org.apache.sis.storage

## Class DataStore

- Object
- - DataStore

- All Implemented Interfaces:
    AutoCloseable, Resource, Localized
  Direct Known Subclasses:
    GeoTiffStore, LandsatStore, NetcdfStore

      public abstract class DataStore
      extends Object
      implements Resource, Localized, AutoCloseable

  Manages a series of features, coverages or sensor data. Different `DataStore` subclasses exist for different formats (netCDF, GeoTIFF, etc.). The supported format can be identifier by the provider.

  Each data store is itself a `Resource`. The data store subclasses should implement a more specialized `Resource` interface depending on the format characteristics. For example a `DataStore` for ShapeFiles will implement the `FeatureSet` interface, while a `DataStore` for netCDF files will implement the `Aggregate` interface.

  Thread safety policy
  This `DataStore` base class is thread-safe. However subclasses do not need to be thread-safe. Unless otherwise specified, users should assume that `DataStore` instances are not thread-safe.
  Since:
    0.3
  See Also:
    `DataStores​.open(Object)`

  Defined in the `sis-storage` module

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected WarningListeners<DataStore>` | `listeners` The set of registered `WarningListener`s for this data store.
    `protected DataStoreProvider` | `provider` The factory that created this `DataStore` instance, or `null` if unspecified.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `DataStore()` Creates a new instance with no provider and initially no listener.
    `protected` | `DataStore(DataStoreProvider provider, StorageConnector connector)` Creates a new instance for the given storage (typically file or database).
    `protected` | `DataStore(DataStore parent, StorageConnector connector)` Creates a new instance as a child of another data store instance.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addWarningListener(WarningListener<? super DataStore> listener)` Adds a listener to be notified when a warning occurred while reading from or writing to the storage.
    `abstract void` | `close()` Closes this data store and releases any underlying resources.
    `Resource` | `findResource(String identifier)` Searches for a resource identified by the given identifier.
    `String` | `getDisplayName()` Returns a short name or label for this data store.
    `Locale` | `getLocale()` The locale to use for formatting warnings and other messages.
    `abstract Metadata` | `getMetadata()` Returns information about the data store as a whole.
    `abstract ParameterValueGroup` | `getOpenParameters()` Returns the parameters used to open this data store.
    `DataStoreProvider` | `getProvider()` Returns the factory that created this `DataStore` instance.
    `void` | `removeWarningListener(WarningListener<? super DataStore> listener)` Removes a previously registered listener.
    `void` | `setLocale(Locale locale)` Sets the locale to use for formatting warnings and other messages.

    - ### Methods inherited from class Object

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

