Package org.apache.sis.storage

Class DataStoreProvider

java.lang.Object
org.apache.sis.storage.DataStoreProvider
Direct Known Subclasses:
GeoTiffStoreProvider, LandsatStoreProvider, SQLStoreProvider, StoreProvider, URIDataStore.Provider
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: 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
Version:
1.2

  • Field Details

    • 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.

      Implementers 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 typed 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:

    • CREATE

      public static final String CREATE
      Name of the parameter that specifies whether to allow creation of a new DataStore if none exist at the given location. A parameter named "create" may be included in the group of parameters returned by getOpenParameters() if the data store supports write operations. The parameter value is often a Boolean and the default value should be Boolean.FALSE or equivalent.

      Implementers are encouraged to define an optional parameter with this name in complement to the "location" parameter only if write operations are supported. If this parameter value is not set or is set to false, then the open(ParameterValueGroup) method should fail if no file or database exists at the URL or path given by the "location" parameter. Otherwise if this parameter is set to true, then the open(…) method may create files, a directory or a database at the given location.

      Relationship with standard file open options

      For data stores on file systems, a "create" = true parameter value is equivalent to opening a file with StandardOpenOption.CREATE and APPEND. The other file standard options like CREATE_NEW and TRUNCATE_EXISTING should not be accessible through this "create" parameter. The reason is that ParameterValueGroup may be used for storing parameters permanently (for example in a configuration file or in a database) for reopening the same DataStore many times. File options designed for being used only once like CREATE_NEW and TRUNCATE_EXISTING are incompatible with this usage.

      See Also:

    • logger

      private volatile Logger logger
      The logger where to reports warnings or change events. Created when first needed and kept by strong reference for avoiding configuration lost if the logger is garbage collected. This strategy assumes that DataStoreProvider instances are kept alive for the duration of JVM lifetime, which is the case with DataStoreRegistry.
      See Also:

  • Constructor Details

    • DataStoreProvider

      protected DataStoreProvider()
      Creates a new provider.

  • Method Details

    • 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

      public org.opengis.metadata.distribution.Format getFormat()
      Returns a description of the data format. The description should contain (if available): 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:

    • 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 org.opengis.parameter.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.

      Implementers are responsible for declaring all parameters and whether they are mandatory or optional. It is recommended to define at least a parameter named "location", completed by "create" if the data store supports write operations. Those parameters 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:

    • probeContent

      public abstract ProbeResult probeContent(StorageConnector connector) throws DataStoreException
      Indicates if the given storage appears to be supported by the DataStores created by this provider. Implementations will typically check the first bytes of the input stream for a "magic number" associated with the format. The most typical return values are: 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.
      Note for implementers: Implementations are responsible for restoring the storage object to its original position on return of this method. Implementers can use the mark/reset mechanism for this purpose. Marks are available as Buffer.mark(), InputStream.mark(int) and ImageInputStream.mark(). Alternatively, the probeContent(StorageConnector, Class, Prober) helper method manages automatically the marks for a set of known types.
      Parameters:
      connector - information about the storage (URL, stream, JDBC connection, etc).
      Returns:
      a supported status 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.

    • probeContent

      protected <S> ProbeResult probeContent(StorageConnector connector, Class<S> type, DataStoreProvider.Prober<? super S> prober) throws DataStoreException
      Applies the specified test on the storage content without modifying buffer or input stream position. This is a helper method for probeContent(StorageConnector) implementations, providing an alternative safer than StorageConnector.getStorageAs(Class) for performing an arbitrary number of independent tests on the same StorageConnector. Current implementation accepts the following types (this list may be expanded in future versions):
      ByteBuffer (default byte order fixed to BIG_ENDIAN), InputStream, DataInput, ImageInputStream and Reader.
      The following types are also accepted for completeness but provide no additional safety compared to direct use of StorageConnector.getStorageAs(Class):
      URI, URL, File, Path and String (interpreted as a file path).
      This method marks and resets streams automatically with an arbitrary read-ahead limit (typically okay for the first 8 kilobytes).

      Usage example

      probeContent(StorageConnector) implementations often check the first bytes of the input stream for a "magic number" associated with the format, as in the following example:
      Type Parameters:
      S - the compile-time type of the type argument (the source or storage type).
      Parameters:
      connector - information about the storage (URL, stream, JDBC connection, etc).
      type - the desired type as one of ByteBuffer, DataInput, Connection class or other documented types.
      prober - the test to apply on the source of the given type.
      Returns:
      the result of executing the probe action with a source of the given type, or ProbeResult.UNSUPPORTED_STORAGE if the given type is supported but no view can be created for the source given at construction time.
      Throws:
      IllegalArgumentException - if the given type argument is not one of the supported types.
      IllegalStateException - if this StorageConnector has been closed.
      DataStoreException - if an error occurred while opening a stream or database connection, or during the execution of the probe action.
      Since:
      1.2
      See Also:

    • tryNextProber

      private <N> ProbeResult tryNextProber(StorageConnector connector, DataStoreProvider.ProberList<?,N> list) throws DataStoreException
      Tries the DataStoreProvider.ProberList.next probe. This method is defined for type parameterization (the caller has only <?> and we need a specific type <N>).
      Type Parameters:
      N - type of input requested by the next probe.
      Parameters:
      connector - information about the storage (URL, stream, JDBC connection, etc).
      list - root of the chained list of next probes.
      Throws:
      DataStoreException

    • tryProber

      private <S> ProbeResult tryProber(StorageConnector connector, Class<S> type, DataStoreProvider.Prober<? super S> prober) throws DataStoreException
      Implementation of probeContent(StorageConnector, Class, Prober) for a single element in a list of probe.
      Type Parameters:
      S - the compile-time type of the type argument (the source or storage type).
      Parameters:
      connector - information about the storage (URL, stream, JDBC connection, etc).
      type - the desired type as one of ByteBuffer, DataInput, etc.
      prober - the test to apply on the source of the given type.
      Returns:
      the result of executing the probe action with a source of the given type, or null if the given type is supported but no view can be created.
      Throws:
      IllegalArgumentException - if the given type argument is not one of the supported types.
      IllegalStateException - if this StorageConnector has been closed.
      DataStoreException - if another kind of error occurred.

    • 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

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

    • open

      public DataStore open(org.opengis.parameter.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:

      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:

    • getLogger

      public Logger getLogger()
      Returns the logger where to report warnings or loading operations. This logger is used only if no StoreListener has been registered for WarningEvent.

      The default implementation returns a logger with the same name as the package name of the subclass of this DataStoreProvider instance. Subclasses should override this method if they can provide a more specific logger.

      Returns:
      the logger to use as a fallback (when there are no listeners) for warning messages.
      Since:
      1.0
      See Also: