- Direct Known Subclasses:
GeoTiffStoreProvider,LandsatStoreProvider,NetcdfStoreProvider,SQLStoreProvider
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
DataStoreimplementation described by this provider. - Test if a
DataStoreinstance created by this provider would have reasonable chances to open a givenStorageConnector.
Packaging data stores
JAR files that provide implementations of this class shall declare the implementation class names inmodule-info.java as providers of the org.apache.sis.storage.DataStoreProvider service.
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
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprotected static interfaceAn action to execute for testing if aStorageConnectorinput can be read. -
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionReturns a description of the data format.Returns the logger where to report warnings or loading operations.abstract ParameterDescriptorGroupReturns a description of all parameters accepted by this provider for opening a data store.abstract StringReturns a short name or abbreviation for the data format.Returns the range of versions supported by the data store, ornullif unspecified.abstract DataStoreopen(StorageConnector connector) Returns a data store implementation associated with this provider.open(ParameterValueGroup parameters) Returns a data store implementation associated with this provider for the given parameters.abstract ProbeResultprobeContent(StorageConnector connector) Indicates if the given storage appears to be supported by theDataStores created by this provider.protected <S> ProbeResultprobeContent(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.
-
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 aURIor 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,InputStreamandChannelshould be avoided.- See Also:
-
CREATE
Name of the parameter that specifies whether to allow creation of a newDataStoreif 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 aBooleanand the default value should beBoolean.FALSEor 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 options
For data stores on file systems, a"create" = trueparameter value is equivalent to opening a file withStandardOpenOption.CREATEandAPPEND. The other file standard options likeCREATE_NEWandTRUNCATE_EXISTINGshould not be accessible through this "create" parameter. The reason is thatParameterValueGroupmay be used for storing parameters permanently (for example in a configuration file or in a database) for reopening the sameDataStoremany times. File options designed for being used only once likeCREATE_NEWandTRUNCATE_EXISTINGare incompatible with this usage.- 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, and is not guaranteed to be unique. For a more comprehensive format name, seegetFormat().Examples
"CSV","GeoTIFF","GML","GPX","JPEG","JPEG 2000","NetCDF","PNG","Shapefile".- Returns:
- a short name or abbreviation for the data format.
- Since:
- 0.8
- See Also:
-
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, ornullif unspecified.- Returns:
- the range of supported versions, or
nullif unspecified. - Since:
- 0.8
-
getOpenParameters
Returns a description of all parameters accepted by this provider for opening a data store. Those parameters provide an alternative toStorageConnectorfor opening aDataStorefrom 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
DataStoreProvidermethods and used whenever aStorageConnectoris required.Alternative
The main differences between the use ofStorageConnectorand parameters are:StorageConnectoris 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 theDataStores 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.SUPPORTEDor another instance with supported status if theDataStores created by this provider can open the given storage.ProbeResult.UNSUPPORTED_STORAGEif the given storage does not appear to be in a format supported by thisDataStoreProvider.
SUPPORTEDvalue 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
DataStoreinstances 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):
The following types are also accepted for completeness but provide no additional safety compared to direct use ofByteBuffer(default byte order fixed toBIG_ENDIAN),InputStream,DataInput,ImageInputStreamandReader.StorageConnector.getStorageAs(Class):
This method marks and resets streams automatically with an arbitrary read-ahead limit (typically okay for the first 8 kilobytes).URI,URL,File,PathandString(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:@Override public ProbeResult probeContent(StorageConnector connector) throws DataStoreException { return probeContent(connector, ByteBuffer.class, (buffer) -> { if (buffer.remaining() >= Integer.BYTES) { if (buffer.getInt() == MAGIC_NUMBER) { return ProbeResult.SUPPORTED; } return ProbeResult.UNSUPPORTED_STORAGE; } // 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; }); }- Type Parameters:
S- the compile-time type of thetypeargument (the source or storage type).- Parameters:
connector- information about the storage (URL, stream, JDBC connection, etc).type- the desired type as one ofByteBuffer,DataInput,Connectionclass 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_STORAGEif the given type is supported but no view can be created for the source given at construction time. - Throws:
IllegalArgumentException- if the giventypeargument is not one of the supported types.IllegalStateException- if thisStorageConnectorhas 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:
-
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)afterDataStorecreation, 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
Returns a data store implementation associated with this provider for the given parameters. TheDataStoreProviderinstance 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 toStorageConnectorconstructor, 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 noStoreListenerhas been registered forWarningEvent.The default implementation returns a logger with the same name as the package name of the subclass of this
DataStoreProviderinstance. 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:
-