Package org.apache.sis.storage

Class 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 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 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, get­Open­Parameters(), Constant Field Values

      • 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:
        LOCATION, get­Open­Parameters(), 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", "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:
        get­Format()

      • 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:
        get­Short­Name(), Default­Format

      • 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:
        LOCATION, CREATE, open(Parameter­Value­Group), Data­Store​.get­Open­Parameters()

      • 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 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:
        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 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:
        LOCATION, CREATE, get­Open­Parameters()

      • getLogger

        public Logger getLogger()
        Returns the logger where to report warnings. 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