Interface Resource
-
- All Known Subinterfaces:
Aggregate
,DataSet
,FeatureSet
,GridCoverageResource
,WritableAggregate
,WritableFeatureSet
- All Known Implementing Classes:
DataStore
,GeoTiffStore
,LandsatStore
,NetcdfStore
,SQLStore
public interface Resource
Provides access to geospatial data in aDataStore
. The ISO 19115 specification defines resource as an “identifiable asset or means that fulfills a requirement”. For example a resource can be a coverage of Sea Surface Temperature, or a coverage of water salinity, or the set of all buoys in a harbor, or an aggregation of all the above. A resource is not necessarily digital; it can be a paper document or an organization, in which case only metadata are provided. If the resource is digital, thenResource
s should be instances of sub-types likeAggregate
orFeatureSet
.DataStore
s are themselves closeable resources. If the data store contains resources for many feature types or coverages, then the data store will be an instance ofAggregate
. The components of an aggregate can be themselves other aggregates, thus forming a tree.Relationship with ISO 19115: this type is closely related to theDS_Resource
type defined by ISO 19115. The Apache SIS type differs from the ISO type by being more closely related to data extraction, as can been seen from the checkedDataStoreException
thrown by most methods. Convenience methods for frequently requested information – for exampleDataSet.getEnvelope()
– were added. The sub-types performing the actual data extraction – for exampleFeatureSet
– are specific to Apache SIS.- Since:
- 0.8
- See Also:
Aggregate.components()
Defined in the
sis-storage
module
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description <T extends StoreEvent>
voidaddListener(Class<T> eventType, StoreListener<? super T> listener)
Registers a listener to notify when the specified kind of event occurs in this resource or in children.Optional<GenericName>
getIdentifier()
Returns the resource persistent identifier.Metadata
getMetadata()
Returns information about this resource.<T extends StoreEvent>
voidremoveListener(Class<T> eventType, StoreListener<? super T> listener)
Unregisters a listener previously added to this resource for the given type of events.
-
-
-
Method Detail
-
getIdentifier
Optional<GenericName> getIdentifier() throws DataStoreException
Returns the resource persistent identifier. This identifier can be used to uniquely identify a resource in the containingDataStore
. For this identifier to be reliable the following conditions must hold:- It shall be unique in the
DataStore
which contains it, if there is one. - It's value shall not change after closing and reopening the
DataStore
on the same data. - It should be consistent with the
getMetadata()/identificationInfo/citation/identifier
value.
- Returns:
- a persistent identifier unique within the data store, or absent if this resource has no such identifier.
- Throws:
DataStoreException
- if an error occurred while fetching the identifier.- Since:
- 1.0
- See Also:
DataStore.getIdentifier()
,DataStore.findResource(String)
- It shall be unique in the
-
getMetadata
Metadata getMetadata() throws DataStoreException
Returns information about this resource. If this resource is anAggregate
, then the metadata may enumerate characteristics (spatiotemporal extents, feature types, range dimensions, etc.) of all components in the aggregate, or summarize them (for example by omitting extents that are fully included in larger extents). If this resource is aDataSet
, then the metadata shall contain only the information that apply to that particular dataset, optionally with a reference to the parent metadata (see below).Some relationships between metadata and resources are:
metadata
/parentMetadata
/title
:
a human-readable caption forDataStore.getMetadata()
(if not redundant with this metadata).metadata
/identificationInfo
/citation
/title
:
a human-readable designation for this resource.metadata
/identificationInfo
/associatedResource
/name
/title
:
a human-readable designation for parent, children or other related resources. May be omitted if too expensive to compute.metadata
/metadataScope
/resourceScope
:
ScopeCode.DATASET
if the resource is aDataSet
, orScopeCode.SERVICE
if the resource is a web service, orScopeCode.SERIES
orScopeCode.INITIATIVE
if the resource is anAggregate
other than a transfer aggregate.metadata
/contentInfo
/featureType
/featureTypeName
:
names of feature types included in this resource. Example: “bridge”, “road”, “river”. etc.metadata
/contentInfo
/attributeGroup
/attribute
/sequenceIdentifier
:
sample dimension names (or band numbers in simpler cases) of coverages or rasters included in this resource.
- Returns:
- information about this resource. Should not be
null
. - Throws:
DataStoreException
- if an error occurred while reading the metadata.- See Also:
DataStore.getMetadata()
-
addListener
<T extends StoreEvent> void addListener(Class<T> eventType, StoreListener<? super T> listener)
Registers a listener to notify when the specified kind of event occurs in this resource or in children. The resource will call theStoreListener.eventOccured(StoreEvent)
method when new events matching theeventType
occur. An event may be a change in resource content or structure, or a warning that occurred during a read or write operation.Registering a listener for a given
eventType
also register the listener for all event sub-types. The same listener can be registered many times, but itsStoreListener.eventOccured(StoreEvent)
method will be invoked only once per event. This filtering applies even if the listener is registered on different resources in the same tree, for example a parent and its children.If this resource may produce events of the given type, then the given listener is kept by strong reference; it will not be garbage collected unless explicitly removed or unless this
Resource
is itself garbage collected. However if the given type of events can never happen with this resource, then this method is not required to keep a reference to the given listener.Warning eventsIfeventType
is assignable fromWarningEvent.class
, then registering that listener turns off logging of warning messages for this resource. This side-effect is applied on the assumption that the registered listener will handle warnings in its own way, for example by showing warnings in a widget.- Type Parameters:
T
- compile-time value of theeventType
argument.- Parameters:
listener
- listener to notify about events.eventType
- type ofStoreEvent
to listen (can not benull
).
-
removeListener
<T extends StoreEvent> void removeListener(Class<T> eventType, StoreListener<? super T> listener)
Unregisters a listener previously added to this resource for the given type of events. TheeventType
must be the exact same class than the one given to theaddListener(…)
method; this method does not remove listeners registered for subclasses and does not remove listeners registered in parent resources.If the same listener has been registered many times for the same even type, then this method removes only the most recent registration. In other words if
addListener(type, ls)
has been invoked twice, thenremoveListener(type, ls)
needs to be invoked twice in order to remove all instances of that listener. If the given listener is not found, then this method does nothing (no exception is thrown).Warning eventsIfeventType
isWarningEvent.class
and if, after this method invocation, there is no remaining listener for warning events, then thisResource
will send future warnings to the loggers.- Type Parameters:
T
- compile-time value of theeventType
argument.- Parameters:
listener
- listener to stop notifying about events.eventType
- type ofStoreEvent
which were listened (can not benull
).
-
-