org.apache.sis.storage

## Class DataStoreProvider

- Object
- - DataStoreProvider

- Direct Known Subclasses:
    GeoTiffStoreProvider, LandsatStoreProvider, NetcdfStoreProvider

      public abstract class DataStoreProvider
      extends Object

  Provides information about a specific `DataStore` implementation. There is typically one `DataStoreProvider` instance for each format supported by a library. Each `DataStoreProvider` instances provides the following services:
  - Provide generic information about the storage (name, etc.).
  - Create instances of the `DataStore` implementation described by this provider.
  - Test if a `DataStore` instance created by this provider would have reasonable chances to open a given `StorageConnector`.
  Packaging data stores
  JAR files that provide implementations of this class shall contain an entry with exactly the following path:

      META-INF/services/org.apache.sis.storage.DataStoreProvider

  The above entry shall contain one line for each `DataStoreProvider` implementation provided in the JAR file, where each line is the fully qualified name of the implementation class. See `ServiceLoader` for more general discussion about this lookup mechanism.
  Thread safety
  All `DataStoreProvider` implementations shall be thread-safe. However the `DataStore` instances created by the providers do not need to be thread-safe.
  Since:
    0.3

  Defined in the `sis-storage` module

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `LOCATION` Name of the parameter that specifies the data store location.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `DataStoreProvider()` Creates a new provider.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Format` | `getFormat()` Returns a description of the data format.
    `abstract ParameterDescriptorGroup` | `getOpenParameters()` Returns a description of all parameters accepted by this provider for opening a data store.
    `abstract String` | `getShortName()` Returns a short name or abbreviation for the data format.
    `Range<Version>` | `getSupportedVersions()` Returns the range of versions supported by the data store, or `null` if unspecified.
    `DataStore` | `open(ParameterValueGroup parameters)` Returns a data store implementation associated with this provider for the given parameters.
    `abstract DataStore` | `open(StorageConnector connector)` Returns a data store implementation associated with this provider.
    `abstract ProbeResult` | `probeContent(StorageConnector connector)` Indicates if the given storage appears to be supported by the `DataStore`s created by this provider.

    - ### Methods inherited from class Object

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

- - ### Field Detail

    - #### LOCATION

          public static final String LOCATION

      Name of the parameter that specifies the data store location. A parameter named "location" should be included in the group of parameters returned by `getOpenParameters()`. The parameter value is often a `URI` or a `Path`, but other types are allowed.

      Implementors are encouraged to define a parameter with this name to ensure a common and consistent definition among providers. The parameter should be defined as mandatory and declared with a well-known Java class such as `URI`, `Path`, JDBC DataSource, etc. The type should have a compact textual representation, for serialization in XML or configuration files. Consequently `InputStream` and `Channel` should be avoided.

      See Also:
        `getOpenParameters()`, Constant Field Values

  - ### Constructor Detail

    - #### DataStoreProvider

          protected DataStoreProvider()

      Creates a new provider.

  - ### Method Detail

    - #### getShortName

          public abstract String getShortName()

      Returns a short name or abbreviation for the data format. This name is used in some warnings or exception messages. It may contain any characters, including white spaces (i.e. this short name is not a format identifier).
      Examples: `"CSV"`, `"GeoTIFF"`, `"GML"`, `"GPX"`, `"JPEG"`, `"JPEG 2000"`, `"NetCDF"`, `"PNG"`, `"Shapefile"`.
      For a more comprehensive format name, see `getFormat()`.
      Returns:
        a short name or abbreviation for the data format.
      Since:
        0.8
      See Also:
        `getFormat()`

    - #### getFormat

          public Format getFormat()

      Returns a description of the data format. The description should contain (if available):
      - A reference to the format specification citation, including:
        - a format specification title (example: “PNG (Portable Network Graphics) Specification”),
        - the format short name as a citation alternate title (example: “PNG”),
        - the format version as the citation edition,
        - link to an online version of the specification.
      - The title of the file decompression technique used for reading the data.
      The default implementation returns a format containing only the value returned by `getShortName()`. Subclasses are encouraged to override this method for providing a more complete description, if available.
      Returns:
        a description of the data format.
      Since:
        0.8
      See Also:
        `getShortName()`, `DefaultFormat`

    - #### getSupportedVersions

          public Range<Version> getSupportedVersions()

      Returns the range of versions supported by the data store, or `null` if unspecified.
      Returns:
        the range of supported versions, or `null` if unspecified.
      Since:
        0.8

    - #### getOpenParameters

          public abstract ParameterDescriptorGroup getOpenParameters()

      Returns a description of all parameters accepted by this provider for opening a data store. Those parameters provide an alternative to `StorageConnector` for opening a `DataStore` from a path or URL, together with additional information like character encoding.

      Implementors are responsible for declaring all parameters and whether they are mandatory or optional. It is recommended to define at least a parameter named "location". That parameter will be recognized by the default `DataStoreProvider` methods and used whenever a `StorageConnector` is required.

      Alternative: the main differences between the use of `StorageConnector` and parameters are:
      - `StorageConnector` is designed for use with file or stream of unknown format; the format is automatically detected. By contrast, the use of parameters require to determine the format first (i.e. select a `DataStoreProvider`).
      - Parameters can be used to dynamically generate user configuration interfaces and provide fine grain control over the store general behavior such as caching, time-outs, encoding, etc.
      - Parameters can more easily be serialized in XML or configuration files.
      Returns:
        description of the parameters required or accepted for opening a `DataStore`.
      Since:
        0.8
      See Also:
        `open(ParameterValueGroup)`, `DataStore​.getOpenParameters()`

    - #### probeContent

          public abstract ProbeResult probeContent(StorageConnector connector)
                                            throws DataStoreException

      Indicates if the given storage appears to be supported by the `DataStore`s created by this provider. The most typical return values are:
      - `ProbeResult​.SUPPORTED` if the `DataStore`s created by this provider can open the given storage.
      - `ProbeResult​.UNSUPPORTED_STORAGE` if the given storage does not appear to be in a format supported by this `DataStoreProvider`.
      Note that the `SUPPORTED` value does not guarantee that reading or writing will succeed, only that there appears to be a reasonable chance of success based on a brief inspection of the storage object or contents.

      Implementors are responsible for restoring the input to its original stream position on return of this method. Implementors can use a mark/reset pair for this purpose. Marks are available as `Buffer​.mark()`, `InputStream​.mark(int)` and `ImageInputStream​.mark()`.

      Implementation example
      Implementations will typically check the first bytes of the stream for a "magic number" associated with the format, as in the following example:

          public ProbeResult probeContent(StorageConnector storage) throws DataStoreException {
              final ByteBuffer buffer = storage.getStorageAs(ByteBuffer.class);
              if (buffer == null) {
                  // If StorageConnector can not provide a ByteBuffer, then the storage is
                  // probably not a File, URL, URI, InputStream neither a ReadableChannel.
                  return ProbeResult.UNSUPPORTED_STORAGE;
              }
              if (buffer.remaining() < Integer.BYTES) {
                  // If the buffer does not contain enough bytes for the integer type, this is not
                  // necessarily because the file is truncated. It may be because the data were not
                  // yet available at the time this method has been invoked.
                  return ProbeResult.INSUFFICIENT_BYTES;
              }
              if (buffer.getInt(buffer.position()) != MAGIC_NUMBER) {
                  // We used ByteBuffer.getInt(int) instead than ByteBuffer.getInt() above
                  // in order to keep the buffer position unchanged after this method call.
                  return ProbeResult.UNSUPPORTED_STORAGE;
              }
              return ProbeResult.SUPPORTED;
          }

      Parameters:
        `connector` - information about the storage (URL, stream, JDBC connection, etc).
      Returns:
        `ProbeResult​.SUPPORTED` if the given storage seems to be readable by the `DataStore` instances created by this provider.
      Throws:
        `DataStoreException` - if an I/O or SQL error occurred. The error shall be unrelated to the logical structure of the storage.

    - #### open

          public abstract DataStore open(StorageConnector connector)
                                  throws DataStoreException

      Returns a data store implementation associated with this provider. This method is typically invoked when the format is not known in advance (the `probeContent(StorageConnector)` method can be tested on many providers) or when the input is not a type accepted by `open(ParameterValueGroup)` (for example an `InputStream`).
      Implementation note
      Implementors shall invoke `StorageConnector​.closeAllExcept(Object)` after `DataStore` creation, keeping open only the needed resource.
      Parameters:
        `connector` - information about the storage (URL, stream, JDBC connection, etc).
      Returns:
        a data store implementation associated with this provider for the given storage.
      Throws:
        `DataStoreException` - if an error occurred while creating the data store instance.
      See Also:
        `DataStores​.open(Object)`

    - #### open

          public DataStore open(ParameterValueGroup parameters)
                         throws DataStoreException

      Returns a data store implementation associated with this provider for the given parameters. The `DataStoreProvider` instance needs to be known before parameters are initialized, since the parameters are implementation-dependent. Example:

          DataStoreProvider provider = ...;
          ParameterValueGroup pg = provider.getOpenParameters().createValue();
          pg.parameter(DataStoreProvider.LOCATION, myURL);
          // Set any other parameters if desired.
          try (DataStore ds = provider.open(pg)) {
              // Use the data store.
          }

      Implementation note
      The default implementation gets the value of a parameter named "location". That value (typically a path or URL) is given to `StorageConnector` constructor, which is then passed to `open(StorageConnector)`.
      Parameters:
        `parameters` - opening parameters as defined by `getOpenParameters()`.
      Returns:
        a data store implementation associated with this provider for the given parameters.
      Throws:
        `DataStoreException` - if an error occurred while creating the data store instance.
      Since:
        0.8
      See Also:
        `getOpenParameters()`

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