ddf.catalog

Interface CatalogFramework

All Superinterfaces:

Describable

All Known Implementing Classes:

CatalogFrameworkImpl

public interface CatalogFramework
extends Describable

The CatalogFramework functions as the routing mechanism between all catalog components. It decouples clients from service implementations and provides integration points for Catalog Plugins.

General, high-level flow:

• An endpoint will invoke the active CatalogFramework, typically via an OSGi dependency injection framework such as Blueprint
• For the query, create, delete, update methods, the CatalogFramework calls all "Pre" Catalog Plugins (either PreQueryPlugin or PreIngestPlugin),
• The active/requested FederationStrategy is invoked, which in turn calls:
  • The active CatalogProvider
  • all ConnectedSources
  • specified FederatedSources
• All "Post" Catalog Plugins (either PostQueryPlugin or PostIngestPlugin),
• The appropriate Response is returned to the calling endpoint.

  Also includes convenience methods endpoints can use to invoke MetacardTransformers and QueryResponseTransformers.

Method Summary

Modifier and Type	Method and Description
CreateResponse	create(CreateRequest createRequest) Creates Metacards in the CatalogProvider.
CreateResponse	create(CreateStorageRequest createRequest) This code is experimental.
DeleteResponse	delete(DeleteRequest deleteRequest) Deletes Metacards with Attributes matching a specified value.
ResourceResponse	getEnterpriseResource(ResourceRequest request) Evaluate a ResourceRequest against the local CatalogProvider and RemoteSources.
Map<String,Set<String>>	getEnterpriseResourceOptions(String metacardId) Deprecated. will be removed in the next release
ResourceResponse	getLocalResource(ResourceRequest request) Evaluate a ResourceRequest using available ResourceReaders (does not attempt to locate the resource via federation).
Map<String,Set<String>>	getLocalResourceOptions(String metacardId) Deprecated. Will be removed in the next release.
ResourceResponse	getResource(ResourceRequest request, String resourceSiteName) Evaluate a ResourceRequest using the specified site name.
Map<String,Set<String>>	getResourceOptions(String metacardId, String sourceId) Deprecated. Will be removed in the next release.
Set<String>	getSourceIds() Return the set of source IDs known to the CatalogFramework.
SourceInfoResponse	getSourceInfo(SourceInfoRequest sourceInfoRequest) Returns information for each Source that is endpoint-addressable in CatalogFramework, including its own CatalogProvider, based on the contents of the SourceInfoRequest.
QueryResponse	query(QueryRequest query) Evaluates a QueryRequest using the default FederationStrategy
QueryResponse	query(QueryRequest queryRequest, FederationStrategy strategy) Evaluates and executes a QueryRequest using the FederationStrategy provided.
BinaryContent	transform(Metacard metacard, String transformerId, Map<String,Serializable> requestProperties) Transforms the provided Metacard into BinaryContent.
BinaryContent	transform(SourceResponse response, String transformerId, Map<String,Serializable> requestProperties) Transforms the provided SourceResponse (or QueryResponse) into BinaryContent.
UpdateResponse	update(UpdateRequest updateRequest) Updates a list of Metacards.
UpdateResponse	update(UpdateStorageRequest updateRequest) This code is experimental.

Methods inherited from interface ddf.catalog.util.Describable

getDescription, getId, getOrganization, getTitle, getVersion

Method Detail

create

CreateResponse create(CreateStorageRequest createRequest)
               throws IngestException,
                      SourceUnavailableException

This code is experimental. While this interface is functional and tested, it may change or be removed in a future version of the library. Creates Metacards in the CatalogProvider.

Implementations of this method must:

1. Before evaluation, call PreIngestPlugin.process(CreateRequest) for each registered PreIngestPlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.
2. Call CatalogProvider.create(CreateRequest) on the registered CatalogProvider
3. Call PostIngestPlugin.process(CreateResponse) for each registered PostIngestPlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.
4. Call PreCreateStoragePlugin.process(CreateStorageRequest) for each registered PreCreateStoragePlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.
5. Call StorageProvider.create(CreateStorageRequest) on the registered CatalogProvider
6. Call PostCreateStoragePlugin.process(ddf.catalog.content.operation.CreateStorageResponse) for each registered PostCreateStoragePlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.

Parameters:

createRequest - the CreateStorageRequest

Returns:

CreateResponse

Throws:

IngestException - if an issue occurs during the update

SourceUnavailableException - if the source being updated is unavailable

create

CreateResponse create(CreateRequest createRequest)
               throws IngestException,
                      SourceUnavailableException

