# Class AbstractResource

Object
AbstractResource

All Implemented Interfaces:
  `Resource`

Direct Known Subclasses:
  `AbstractFeatureSet`, `AbstractGridCoverageResource`

public abstract class AbstractResource extends Object implements Resource
Default implementations of several methods for classes that want to implement the `Resource` interface. This class provides a `getMetadata()` method which extracts information from other methods. Subclasses should override the following methods:

- `getIdentifier()` (strongly recommended)
- `getEnvelope()` (recommended)
- `createMetadata()` (optional)
- `getSynchronizationLock()` (optional)

## Thread safety

Default methods of this abstract class are thread-safe. Synchronization, when needed, uses `getSynchronizationLock()`.

Since:
  1.2

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from interface Resource

  `Resource​.FileSet`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final StoreListeners`
  `listeners`
  The set of registered `StoreListener`s for this resources.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `AbstractResource(StoreListeners parentListeners, boolean hidden)`
  Creates a new resource which can send notifications to the given set of listeners.
  `protected`
  `AbstractResource(Resource parent)`
  Creates a new resource, potentially as a child of another resource.

- ## 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.
  `protected void`
  `clearCache()`
  Clears any cache in this resource, forcing the data to be recomputed when needed again.
  `protected Metadata`
  `createMetadata()`
  Invoked in a synchronized block the first time that `getMetadata()` is invoked.
  `Optional<Envelope>`
  `getEnvelope()`
  Returns the spatiotemporal envelope of this resource.
  `Optional<GenericName>`
  `getIdentifier()`
  Returns the resource persistent identifier if available.
  `final Metadata`
  `getMetadata()`
  Returns a description of this resource.
  `protected Object`
  `getSynchronizationLock()`
  Returns the object on which to perform synchronizations for thread-safety.
  `<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.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface Resource

  `getFileSet`

- ## Field Details

  - ### listeners

    protected final StoreListeners listeners
    The set of registered `StoreListener`s for this resources. This `StoreListeners` has `DataStore​.listeners` has a parent.

- ## Constructor Details

  - ### AbstractResource

    protected AbstractResource(Resource parent)
    Creates a new resource, potentially as a child of another resource. The parent resource is typically, but not necessarily, an `Aggregate`.
    Parameters:
      `parent` - the parent resource, or `null` if none.
    Since:
      1.4

  - ### AbstractResource

    protected AbstractResource(StoreListeners parentListeners, boolean hidden)
    Creates a new resource which can send notifications to the given set of listeners. If `hidden` is `false` (the recommended value), then this resource will have its own set of listeners with this resource declared as the source of events. It will be possible to add and remove listeners independently from the set of parent listeners. Conversely if `hidden` is `true`, then the given listeners will be used directly and this resource will not appear as the source of any event.

    In any cases, the listeners of all parents (ultimately the data store that created this resource) will always be notified, either directly if `hidden` is `true` or indirectly if `hidden` is `false`.

    Parameters:
      `parentListeners` - listeners of the parent resource, or `null` if none. This is usually the listeners of the `DataStore` that created this resource.
      `hidden` - `false` if this resource shall use its own `StoreListeners` with the specified parent, or `true` for using `parentListeners` directly.

- ## Method Details

  - ### getIdentifier

    public Optional<GenericName> getIdentifier() throws DataStoreException
    Returns the resource persistent identifier if available. The default implementation returns an empty value. Subclasses are strongly encouraged to override if they can provide a value.

    #### Relationship with metadata

    The default implementation of `createMetadata()` uses this identifier for initializing the `metadata/identificationInfo/citation/title` property.
    Specified by:
      `getIdentifier` in interface `Resource`
    Returns:
      a persistent identifier unique within the data store.
    Throws:
      `DataStoreException` - if an error occurred while fetching the identifier.
    See Also:
      - `DataStore​.getIdentifier()`
      - `DataStore​.findResource(String)`

  - ### getEnvelope

    public Optional<Envelope> getEnvelope() throws DataStoreException
    Returns the spatiotemporal envelope of this resource. This information is part of API only in some kinds of resource such as `FeatureSet`. But the method is provided in this base class for convenience. The default implementation gives an empty value.

    #### Implementation note

    The default implementation of `createMetadata()` uses this identifier for initializing the `metadata/identificationInfo/extent/geographicElement` property.
    Returns:
      the spatiotemporal resource extent.
    Throws:
      `DataStoreException` - if an error occurred while reading or computing the envelope.

  - ### getMetadata

    public final Metadata getMetadata() throws DataStoreException
    Returns a description of this resource. The implementation invokes `createMetadata()` in a synchronized block when first needed, then caches the result.
    Specified by:
      `getMetadata` in interface `Resource`
    Returns:
      information about this resource (never `null`).
    Throws:
      `DataStoreException` - if an error occurred while reading or computing the metadata.
    See Also:
      - `DataStore​.getMetadata()`
      - `DefaultMetadata​.deepCopy(Metadata)`

  - ### createMetadata

    protected Metadata createMetadata() throws DataStoreException
    Invoked in a synchronized block the first time that `getMetadata()` is invoked. The default implementation populates metadata based on information provided by `getIdentifier()` and `getEnvelope()`. Subclasses should override if they can provide more information. The default value can be completed by casting to `DefaultMetadata`.
    Returns:
      the newly created metadata, or `null` if unknown.
    Throws:
      `DataStoreException` - if an error occurred while reading metadata from this resource.

  - ### clearCache

    protected void clearCache()
    Clears any cache in this resource, forcing the data to be recomputed when needed again. The default implementation clears the cached metadata object, which will cause `createMetadata()` to be invoked again when first needed.

  - ### getSynchronizationLock

    protected Object getSynchronizationLock()
    Returns the object on which to perform synchronizations for thread-safety. The default implementation returns `this`. Subclasses can override for example for synchronizing everything on an enclosing `DataStore`.
    Returns:
      the synchronization lock.

  - ### addListener

    public <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 default implementation forwards to `listeners.addListener(eventType, listener)`.
    Specified by:
      `addListener` in interface `Resource`
    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

    public <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 default implementation forwards to `listeners.removeListener(eventType, listener)`
    Specified by:
      `removeListener` in interface `Resource`
    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.