# 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:

- `Resource​.getIdentifier()` (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 will send notifications, directly or indirectly, 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.
  `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, getIdentifier`

- ## 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`. Invoking this constructor is equivalent (except for null checks) to invoking ``AbstractResource`(parent.listeners, false)`.
    Parameters:
      `parent` - the parent resource, or `null` if none.
    Since:
      1.4

  - ### AbstractResource

    protected AbstractResource(StoreListeners parentListeners, boolean hidden)
    Creates a new resource which will send notifications, directly or indirectly, to the given set of listeners. The `hidden` argument specifies whether the new resource should be invisible in the tree of resources. The caller may want to hide a resource if, for example, it is a decorator that delegates most of its work to the real resource.

    The `hidden` argument works as below: if `true`, then the `parentListeners` argument will be assigned directly to the `listeners` field, unless that argument is `null`. Consequently, any event sent by this resources will appear to the users as if the event was sent by the parent resource. Conversely if `false`, then this resource will have its own set of listeners with this resource declared as the source of events. In the latter case, listeners can be added or removed independently from the listeners of the parent resource.

    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

  - ### 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 `Resource​.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.