Creates Metacards in the CatalogProvider.

Implementations of this method must:

1. Before evaluation, call PreIngestPlugin.process(CreateRequest) for each registered PreIngestPlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.
2. Call CatalogProvider.create(CreateRequest) on the registered CatalogProvider
3. Call PostIngestPlugin.process(CreateResponse) for each registered PostIngestPlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.

Parameters:

createRequest - the CreateRequest

Returns:

CreateResponse

Throws:

IngestException - if an issue occurs during the update

SourceUnavailableException - if the source being updated is unavailable

delete

DeleteResponse delete(DeleteRequest deleteRequest)
               throws IngestException,
                      SourceUnavailableException

Deletes Metacards with Attributes matching a specified value.

Implementations of this method must:

1. Before evaluation, call PreIngestPlugin.process(DeleteRequest) for each registered PreIngestPlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.
2. Call CatalogProvider.delete(DeleteRequest) on the registered CatalogProvider
3. Call PostIngestPlugin.process(DeleteResponse) for each registered PostIngestPlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.

Parameters:

deleteRequest - the DeleteRequest

Returns:

DeleteResponse

Throws:

IngestException - if an issue occurs during the deletion

SourceUnavailableException - if the source being updated is unavailable

getEnterpriseResource

ResourceResponse getEnterpriseResource(ResourceRequest request)
                                throws IOException,
                                       ResourceNotFoundException,
                                       ResourceNotSupportedException

Evaluate a ResourceRequest against the local CatalogProvider and RemoteSources.

Implementations of this method must:

1. Before evaluation, call PreResourcePlugin.process(ResourceRequest) for each registered PreResourcePlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.
2. If not provided with a java.net.URI ( ResourceRequest.GET_RESOURCE_BY_PRODUCT_URI.equals(ResourceRequest.getAttributeName())==false ) , retrieve the matching Metacard and get its Product java.net.URI.
3. Locate the ResourceReader that supports the URI.getScheme() of the java.net.URI on the OSGi Registry.
4. Call ResourceReader.retrieveResource(java.net.URI, Map)
5. Call PostResourcePlugin.process(ResourceResponse) for each registered PostResourcePlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.

Parameters:

request - the ResourceRequest

Returns:

ResourceResponse

Throws:

IOException - if there was a problem communicating with the system containing the resource

ResourceNotFoundException - if the requested resource was not found

ResourceNotSupportedException - if the scheme used in the associated java.net.URI is not supported by this CatalogFramework

getEnterpriseResourceOptions

Map<String,Set<String>> getEnterpriseResourceOptions(String metacardId)
                                              throws ResourceNotFoundException

Deprecated. will be removed in the next release

Search for a Metacard in the enterprise and retrieve arguments that can be used in the retrieval of its associated Resource

Parameters:

metacardId - the ID of the Metacard

Returns:

Map of supported options with argument name for using those options

Throws:

ResourceNotFoundException - if the Metacard is not found or there is no Resource associated with the Metacard

getLocalResource

ResourceResponse getLocalResource(ResourceRequest request)
                           throws IOException,
                                  ResourceNotFoundException,
                                  ResourceNotSupportedException

Evaluate a ResourceRequest using available ResourceReaders (does not attempt to locate the resource via federation).

Implementations of this method must:

1. Before evaluation, call PreResourcePlugin.process(ResourceRequest) for each registered PreResourcePlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.
2. If not provided with a java.net.URI ( ResourceRequest.GET_RESOURCE_BY_PRODUCT_URI.equals(ResourceRequest.getAttributeName())==false ) , retrieve the matching Metacard and get its Product java.net.URI.
3. Locate the ResourceReader that supports the URI.getScheme() of the java.net.URI on the OSGi Registry.
4. Call ResourceReader.retrieveResource(java.net.URI, Map)
5. Call PostResourcePlugin.process(ResourceResponse) for each registered PostResourcePlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.

Parameters:

request - the ResourceRequest

Returns:

ResourceResponse

Throws:

IOException - if there was a problem communicating with the system containing the resource

ResourceNotFoundException - if the requested resource was not found

ResourceNotSupportedException - if the scheme used in the associated java.net.URI is not supported by this CatalogFramework

getLocalResourceOptions

Map<String,Set<String>> getLocalResourceOptions(String metacardId)
                                         throws ResourceNotFoundException

Deprecated. Will be removed in the next release.

Search for a Metacard locally and retrieve arguments that can be used in the retrieval of its associated Resource.

