public abstract class DataStoreProvider extends Object
DataStore
implementation.
There is typically one DataStoreProvider
instance for each format supported by a library.
Each DataStoreProvider
instances provides the following services:
DataStore
implementation described by this provider.DataStore
instance created by this provider would have reasonable chances
to open a given StorageConnector
.META-INF/services/org.apache.sis.storage.DataStoreProviderThe 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.
DataStoreProvider
implementations shall be thread-safe.
However the DataStore
instances created by the providers do not need to be thread-safe.Defined in the sis-storage
module
Modifier and Type | Field and Description |
---|---|
static String |
LOCATION
Name of the parameter that specifies the data store location.
|
Modifier | Constructor and Description |
---|---|
protected |
DataStoreProvider()
Creates a new provider.
|
Modifier and Type | Method and Description |
---|---|
Format |
getFormat()
Returns a description of the data format.
|
abstract ParameterDescriptorGroup |
getOpenParameters()
Returns a description of all parameters accepted by this provider for opening a data store.
|
abstract String |
getShortName()
Returns a short name or abbreviation for the data format.
|
Range<Version> |
getSupportedVersions()
Returns the range of versions supported by the data store, or
null if unspecified. |
DataStore |
open(ParameterValueGroup parameters)
Returns a data store implementation associated with this provider for the given parameters.
|
abstract DataStore |
open(StorageConnector connector)
Returns a data store implementation associated with this provider.
|
abstract ProbeResult |
probeContent(StorageConnector connector)
Indicates if the given storage appears to be supported by the
DataStore s created by this provider. |
public static final String LOCATION
getOpenParameters()
.
The parameter value is often a URI
or a Path
, but other types are allowed.
Implementors 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 declared 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.
getOpenParameters()
,
Constant Field Valuespublic abstract String getShortName()
"CSV"
, "GeoTIFF"
, "GML"
, "GPX"
, "JPEG"
, "JPEG 2000"
,
"NetCDF"
, "PNG"
, "Shapefile"
.
getFormat()
.getFormat()
public Format getFormat()
getShortName()
.
Subclasses are encouraged to override this method for providing a more complete description, if available.getShortName()
,
DefaultFormat
public Range<Version> getSupportedVersions()
null
if unspecified.null
if unspecified.public abstract ParameterDescriptorGroup getOpenParameters()
StorageConnector
for opening a DataStore
from a path or URL, together with additional information like character encoding.
Implementors are responsible for declaring all parameters and whether they are mandatory or optional.
It is recommended to define at least a parameter named "location".
That parameter will be recognized by the default DataStoreProvider
methods and used whenever a
StorageConnector
is required.
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
).DataStore
.open(ParameterValueGroup)
,
DataStore.getOpenParameters()
public abstract ProbeResult probeContent(StorageConnector connector) throws DataStoreException
DataStore
s created by this provider.
The most typical return values are:
ProbeResult.SUPPORTED
if the DataStore
s 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
.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()
.
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; }
connector
- information about the storage (URL, stream, JDBC connection, etc).ProbeResult.SUPPORTED
if the given storage seems to be readable by the DataStore
instances created by this provider.DataStoreException
- if an I/O or SQL error occurred. The error shall be unrelated to the logical
structure of the storage.public abstract DataStore open(StorageConnector connector) throws DataStoreException
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
).
StorageConnector.closeAllExcept(Object)
after DataStore
creation, keeping open only the needed resource.connector
- information about the storage (URL, stream, JDBC connection, etc).DataStoreException
- if an error occurred while creating the data store instance.DataStores.open(Object)
public DataStore open(ParameterValueGroup parameters) throws DataStoreException
DataStoreProvider
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. }
StorageConnector
constructor,
which is then passed to open(StorageConnector)
.parameters
- opening parameters as defined by getOpenParameters()
.DataStoreException
- if an error occurred while creating the data store instance.getOpenParameters()
Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.