public interface CatalogFramework extends Describable
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:
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:
CatalogProvider
ConnectedSource
s
FederatedSource
s
PostQueryPlugin
or PostIngestPlugin
),
The appropriate Response
is returned to the calling
endpoint.
Also includes convenience methods endpoints can use to invoke MetacardTransformer
s and QueryResponseTransformer
s.
Modifier and Type | Method and Description |
---|---|
CreateResponse |
create(CreateRequest createRequest)
Creates
Metacard s in the CatalogProvider . |
CreateResponse |
create(CreateStorageRequest createRequest)
This code is experimental.
|
DeleteResponse |
delete(DeleteRequest deleteRequest)
|
ResourceResponse |
getEnterpriseResource(ResourceRequest request)
|
Map<String,Set<String>> |
getEnterpriseResourceOptions(String metacardId)
Deprecated.
will be removed in the next release
|
ResourceResponse |
getLocalResource(ResourceRequest request)
Evaluate a
ResourceRequest using available ResourceReader s
(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)
|
UpdateResponse |
update(UpdateRequest updateRequest)
Updates a list of Metacards.
|
UpdateResponse |
update(UpdateStorageRequest updateRequest)
This code is experimental.
|
getDescription, getId, getOrganization, getTitle, getVersion
CreateResponse create(CreateStorageRequest createRequest) throws IngestException, SourceUnavailableException
Metacard
s in the CatalogProvider
.
Implementations of this method must:
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.
Call CatalogProvider.create(CreateRequest)
on the registered
CatalogProvider
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.
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.
Call StorageProvider.create(CreateStorageRequest)
on the
registered CatalogProvider
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.
createRequest
- the CreateStorageRequest
CreateResponse
IngestException
- if an issue occurs during the updateSourceUnavailableException
- if the source being updated is unavailableCreateResponse create(CreateRequest createRequest) throws IngestException, SourceUnavailableException
Metacard
s in the CatalogProvider
.
Implementations of this method must:
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.
Call CatalogProvider.create(CreateRequest)
on the registered
CatalogProvider
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.
createRequest
- the CreateRequest
CreateResponse
IngestException
- if an issue occurs during the updateSourceUnavailableException
- if the source being updated is unavailableDeleteResponse delete(DeleteRequest deleteRequest) throws IngestException, SourceUnavailableException
Metacard
s with Attribute
s matching a specified value.
Implementations of this method must:
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.
Call CatalogProvider.delete(DeleteRequest)
on the registered
CatalogProvider
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.
deleteRequest
- the DeleteRequest
DeleteResponse
IngestException
- if an issue occurs during the deletionSourceUnavailableException
- if the source being updated is unavailableResourceResponse getEnterpriseResource(ResourceRequest request) throws IOException, ResourceNotFoundException, ResourceNotSupportedException
ResourceRequest
against the local CatalogProvider
and RemoteSource
s.
Implementations of this method must:
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.
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.
Locate the ResourceReader
that supports the URI.getScheme()
of the java.net.URI on the OSGi Registry.
Call ResourceReader.retrieveResource(java.net.URI, Map)
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.
request
- the ResourceRequest
ResourceResponse
IOException
- if there was a problem communicating with the system containing the
resourceResourceNotFoundException
- if the requested resource was not foundResourceNotSupportedException
- if the scheme used in the associated java.net.URI is not
supported by this CatalogFramework
Map<String,Set<String>> getEnterpriseResourceOptions(String metacardId) throws ResourceNotFoundException
Metacard
in the enterprise and retrieve arguments that can be used in the
retrieval of its associated ResourcemetacardId
- the ID of the Metacard
ResourceNotFoundException
- if the Metacard
is not found or there is no Resource
associated with the Metacard
ResourceResponse getLocalResource(ResourceRequest request) throws IOException, ResourceNotFoundException, ResourceNotSupportedException
ResourceRequest
using available ResourceReader
s
(does not attempt to locate the resource via federation).
Implementations of this method must:
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.
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.
Locate the ResourceReader
that supports the URI.getScheme()
of the java.net.URI on the OSGi Registry.
Call ResourceReader.retrieveResource(java.net.URI, Map)
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.
request
- the ResourceRequest
ResourceResponse
IOException
- if there was a problem communicating with the system containing the
resourceResourceNotFoundException
- if the requested resource was not foundResourceNotSupportedException
- if the scheme used in the associated java.net.URI is not
supported by this CatalogFramework
Map<String,Set<String>> getLocalResourceOptions(String metacardId) throws ResourceNotFoundException
Metacard
locally and retrieve arguments that can be used in the retrieval
of its associated Resource.metacardId
- the ID of the Metacard
ResourceNotFoundException
- if the Metacard
is not found or there is no Resource
associated with the Metacard
ResourceResponse getResource(ResourceRequest request, String resourceSiteName) throws IOException, ResourceNotFoundException, ResourceNotSupportedException
ResourceRequest
using the specified site name.
Implementations of this method must:
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.
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.
Locate the ResourceReader
that supports the URI.getScheme()
of the java.net.URI on the OSGi Registry.
Call ResourceReader.retrieveResource(java.net.URI, Map)
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.
request
- the ResourceRequest
resourceSiteName
- name of the site/source to retrieve the resource fromResourceResponse
IOException
- if there was a problem communicating with the system containing the
resourceResourceNotFoundException
- if the requested resource was not foundResourceNotSupportedException
- if the scheme used in the associated java.net.URI is not
supported by this CatalogFramework
Map<String,Set<String>> getResourceOptions(String metacardId, String sourceId) throws ResourceNotFoundException
Metacard
on specified Source
and retrieve
arguments that can be used in the retrieval of its associated ResourcemetacardId
- the ID of the metacardsourceId
- the ID of the source to retrieve the metacard fromResourceNotFoundException
- if the Metacard
is not found or there is no Resource
associated with the Metacard
Set<String> getSourceIds()
CatalogFramework
. This set includes the local
provider and any federated sources, but not connected sources as they are hidden from external
clients.SourceInfoResponse getSourceInfo(SourceInfoRequest sourceInfoRequest) throws SourceUnavailableException
Source
that is endpoint-addressable in
CatalogFramework
, including its own CatalogProvider
, based
on the contents of the SourceInfoRequest
.
The SourceInfoRequest
specifies either:
sourceInfoRequest
- the SourceInfoRequest
SourceInfoResponse
SourceUnavailableException
- if the source indicated in the SourceInfoRequest
is
null
, not found, or cannot provide the requested informationQueryResponse query(QueryRequest query) throws UnsupportedQueryException, SourceUnavailableException, FederationException
QueryRequest
using the default FederationStrategy
Implementations of this method must:
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.
Call Source.query(QueryRequest)
on the registered
CatalogProvider
Call Source.query(QueryRequest)
on all registered
ConnectedSource
s
If applicable, invoke the default FederationStrategy
which will call Source.query(QueryRequest)
on all registered FederatedSource
s
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.
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.
query
- the QueryRequest
QueryResponse
the resulting responseUnsupportedQueryException
- if the provided query can not be interpreted by a required
Source
SourceUnavailableException
- if a required Source
is not
availableFederationException
- if federation is requested but can not complete, usually due to the
FederationStrategy
query(QueryRequest, FederationStrategy)
QueryResponse query(QueryRequest queryRequest, FederationStrategy strategy) throws SourceUnavailableException, UnsupportedQueryException, FederationException
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.
queryRequest
- the QueryRequest
strategy
- the FederationStrategy
to useQueryResponse
the resulting responseSourceUnavailableException
- if a required Source
is
unavailableUnsupportedQueryException
- if the Query
can not be
evaluated by this CatalogFramework
or any of its Source
s.FederationException
- if the QueryRequest
includes FederatedSource
s and there is either a problem connecting to a FederatedSource
or a FederatedSource
cannot
evaluate the Query
BinaryContent transform(Metacard metacard, String transformerId, Map<String,Serializable> requestProperties) throws CatalogTransformerException
Metacard
into BinaryContent
. The transformerId is used
to uniquely identify the MetacardTransformer
desired.metacard
- the Metacard
to be transformedtransformerId
- the id of the MetacardTransformer
desired,
as registered with the OSGi Service Registry.requestProperties
- to be used by the the transformer, if applicableBinaryContent
the transformed Metacard
CatalogTransformerException
- if there is a problem transforming the Metacard
BinaryContent transform(SourceResponse response, String transformerId, Map<String,Serializable> requestProperties) throws CatalogTransformerException
SourceResponse
(or QueryResponse
) into BinaryContent
. The transformerId is used to uniquely identify the QueryResponseTransformer
desired.response
- the SourceResponse
to be transformedtransformerId
- the id of the transformerrequestProperties
- to be used by the the transformer, if applicableBinaryContent
the transformed SourceResponse
CatalogTransformerException
- if there is a problem transforming the SourceResponse
UpdateResponse update(UpdateStorageRequest updateRequest) throws IngestException, SourceUnavailableException
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:
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.
Call CatalogProvider.update(UpdateRequest)
on the registered
CatalogProvider
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.
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.
Call StorageProvider.update(UpdateStorageRequest)
on the
registered CatalogProvider
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.
updateRequest
- the UpdateStorageRequest
UpdateResponse
IngestException
- if an issue occurs during the updateSourceUnavailableException
- if the source being updated is unavailableUpdateResponse update(UpdateRequest updateRequest) throws IngestException, SourceUnavailableException
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:
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.
Call CatalogProvider.update(UpdateRequest)
on the registered
CatalogProvider
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.
updateRequest
- the UpdateRequest
UpdateResponse
IngestException
- if an issue occurs during the updateSourceUnavailableException
- if the source being updated is unavailableThis work is licensed under a Creative Commons Attribution 4.0 International License.