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

Class DataStoreProvider

Object
DataStoreProvider
Direct Known Subclasses:
Geo­Tiff­Store­Provider, Landsat­Store­Provider, Netcdf­Store­Provider, SQLStore­Provider
public abstract class DataStoreProvider extends Object
Provides information about a specific Data­Store implementation. There is typically one Data­Store­Provider instance for each format supported by a library. Each Data­Store­Provider instances provides the following services:
  • Provide generic information about the storage (name, etc.).
  • Create instances of the Data­Store implementation described by this provider.
  • Test if a Data­Store instance created by this provider would have reasonable chances to open a given Storage­Connector.

Packaging data stores

JAR files that provide implementations of this class shall declare the implementation class names in module-info​.java as providers of the org​.apache​.sis​.storage​.Data­Store­Provider service. See Service­Loader for more general discussion about this lookup mechanism.

Thread safety

All Data­Store­Provider implementations shall be thread-safe. However, the Data­Store instances created by the providers do not need to be thread-safe.
Since:
0.3

  • 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 get­Open­Parameters(). 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, Input­Stream 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 Data­Store if none exist at the given location. A parameter named "create" may be included in the group of parameters returned by get­Open­Parameters() 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(Parameter­Value­Group) 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 Standard­Open­Option​.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 Parameter­Value­Group may be used for storing parameters permanently (for example in a configuration file or in a database) for reopening the same Data­Store many times. File options designed for being used only once like CREATE_NEW and TRUNCATE_EXISTING are incompatible with this usage.
      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, and is not guaranteed to be unique. For a more comprehensive format name, see get­Format().

      Examples

      "CSV", "Geo­TIFF", "GML", "GPX", "JPEG", "JPEG 2000", "Net­CDF", "PNG", "Shapefile".
      Returns:
      a short name or abbreviation for the data format.
      Since:
      0.8
      See Also:

    • getFormat

      public 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 get­Short­Name(). 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 ParameterDescriptorGroup getOpenParameters()
      Returns a description of all parameters accepted by this provider for opening a data store. Those parameters provide an alternative to Storage­Connector for opening a Data­Store 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 Data­Store­Provider methods and used whenever a Storage­Connector is required.

      Alternative

      The main differences between the use of Storage­Connector and parameters are:
      • Storage­Connector 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 Data­Store­Provider).
      • 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 Data­Store.
      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 Data­Stores 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 Byte­Buffer​.mark(), Input­Stream​.mark(int) and Image­Input­Stream​.mark(). Alternatively, the probe­Content(Storage­Connector, 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 Data­Store instances created by this provider.
      Throws:
      Data­Store­Exception - 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 probe­Content(Storage­Connector) implementations, providing an alternative safer than Storage­Connector​.get­Storage­As(Class) for performing an arbitrary number of independent tests on the same Storage­Connector. Current implementation accepts the following types (this list may be expanded in future versions):
      Byte­Buffer (default byte order fixed to BIG_ENDIAN), Input­Stream, Data­Input, Image­Input­Stream and Reader.
      The following types are also accepted for completeness but provide no additional safety compared to direct use of Storage­Connector​.get­Storage­As(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

      probe­Content(Storage­Connector) implementations often check the first bytes of the input stream for a "magic number" associated with the format, as in the following example: 
          @Override
    public ProbeResult probeContent(StorageConnector connector) throws DataStoreException {
        return probeContent(connector, ByteBuffer.class, (buffer) -> {
            if (buffer.remaining() >= Integer.BYTES) {
                if (buffer.getInt() == MAGIC_NUMBER) {
                    return ProbeResult.SUPPORTED;
                }
                return ProbeResult.UNSUPPORTED_STORAGE;
            }
            // 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;
        });
    }
      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 Byte­Buffer, Data­Input, 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 Probe­Result​.UNSUPPORTED_STORAGE if the given type is supported but no view can be created for the source given at construction time.
      Throws:
      Illegal­Argument­Exception - if the given type argument is not one of the supported types.
      Illegal­State­Exception - if this Storage­Connector has been closed.
      Data­Store­Exception - if an error occurred while opening a stream or database connection, or during the execution of the probe action.
      Since:
      1.2
      See Also:

    • 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 probe­Content(Storage­Connector) method can be tested on many providers) or when the input is not a type accepted by open(Parameter­Value­Group) (for example an Input­Stream).

      Implementation note

      Implementers shall invoke Storage­Connector​.close­All­Except(Object) after Data­Store 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:
      Data­Store­Exception - if an error occurred while creating the data store instance.
      See Also:

    • open

      public DataStore open(ParameterValueGroup parameters) throws DataStoreException
      Returns a data store implementation associated with this provider for the given parameters. The Data­Store­Provider 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 Storage­Connector constructor, which is then passed to open(Storage­Connector).
      Parameters:
      parameters - opening parameters as defined by get­Open­Parameters().
      Returns:
      a data store implementation associated with this provider for the given parameters.
      Throws:
      Data­Store­Exception - 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 Store­Listener has been registered for Warning­Event.

      The default implementation returns a logger with the same name as the package name of the subclass of this Data­Store­Provider 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: