org.apache.sis.storage

Class DataStoreProvider

Object

DataStoreProvider

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

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DataStoreProvider() Creates a new provider.

Method Summary

Methods

Modifier and Type	Method and Description
abstract DataStore	open(StorageConnector storage) Returns a data store implementation associated with this provider.
abstract ProbeResult	probeContent(StorageConnector storage) Indicates if the given storage appears to be supported by the DataStores created by this provider.

Methods inherited from class Object

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

Constructor Detail

DataStoreProvider

protected DataStoreProvider()

Creates a new provider.

Method Detail

probeContent

public abstract ProbeResult probeContent(StorageConnector storage)
                                  throws DataStoreException

Indicates if the given storage appears to be supported by the DataStores created by this provider. The most typical return values are:

• ProbeResult.SUPPORTED if the DataStores 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:

storage - 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 storage)
                        throws DataStoreException

Returns a data store implementation associated with this provider.

Implementation note

Implementors shall invoke StorageConnector.closeAllExcept(Object) after DataStore creation, keeping open only the needed resource.

Parameters:

storage - 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)