- - ### Field Detail

    - #### provider

          protected final DataStoreProvider provider

      The factory that created this `DataStore` instance, or `null` if unspecified. This information can be useful for fetching information common to all `DataStore` instances of the same class.
      Since:
        0.8
      See Also:
        `getProvider()`

    - #### listeners

          protected final WarningListeners<DataStore> listeners

      The set of registered `WarningListener`s for this data store.

  - ### Constructor Detail

    - #### DataStore

          protected DataStore()

      Creates a new instance with no provider and initially no listener.

    - #### DataStore

          protected DataStore(DataStoreProvider provider,
                              StorageConnector connector)
                       throws DataStoreException

      Creates a new instance for the given storage (typically file or database). The `provider` argument is an optional information. The `connector` argument is mandatory.
      Parameters:
        `provider` - the factory that created this `DataStore` instance, or `null` if unspecified.
        `connector` - information about the storage (URL, stream, reader instance, etc).
      Throws:
        `DataStoreException` - if an error occurred while creating the data store for the given storage.
      Since:
        0.8

    - #### DataStore

          protected DataStore(DataStore parent,
                              StorageConnector connector)
                       throws DataStoreException

      Creates a new instance as a child of another data store instance. The new instance inherits the parent provider. The parent and the child share the same listeners: adding or removing a listener to a parent adds or removes the same listeners to all children, and conversely.
      Parameters:
        `parent` - the parent data store, or `null` if none.
        `connector` - information about the storage (URL, stream, reader instance, etc).
      Throws:
        `DataStoreException` - if an error occurred while creating the data store for the given storage.
      Since:
        0.8

  - ### Method Detail

    - #### getProvider

          public DataStoreProvider getProvider()

      Returns the factory that created this `DataStore` instance. The provider gives additional information on this `DataStore` such as a format description and a list of parameters that can be used for opening data stores of the same class.
      Returns:
        the factory that created this `DataStore` instance, or `null` if unspecified.
      Since:
        0.8
      See Also:
        `provider`

    - #### getDisplayName

          public String getDisplayName()

      Returns a short name or label for this data store. The returned name can be used in user interfaces or in error messages. It may be a title in natural language, but should be relatively short. The name may be localized in the language specified by the value of `getLocale()` if this data store is capable to produce a name in various languages.

      This name should not be used as an identifier since there is no guarantee that the name is unique among data stores, and no guarantee that the name is the same in all locales. The name may also contain any Unicode characters, including characters usually not allowed in identifiers like white spaces.

      This method should never throw an exception since it may be invoked for producing error messages, in which case throwing an exception here would mask the original exception.

      Default implementation returns the `StorageConnector​.getStorageName()` value, or `null` if this data store has been created by the no-argument constructor. Note that this default value may change in any future SIS version. Subclasses should override this method if they can provide a better name.

      Returns:
        a short name of label for this data store, or `null` if unknown.
      Since:
        0.8

    - #### getLocale

          public Locale getLocale()

      The locale to use for formatting warnings and other messages. This locale if for user interfaces only – it has no effect on the data to be read or written from/to the data store.

      The default value is the system default locale.

      Specified by:
        `getLocale` in interface `Localized`
      Returns:
        the locale, or `null` if not explicitly defined.

    - #### setLocale

          public void setLocale(Locale locale)

      Sets the locale to use for formatting warnings and other messages. In a client-server architecture, it should be the locale on the client side.

      This locale is used on a best-effort basis; whether messages will honor this locale or not depends on the code that logged warnings or threw exceptions. In Apache SIS implementation, this locale has better chances to be honored by the `DataStoreException​.getLocalizedMessage()` method rather than `getMessage()`. See `getLocalizedMessage()` javadoc for more information.

      Parameters:
        `locale` - the new locale to use.
      See Also:
        `DataStoreException​.getLocalizedMessage()`

    - #### getOpenParameters

          public abstract ParameterValueGroup getOpenParameters()

      Returns the parameters used to open this data store. The collection of legal parameters is implementation-dependent (their description is given by `DataStoreProvider​.getOpenParameters()`), but should contain at least a parameter named "location" with a `URI`, `Path` or `DataSource` value.

      In the event a data store must be closed and reopened later, those parameters can be stored in a file or database and used for creating a new store later.

      In some cases, for stores reading in-memory data or other inputs that can not fit with `ParameterDescriptorGroup` requirements (for example an `InputStream` connected to unknown or no `URL`), this method may return null.

      Returns:
        parameters used for opening this `DataStore`, or `null` if not available.
      Since:
        0.8
      See Also:
        `DataStoreProvider​.getOpenParameters()`

    - #### getMetadata

          public abstract Metadata getMetadata()
                                        throws DataStoreException

      Returns information about the data store as a whole. The returned metadata object can contain information such as the spatiotemporal extent of all contained resources, contact information about the creator or distributor, data quality, update frequency, usage constraints, file format and more.
      Specified by:
        `getMetadata` in interface `Resource`
      Returns:
        information about resources in the data store, or `null` if none.
      Throws:
        `DataStoreException` - if an error occurred while reading the data.
      See Also:
        `Resource​.getMetadata()`

    - #### findResource

          public Resource findResource(String identifier)
                                throws DataStoreException

      Searches for a resource identified by the given identifier. The given identifier should match the following metadata element of a resource:

      > `metadata` / `identificationInfo` / `citation` / `identifier`

      Implementation may also accept aliases for convenience. For example if the full name of a resource is `"foo:bar"`, then this method may accept `"bar"` as a synonymous of `"foo:bar"` provided that it does not introduce ambiguity.

      The default implementation verifies if above criterion matches to this `DataStore` (which is itself a resource), then iterates recursively over `Aggregate` components if this data store is an aggregate. If a match is found without ambiguity, the associated resource is returned. Otherwise an exception is thrown. Subclasses are encouraged to override this method with a more efficient implementation.

      Parameters:
        `identifier` - identifier of the resource to fetch. Must be non-null.
      Returns:
        resource associated to the given identifier (never `null`).
      Throws:
        `IllegalNameException` - if no resource is found for the given identifier, or if more than one resource is found.
        `DataStoreException` - if another kind of error occurred while searching resources.

    - #### addWarningListener

          public void addWarningListener(WarningListener<? super DataStore> listener)
                                  throws IllegalArgumentException

      Adds a listener to be notified when a warning occurred while reading from or writing to the storage. When a warning occurs, there is a choice:
      - If this data store has no warning listener, then the warning is logged at `Level​.WARNING`.
      - If this data store has at least one warning listener, then all listeners are notified and the warning is not logged by this data store instance.
      Consider invoking this method in a `try` … `finally` block if the `DataStore` lifetime is longer than the listener lifetime, as below:

          datastore.addWarningListener(listener);
          try {
              // Do some work...
          } finally {
              datastore.removeWarningListener(listener);
          }

      Parameters:
        `listener` - the listener to add.
      Throws:
        `IllegalArgumentException` - if the given listener is already registered in this data store.

    - #### removeWarningListener

          public void removeWarningListener(WarningListener<? super DataStore> listener)
                                     throws NoSuchElementException

      Removes a previously registered listener.
      Parameters:
        `listener` - the listener to remove.
      Throws:
        `NoSuchElementException` - if the given listener is not registered in this data store.

    - #### close

          public abstract void close()
                              throws DataStoreException

      Closes this data store and releases any underlying resources.
      Specified by:
        `close` in interface `AutoCloseable`
      Throws:
        `DataStoreException` - if an error occurred while closing this data store.

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.