Parameters:

metacardId - the ID of the Metacard

Returns:

Map of supported options with argument name for using those options

Throws:

ResourceNotFoundException - if the Metacard is not found or there is no Resource associated with the Metacard

getResource

ResourceResponse getResource(ResourceRequest request,
                             String resourceSiteName)
                      throws IOException,
                             ResourceNotFoundException,
                             ResourceNotSupportedException

Evaluate a ResourceRequest using the specified site name.

Implementations of this method must:

1. Before evaluation, call PreResourcePlugin.process(ResourceRequest) for each registered PreResourcePlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.
2. If not provided with a java.net.URI ( ResourceRequest.GET_RESOURCE_BY_PRODUCT_URI.equals(ResourceRequest.getAttributeName())==false ) , retrieve the matching Metacard and get its Product java.net.URI.
3. Locate the ResourceReader that supports the URI.getScheme() of the java.net.URI on the OSGi Registry.
4. Call ResourceReader.retrieveResource(java.net.URI, Map)
5. Call PostResourcePlugin.process(ResourceResponse) for each registered PostResourcePlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.

Parameters:

request - the ResourceRequest

resourceSiteName - name of the site/source to retrieve the resource from

Returns:

ResourceResponse

Throws:

IOException - if there was a problem communicating with the system containing the resource

ResourceNotFoundException - if the requested resource was not found

ResourceNotSupportedException - if the scheme used in the associated java.net.URI is not supported by this CatalogFramework

getResourceOptions

Map<String,Set<String>> getResourceOptions(String metacardId,
                                           String sourceId)
                                    throws ResourceNotFoundException

Deprecated. Will be removed in the next release.

Search for a Metacard on specified Source and retrieve arguments that can be used in the retrieval of its associated Resource

Parameters:

metacardId - the ID of the metacard

sourceId - the ID of the source to retrieve the metacard from

Returns:

Map of supported options with argument name for using those options

Throws:

ResourceNotFoundException - if the Metacard is not found or there is no Resource associated with the Metacard

getSourceIds

Set<String> getSourceIds()

Return the set of source IDs known to the CatalogFramework. This set includes the local provider and any federated sources, but not connected sources as they are hidden from external clients.

Returns:

Set of source IDs

getSourceInfo

SourceInfoResponse getSourceInfo(SourceInfoRequest sourceInfoRequest)
                          throws SourceUnavailableException

Returns information for each Source that is endpoint-addressable in CatalogFramework, including its own CatalogProvider, based on the contents of the SourceInfoRequest.

The SourceInfoRequest specifies either:

1. an enterprise source search, which includes the catalog provider and all federated and connected sources
2. a list of requested source IDs, which are all federated sources
3. the catalog provider only

Parameters:

sourceInfoRequest - the SourceInfoRequest

Returns:

SourceInfoResponse

Throws:

SourceUnavailableException - if the source indicated in the SourceInfoRequest is null, not found, or cannot provide the requested information

query

QueryResponse query(QueryRequest query)
             throws UnsupportedQueryException,
                    SourceUnavailableException,
                    FederationException

Evaluates a QueryRequest using the default FederationStrategy

Implementations of this method must:

1. Before evaluation, call PreQueryPlugin.process(QueryRequest) for each registered PreQueryPlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.
2. Call Source.query(QueryRequest) on the registered CatalogProvider
3. Call Source.query(QueryRequest) on all registered ConnectedSources
4. If applicable, invoke the default FederationStrategy which will call Source.query(QueryRequest) on all registered FederatedSources
5. Before returning, call PostQueryPlugin.process(QueryResponse) for each registered PostQueryPlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.
6. Return the last QueryResponse to the caller.

Important: Implementations are free to limit the number of results returned regardless of the page size requested in the QueryRequest. For that reason, clients should not assume that the number of results returned matches the page size requested and write their paging code accordingly. If the QueryResponse does not need to be used, it is highly recommended that clients use an iterable class such as ResultIterable to retrieve and process results. If partitioning of results is required clients may use Guavas Iterables.partition(Iterable, int) method.

Parameters:

query - the QueryRequest

Returns:

QueryResponse the resulting response

Throws:

UnsupportedQueryException - if the provided query can not be interpreted by a required Source

SourceUnavailableException - if a required Source is not available

FederationException - if federation is requested but can not complete, usually due to the FederationStrategy

See Also:

query(QueryRequest, FederationStrategy)

query

