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

# Class AbstractGridCoverageResource

Object
AbstractResource
AbstractGridCoverageResource

All Implemented Interfaces:
  `DataSet`, `GridCoverageResource`, `Resource`

public abstract class AbstractGridCoverageResource extends AbstractResource implements GridCoverageResource
Default implementations of several methods for classes that want to implement the `GridCoverageResource` interface. Subclasses should override the following methods:

- `GridCoverageResource​.getGridGeometry()` (mandatory)
- `GridCoverageResource​.getSampleDimensions()` (mandatory)

This class also provides the following helper methods for implementation of the `read(…)` method in subclasses:

- `canNotRead(String, GridGeometry, Throwable)` for reporting a failure to read operation.
- `logReadOperation(Object, GridGeometry, long)` for logging a notice about a read operation.

Since:
  1.2

- ## Field Summary

  ### Fields inherited from class AbstractResource

  `listeners`

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected DataStoreException`
  `canNotRead(String filename, GridGeometry request, Throwable cause)`
  Creates an exception for a failure to load data.
  `protected Metadata`
  `createMetadata()`
  Invoked in a synchronized block the first time that `getMetadata()` is invoked.
  `Optional<Envelope>`
  `getEnvelope()`
  Returns the envelope of the grid geometry if known.
  `protected void`
  `logReadOperation(Object file, GridGeometry domain, long startTime)`
  Logs the execution of a `GridCoverageResource​.read(GridGeometry, int...)` operation.

  ### Methods inherited from class AbstractResource

  `addListener, clearCache, getIdentifier, getMetadata, getSynchronizationLock, removeListener`

  ### Methods inherited from class Object

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

  ### Methods inherited from interface GridCoverageResource

  `getGridGeometry, getLoadingStrategy, getResolutions, getSampleDimensions, read, setLoadingStrategy, subset`

  ### Methods inherited from interface Resource

  `addListener, getIdentifier, getMetadata, removeListener`

- ## Constructor Details

  - ### AbstractGridCoverageResource

    protected AbstractGridCoverageResource(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

  - ### AbstractGridCoverageResource

    protected AbstractGridCoverageResource(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

  - ### getEnvelope

    public Optional<Envelope> getEnvelope() throws DataStoreException
    Returns the envelope of the grid geometry if known. The envelope is absent if the grid geometry does not provide this information.
    Specified by:
      `getEnvelope` in interface `DataSet`
    Overrides:
      `getEnvelope` in class `AbstractResource`
    Returns:
      the grid geometry envelope.
    Throws:
      `DataStoreException` - if an error occurred while computing the grid geometry.
    See Also:
      - `GridGeometry​.getEnvelope()`

  - ### 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()`, `getEnvelope()`, `getGridGeometry()` and `getSampleDimensions()`. Subclasses should override if they can provide more information. The default value can be completed by casting to `DefaultMetadata`.
    Overrides:
      `createMetadata` in class `AbstractResource`
    Returns:
      the newly created metadata, or `null` if unknown.
    Throws:
      `DataStoreException` - if an error occurred while reading metadata from this resource.

  - ### canNotRead

    protected DataStoreException canNotRead(String filename, GridGeometry request, Throwable cause)
    Creates an exception for a failure to load data. The exception sub-type is inferred from the arguments. If the failure is caused by an envelope outside the resource domain, then that envelope will be inferred from the `request` argument.
    Parameters:
      `filename` - some identification (typically a file name) of the data that cannot be read.
      `request` - the requested domain, or `null` if unspecified.
      `cause` - the cause of the failure, or `null` if none.
    Returns:
      the exception to throw.
    See Also:
      - `NoSuchDataException`
      - `DataStoreReferencingException`
      - `DataStoreContentException`

  - ### logReadOperation

    protected void logReadOperation(Object file, GridGeometry domain, long startTime)
    Logs the execution of a `GridCoverageResource​.read(GridGeometry, int...)` operation. The log level will be `Level​.FINE` if the operation was quick enough, or `PerformanceLevel​.SLOWNESS` or higher level otherwise.
    Parameters:
      `file` - the file that was opened, or `null` for `StoreListeners​.getSourceName()`.
      `domain` - domain of the created grid coverage.
      `startTime` - value of `System​.nanoTime()` when the loading process started.