Module org.apache.sis.storage
Package org.apache.sis.storage

# Interface Resource

All Known Subinterfaces:
  `Aggregate`, `DataSet`, `FeatureSet`, `GridCoverageResource`, `TiledResource`, `WritableAggregate`, `WritableFeatureSet`, `WritableGridCoverageResource`, `WritableTiledResource`

All Known Implementing Classes:
  `AbstractFeatureSet`, `AbstractGridCoverageResource`, `AbstractResource`, `ConcatenatedFeatureSet`, `DataStore`, `GeoTiffStore`, `JoinFeatureSet`, `LandsatStore`, `NetcdfStore`, `SQLStore`

public interface Resource
Provides access to geospatial data in a `DataStore`. 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, then `Resource`s should be instances of sub-types like `Aggregate` or `FeatureSet`.

`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 of `Aggregate`. The components of an aggregate can be themselves other aggregates, thus forming a tree.

## Relationship with ISO 19115

This type is closely related to the `DS_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 be seen from the checked `DataStoreException` thrown by most methods. Convenience methods for frequently requested information – for example `DataSet​.getEnvelope()` – were added. The sub-types performing the actual data extraction – for example `FeatureSet` – are specific to Apache SIS.

Since:
  0.8
See Also:
  - `Aggregate​.components()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<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.
  `Optional<GenericName>`
  `getIdentifier()`
  Returns the resource persistent identifier.
  `Metadata`
  `getMetadata()`
  Returns information about this resource.
  `<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.

- ## Method Details

  - ### getIdentifier

    Optional<GenericName> getIdentifier() throws DataStoreException
    Returns the resource persistent identifier. This identifier can be used to uniquely identify a resource in the containing `DataStore`. 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.
    If any of above conditions is not met, then this identifier should be absent. This case may happen when a resource is an intermediate result of an ongoing process or is a temporary resource generated on-the-fly, for example a sensor event.
    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)`

  - ### getMetadata

    Metadata getMetadata() throws DataStoreException
    Returns information about this resource. If this resource is an `Aggregate`, 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 a `DataSet`, 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 for `DataStore​.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 a `DataSet`, or `ScopeCode​.SERVICE` if the resource is a web service, or `ScopeCode​.SERIES` or `ScopeCode​.INITIATIVE` if the resource is an `Aggregate` 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.

    #### Metadata edition

    This method often returns an unmodifiable metadata, for making possible to return efficiently a cached instance. If the caller wants to modify some metadata elements, it may be necessary to perform a deep copy first.
    Returns:
      information about this resource. Should not be `null`.
    Throws:
      `DataStoreException` - if an error occurred while reading the metadata.
    See Also:
      - `DataStore​.getMetadata()`
      - `DefaultMetadata​.deepCopy(Metadata)`

  - ### 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 the `StoreListener​.eventOccured(StoreEvent)` method when new events matching the `eventType` 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 its `StoreListener​.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 events

    If `eventType` is assignable from `WarningEvent.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 the `eventType` argument.
    Parameters:
      `eventType` - type of `StoreEvent`s to listen (cannot be `null`).
      `listener` - listener to notify about events.

  - ### 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. The `eventType` must be the exact same class than the one given to the `addListener(…)` 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, then `removeListener(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 events

    If `eventType` is `WarningEvent.class` and if, after this method invocation, there are no remaining listeners for warning events, then this `Resource` will send future warnings to the loggers.
    Type Parameters:
      `T` - compile-time value of the `eventType` argument.
    Parameters:
      `eventType` - type of `StoreEvent`s which were listened (cannot be `null`).
      `listener` - listener to stop notifying about events.