QueryResponse query(QueryRequest queryRequest,
                    FederationStrategy strategy)
             throws SourceUnavailableException,
                    UnsupportedQueryException,
                    FederationException

Evaluates and executes a QueryRequest using the FederationStrategy provided.

Implementations of this method must implement all of the rules defined in query(QueryRequest), but use the specified FederationStrategy

Important: Implementations are free to limit the number of results returned regardless of the page size requested in the QueryRequest. For that reason, clients should not assume that the number of results returned matches the page size requested and write their paging code accordingly. If the QueryResponse does not need to be used, it is highly recommended that clients use an iterable class such as ResultIterable to retrieve and process results. If partitioning of results is required clients may use Guavas Iterables.partition(Iterable, int) method.

Parameters:

queryRequest - the QueryRequest

strategy - the FederationStrategy to use

Returns:

QueryResponse the resulting response

Throws:

SourceUnavailableException - if a required Source is unavailable

UnsupportedQueryException - if the Query can not be evaluated by this CatalogFramework or any of its Sources.

FederationException - if the QueryRequest includes FederatedSources and there is either a problem connecting to a FederatedSource or a FederatedSource cannot evaluate the Query

transform

BinaryContent transform(Metacard metacard,
                        String transformerId,
                        Map<String,Serializable> requestProperties)
                 throws CatalogTransformerException

Transforms the provided Metacard into BinaryContent. The transformerId is used to uniquely identify the MetacardTransformer desired.

Parameters:

metacard - the Metacard to be transformed

transformerId - the id of the MetacardTransformer desired, as registered with the OSGi Service Registry.

requestProperties - to be used by the the transformer, if applicable

Returns:

BinaryContent the transformed Metacard

Throws:

CatalogTransformerException - if there is a problem transforming the Metacard

transform

BinaryContent transform(SourceResponse response,
                        String transformerId,
                        Map<String,Serializable> requestProperties)
                 throws CatalogTransformerException

Transforms the provided SourceResponse (or QueryResponse) into BinaryContent. The transformerId is used to uniquely identify the QueryResponseTransformer desired.

Parameters:

response - the SourceResponse to be transformed

transformerId - the id of the transformer

requestProperties - to be used by the the transformer, if applicable

Returns:

BinaryContent the transformed SourceResponse

Throws:

CatalogTransformerException - if there is a problem transforming the SourceResponse

update

UpdateResponse update(UpdateStorageRequest updateRequest)
               throws IngestException,
                      SourceUnavailableException

This code is experimental. While this interface is functional and tested, it may change or be removed in a future version of the library. Updates a list of Metacards. Metacards that are not in the Catalog will not be created.

If a Metacard in the list to be updated does not have its ID attribute set, then the associated ID for that Metacard in the UpdateRequest will be used.

Implementations of this method must:

1. Before evaluation, call PreIngestPlugin.process(UpdateRequest) for each registered PreIngestPlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.
2. Call CatalogProvider.update(UpdateRequest) on the registered CatalogProvider
3. Call PostIngestPlugin.process(UpdateResponse) for each registered PostIngestPlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.
4. Call PreUpdateStoragePlugin.process(UpdateStorageRequest) for each registered PreUpdateStoragePlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.
5. Call StorageProvider.update(UpdateStorageRequest) on the registered CatalogProvider
6. Call PostUpdateStoragePlugin.process(ddf.catalog.content.operation.UpdateStorageResponse) for each registered PostUpdateStoragePlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.

Parameters:

updateRequest - the UpdateStorageRequest

Returns:

UpdateResponse

Throws:

IngestException - if an issue occurs during the update

SourceUnavailableException - if the source being updated is unavailable

update

UpdateResponse update(UpdateRequest updateRequest)
               throws IngestException,
                      SourceUnavailableException

Updates a list of Metacards. Metacards that are not in the Catalog will not be created.

If a Metacard in the list to be updated does not have its ID attribute set, then the associated ID for that Metacard in the UpdateRequest will be used.

Implementations of this method must:

1. Before evaluation, call PreIngestPlugin.process(UpdateRequest) for each registered PreIngestPlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.
2. Call CatalogProvider.update(UpdateRequest) on the registered CatalogProvider
3. Call PostIngestPlugin.process(UpdateResponse) for each registered PostIngestPlugin in order determined by the OSGi SERVICE_RANKING (Descending, highest first), "daisy chaining" their responses to each other.

Parameters:

updateRequest - the UpdateRequest

Returns:

UpdateResponse

Throws:

IngestException - if an issue occurs during the update

SourceUnavailableException - if the source being updated is unavailable