Package org.apache.sis.storage.geotiff

# Class GeoTiffStore

Object
DataStore
GeoTiffStore

All Implemented Interfaces:
  `AutoCloseable`, `Aggregate`, `Resource`, `Localized`

public class GeoTiffStore extends DataStore implements Aggregate
A data store backed by GeoTIFF files.

Since:
  0.8

Defined in the `sis-geotiff` module

- ## Field Summary

  ### Fields inherited from class DataStore

  `listeners, provider`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GeoTiffStore(DataStore parent, DataStoreProvider provider, StorageConnector connector, boolean hidden)`
  Creates a new GeoTIFF store as a component of a larger data store.
  `GeoTiffStore(GeoTiffStoreProvider provider, StorageConnector connector)`
  Creates a new GeoTIFF store from the given file, URL or stream object.

- ## 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 data store.
  `void`
  `close()`
  Closes this GeoTIFF store and releases any underlying resources.
  `List<GridCoverageResource>`
  `components()`
  Returns descriptions of all images in this GeoTIFF file.
  `GridCoverageResource`
  `findResource(String sequence)`
  Returns the image at the given index.
  `Optional<GenericName>`
  `getIdentifier()`
  Returns an identifier constructed from the name of the TIFF file.
  `Metadata`
  `getMetadata()`
  Returns information about the dataset as a whole.
  `Optional<ParameterValueGroup>`
  `getOpenParameters()`
  Returns the parameters used to open this GeoTIFF data store.

  ### Methods inherited from class DataStore

  `getDisplayName, getLocale, getNativeMetadata, getProvider, removeListener, setLocale, toString`

  ### Methods inherited from class Object

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

  ### Methods inherited from interface Resource

  `removeListener`

- ## Constructor Details

  - ### GeoTiffStore

    public GeoTiffStore(GeoTiffStoreProvider provider, StorageConnector connector) throws DataStoreException
    Creates a new GeoTIFF store from the given file, URL or stream object. This constructor invokes `StorageConnector​.closeAllExcept(Object)`, keeping open only the needed resource.
    Parameters:
      `provider` - the factory that created this `DataStore` instance, or `null` if unspecified.
      `connector` - information about the storage (URL, stream, etc).
    Throws:
      `DataStoreException` - if an error occurred while opening the GeoTIFF file.

  - ### GeoTiffStore

    public GeoTiffStore(DataStore parent, DataStoreProvider provider, StorageConnector connector, boolean hidden) throws DataStoreException
    Creates a new GeoTIFF store as a component of a larger data store.
    Example: A Landsat data set is a collection of files in a directory or ZIP file, which includes more than 10 GeoTIFF files (one image per band or product for a scene). `LandsatStore` is a data store opening the Landsat metadata file as the main file, then opening each band/product using a GeoTIFF data store. Those bands/products are components of the Landsat data store.
    If the `hidden` parameter is `true`, some metadata that would normally be provided in this `GeoTiffStore` will be provided by individual components instead.
    Parameters:
      `parent` - the parent that contains this new GeoTIFF store component, or `null` if none.
      `provider` - the factory that created this `DataStore` instance, or `null` if unspecified.
      `connector` - information about the storage (URL, stream, etc).
      `hidden` - `true` if this GeoTIFF store will not be directly accessible from the parent. It is the case if the parent store will expose only some components instead of the GeoTIFF store itself.
    Throws:
      `DataStoreException` - if an error occurred while opening the GeoTIFF file.
    Since:
      1.1

- ## Method Details

  - ### getOpenParameters

    public Optional<ParameterValueGroup> getOpenParameters()
    Returns the parameters used to open this GeoTIFF data store. The parameters are described by `GeoTiffStoreProvider​.getOpenParameters()` and contains at least a parameter named "location" with a `URI` value. The return value may be empty if the storage input can not be described by a URI (for example a GeoTIFF file reading directly from a `ReadableByteChannel`).
    Specified by:
      `getOpenParameters` in class `DataStore`
    Returns:
      parameters used for opening this data store.
    See Also:
      - `DataStoreProvider​.getOpenParameters()`

  - ### getIdentifier

    public Optional<GenericName> getIdentifier() throws DataStoreException
    Returns an identifier constructed from the name of the TIFF file. An identifier is available only if the storage input specified at construction time was something convertible to `URI`, for example an `URL`, `File` or `Path`.
    Specified by:
      `getIdentifier` in interface `Resource`
    Overrides:
      `getIdentifier` in class `DataStore`
    Returns:
      the identifier derived from the filename.
    Throws:
      `DataStoreException` - if an error occurred while fetching the identifier.
    Since:
      1.0
    See Also:
      - `DataStore​.getMetadata()`
      - `DataStore​.getDisplayName()`

  - ### getMetadata

    public Metadata getMetadata() throws DataStoreException
    Returns information about the dataset as a whole. The returned metadata object can contain information such as the spatiotemporal extent of the dataset, contact information about the creator or distributor, data quality, usage constraints and more.
    Specified by:
      `getMetadata` in interface `Resource`
    Specified by:
      `getMetadata` in class `DataStore`
    Returns:
      information about the dataset.
    Throws:
      `DataStoreException` - if an error occurred while reading the data.
    See Also:
      - `DataStore​.getIdentifier()`
      - `DefaultMetadata​.deepCopy(Metadata)`

  - ### components

    public List<GridCoverageResource> components() throws DataStoreException
    Returns descriptions of all images in this GeoTIFF file. Images are not immediately loaded.

    If an error occurs during iteration in the returned collection, an unchecked `BackingStoreException` will be thrown with a `DataStoreException` as its cause.

    Specified by:
      `components` in interface `Aggregate`
    Returns:
      descriptions of all images in this GeoTIFF file.
    Throws:
      `DataStoreException` - if an error occurred while fetching the image descriptions.
    Since:
      1.0

  - ### findResource

    public GridCoverageResource findResource(String sequence) throws DataStoreException
    Returns the image at the given index. Images numbering starts at 1.
    Overrides:
      `findResource` in class `DataStore`
    Parameters:
      `sequence` - string representation of the image index, starting at 1.
    Returns:
      image at the given index.
    Throws:
      `DataStoreException` - if the requested image can not be obtained.
    See Also:
      - `Resource​.getIdentifier()`
      - `FeatureNaming`

  - ### 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 data store. The current implementation of this data store can emit only `WarningEvent`s; any listener specified for another kind of events will be ignored.
    Specified by:
      `addListener` in interface `Resource`
    Overrides:
      `addListener` in class `DataStore`
    Type Parameters:
      `T` - compile-time value of the `eventType` argument.
    Parameters:
      `eventType` - type of `StoreEvent` to listen (can not be `null`).
      `listener` - listener to notify about events.

  - ### close

    public void close() throws DataStoreException
    Closes this GeoTIFF store and releases any underlying resources.
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in class `DataStore`
    Throws:
      `DataStoreException` - if an error occurred while closing the GeoTIFF file.