Class DataStoreProvider
- Direct Known Subclasses:
GeoTiffStoreProvider
,LandsatStoreProvider
,SQLStoreProvider
,StoreProvider
,URIDataStore.Provider
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 givenStorageConnector
.
Packaging data stores
JAR files that provide implementations of this class shall contain an entry with exactly the following path: The above entry shall contain one line for eachDataStoreProvider
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
AllDataStoreProvider
implementations shall be thread-safe.
However, the DataStore
instances created by the providers do not need to be thread-safe.- Since:
- 0.3
- Version:
- 1.2
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprotected static interface
An action to execute for testing if aStorageConnector
input can be read.private static final class
Implementation of the composed probe returned byDataStoreProvider.Prober.orElse(Class, Prober)
. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
Name of the parameter that specifies whether to allow creation of a newDataStore
if none exist at the given location.static final String
Name of the parameter that specifies the data store location.private Logger
The logger where to reports warnings or change events. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionorg.opengis.metadata.distribution.Format
Returns a description of the data format.Returns the logger where to report warnings or loading operations.abstract org.opengis.parameter.ParameterDescriptorGroup
Returns a description of all parameters accepted by this provider for opening a data store.abstract String
Returns a short name or abbreviation for the data format.Returns the range of versions supported by the data store, ornull
if unspecified.abstract DataStore
open
(StorageConnector connector) Returns a data store implementation associated with this provider.open
(org.opengis.parameter.ParameterValueGroup parameters) Returns a data store implementation associated with this provider for the given parameters.abstract ProbeResult
probeContent
(StorageConnector connector) Indicates if the given storage appears to be supported by theDataStore
s created by this provider.protected <S> ProbeResult
probeContent
(StorageConnector connector, Class<S> type, DataStoreProvider.Prober<? super S> prober) Applies the specified test on the storage content without modifying buffer or input stream position.private <N> ProbeResult
tryNextProber
(StorageConnector connector, DataStoreProvider.ProberList<?, N> list) Tries theDataStoreProvider.ProberList.next
probe.private <S> ProbeResult
tryProber
(StorageConnector connector, Class<S> type, DataStoreProvider.Prober<? super S> prober) Implementation ofprobeContent(StorageConnector, Class, Prober)
for a single element in a list of probe.
-
Field Details
-
LOCATION
Name of the parameter that specifies the data store location. A parameter named "location" should be included in the group of parameters returned bygetOpenParameters()
. The parameter value is often aURI
or aPath
, 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,InputStream
andChannel
should be avoided.- See Also:
-
CREATE
Name of the parameter that specifies whether to allow creation of a newDataStore
if none exist at the given location. A parameter named "create" may be included in the group of parameters returned bygetOpenParameters()
if the data store supports write operations. The parameter value is often aBoolean
and the default value should beBoolean.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 theopen(ParameterValueGroup)
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 totrue
, then theopen(…)
method may create files, a directory or a database at the given location.Relationship with standard file open optionsFor data stores on file systems, a
"create" = true
parameter value is equivalent to opening a file withStandardOpenOption.CREATE
andAPPEND
. The other file standard options likeCREATE_NEW
andTRUNCATE_EXISTING
should not be accessible through this "create" parameter. The reason is thatParameterValueGroup
may be used for storing parameters permanently (for example in a configuration file or in a database) for reopening the sameDataStore
many times. File options designed for being used only once likeCREATE_NEW
andTRUNCATE_EXISTING
are incompatible with this usage.- See Also:
-
logger
The logger where to reports warnings or change events. Created when first needed and kept by strong reference for avoiding configuration lost if the logger is garbage collected. This strategy assumes thatDataStoreProvider
instances are kept alive for the duration of JVM lifetime, which is the case withDataStoreRegistry
.- See Also:
-
-
Constructor Details
-
DataStoreProvider
protected DataStoreProvider()Creates a new provider.
-
-
Method Details
-
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:For a more comprehensive format name, see"CSV"
,"GeoTIFF"
,"GML"
,"GPX"
,"JPEG"
,"JPEG 2000"
,"NetCDF"
,"PNG"
,"Shapefile"
.getFormat()
.- Returns:
- a short name or abbreviation for the data format.
- Since:
- 0.8
- See Also:
-
getFormat
public org.opengis.metadata.distribution.Format getFormat()Returns a description of the data format. The description should contain (if available):- A reference to the format specification citation, including:
- a format specification title (example: “PNG (Portable Network Graphics) Specification”),
- the format short name as a citation alternate title (example: “PNG”),
- the format version as the citation edition,
- link to an online version of the specification.
- The title of the file decompression technique used for reading the data.
getShortName()
. 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:
- A reference to the format specification citation, including:
-
getSupportedVersions
Returns the range of versions supported by the data store, ornull
if unspecified.- Returns:
- the range of supported versions, or
null
if unspecified. - Since:
- 0.8
-
getOpenParameters
public abstract org.opengis.parameter.ParameterDescriptorGroup getOpenParameters()Returns a description of all parameters accepted by this provider for opening a data store. Those parameters provide an alternative toStorageConnector
for opening aDataStore
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
DataStoreProvider
methods and used whenever aStorageConnector
is required.Alternative: the main differences between the use ofStorageConnector
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 aDataStoreProvider
).- 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
DataStore
. - Since:
- 0.8
- See Also:
-
probeContent
Indicates if the given storage appears to be supported by theDataStore
s 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:ProbeResult.SUPPORTED
or another instance with supported status if theDataStore
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 thisDataStoreProvider
.
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 asByteBuffer.mark()
,InputStream.mark(int)
andImageInputStream.mark()
. Alternatively, theprobeContent(StorageConnector, 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
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.
-
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 forprobeContent(StorageConnector)
implementations, providing an alternative safer thanStorageConnector.getStorageAs(Class)
for performing an arbitrary number of independent tests on the sameStorageConnector
. Current implementation accepts the following types (this list may be expanded in future versions):ByteBuffer
(default byte order fixed toBIG_ENDIAN
),InputStream
,DataInput
,ImageInputStream
andReader
.StorageConnector.getStorageAs(Class)
:URI
,URL
,File
,Path
andString
(interpreted as a file path).Usage example
probeContent(StorageConnector)
implementations often check the first bytes of the input stream for a "magic number" associated with the format, as in the following example:- Type Parameters:
S
- the compile-time type of thetype
argument (the source or storage type).- Parameters:
connector
- information about the storage (URL, stream, JDBC connection, etc).type
- the desired type as one ofByteBuffer
,DataInput
,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
ProbeResult.UNSUPPORTED_STORAGE
if the given type is supported but no view can be created for the source given at construction time. - Throws:
IllegalArgumentException
- if the giventype
argument is not one of the supported types.IllegalStateException
- if thisStorageConnector
has been closed.DataStoreException
- if an error occurred while opening a stream or database connection, or during the execution of the probe action.- Since:
- 1.2
- See Also:
-
tryNextProber
private <N> ProbeResult tryNextProber(StorageConnector connector, DataStoreProvider.ProberList<?, N> list) throws DataStoreExceptionTries theDataStoreProvider.ProberList.next
probe. This method is defined for type parameterization (the caller has only<?>
and we need a specific type<N>
).- Type Parameters:
N
- type of input requested by the next probe.- Parameters:
connector
- information about the storage (URL, stream, JDBC connection, etc).list
- root of the chained list of next probes.- Throws:
DataStoreException
-
tryProber
private <S> ProbeResult tryProber(StorageConnector connector, Class<S> type, DataStoreProvider.Prober<? super S> prober) throws DataStoreException Implementation ofprobeContent(StorageConnector, Class, Prober)
for a single element in a list of probe.- Type Parameters:
S
- the compile-time type of thetype
argument (the source or storage type).- Parameters:
connector
- information about the storage (URL, stream, JDBC connection, etc).type
- the desired type as one ofByteBuffer
,DataInput
, etc.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
null
if the given type is supported but no view can be created. - Throws:
IllegalArgumentException
- if the giventype
argument is not one of the supported types.IllegalStateException
- if thisStorageConnector
has been closed.DataStoreException
- if another kind of error occurred.
-
open
Returns a data store implementation associated with this provider. This method is typically invoked when the format is not known in advance (theprobeContent(StorageConnector)
method can be tested on many providers) or when the input is not a type accepted byopen(ParameterValueGroup)
(for example anInputStream
).Implementation note
Implementers shall invokeStorageConnector.closeAllExcept(Object)
afterDataStore
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:
DataStoreException
- if an error occurred while creating the data store instance.- See Also:
-
open
public DataStore open(org.opengis.parameter.ParameterValueGroup parameters) throws DataStoreException Returns a data store implementation associated with this provider for the given parameters. TheDataStoreProvider
instance needs to be known before parameters are initialized, since the parameters are implementation-dependent. Example:Implementation note
The default implementation gets the value of a parameter named "location". That value (typically a path or URL) is given toStorageConnector
constructor, which is then passed toopen(StorageConnector)
.- Parameters:
parameters
- opening parameters as defined bygetOpenParameters()
.- Returns:
- a data store implementation associated with this provider for the given parameters.
- Throws:
DataStoreException
- if an error occurred while creating the data store instance.- Since:
- 0.8
- See Also:
-
getLogger
Returns the logger where to report warnings or loading operations. This logger is used only if noStoreListener
has been registered forWarningEvent
.The default implementation returns a logger with the same name as the package name of the subclass of this
DataStoreProvider
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:
-