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 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 Data­Store­Provider implementation provided in the JAR file, where each line is the fully qualified name of the implementation class. 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

Defined in the sis-storage module

  • 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 (i.e. this short name is not a format identifier).
      Examples: "CSV", "Geo­TIFF", "GML", "GPX", "JPEG", "JPEG 2000", "Net­CDF", "PNG", "Shapefile".
      For a more comprehensive format name, see get­Format().
      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. 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.

      Implementers are responsible for restoring the input to its original stream position on return of this method. Implementers can use a mark/reset pair for this purpose. Marks are available as Byte­Buffer​.mark(), Input­Stream​.mark(int) and Image­Input­Stream​.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 of 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:
      Probe­Result​.SUPPORTED 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.
    • 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 is no listeners) for warning messages.
      Since:
      1.0
      See Also: