public abstract class DataStore extends Object implements Resource, Localized, AutoCloseable
DataStore
subclasses exist for different formats (netCDF, GeoTIFF, etc.).
The supported format can be identifier by the provider.
Each data store is itself a Resource
. The data store subclasses should implement
a more specialized Resource
interface depending on the format characteristics.
For example a DataStore
for ShapeFiles will implement the FeatureSet
interface,
while a DataStore
for netCDF files will implement the Aggregate
interface.
DataStore
base class is thread-safe. However subclasses do not need to be thread-safe.
Unless otherwise specified, users should assume that DataStore
instances are not thread-safe.DataStores.open(Object)
Defined in the sis-storage
module
Modifier and Type | Field and Description |
---|---|
protected WarningListeners<DataStore> |
listeners
The set of registered
WarningListener s for this data store. |
protected DataStoreProvider |
provider
The factory that created this
DataStore instance, or null if unspecified. |
Modifier | Constructor and Description |
---|---|
protected |
DataStore()
Creates a new instance with no provider and initially no listener.
|
protected |
DataStore(DataStoreProvider provider,
StorageConnector connector)
Creates a new instance for the given storage (typically file or database).
|
protected |
DataStore(DataStore parent,
StorageConnector connector)
Creates a new instance as a child of another data store instance.
|
Modifier and Type | Method and Description |
---|---|
void |
addWarningListener(WarningListener<? super DataStore> listener)
Adds a listener to be notified when a warning occurred while reading from or writing to the storage.
|
abstract void |
close()
Closes this data store and releases any underlying resources.
|
Resource |
findResource(String identifier)
Searches for a resource identified by the given identifier.
|
String |
getDisplayName()
Returns a short name or label for this data store.
|
Locale |
getLocale()
The locale to use for formatting warnings and other messages.
|
abstract Metadata |
getMetadata()
Returns information about the data store as a whole.
|
abstract ParameterValueGroup |
getOpenParameters()
Returns the parameters used to open this data store.
|
DataStoreProvider |
getProvider()
Returns the factory that created this
DataStore instance. |
void |
removeWarningListener(WarningListener<? super DataStore> listener)
Removes a previously registered listener.
|
void |
setLocale(Locale locale)
Sets the locale to use for formatting warnings and other messages.
|
protected final DataStoreProvider provider
DataStore
instance, or null
if unspecified.
This information can be useful for fetching information common to all DataStore
instances of the same class.getProvider()
protected final WarningListeners<DataStore> listeners
WarningListener
s for this data store.protected DataStore()
protected DataStore(DataStoreProvider provider, StorageConnector connector) throws DataStoreException
provider
argument is an optional information.
The connector
argument is mandatory.provider
- the factory that created this DataStore
instance, or null
if unspecified.connector
- information about the storage (URL, stream, reader instance, etc).DataStoreException
- if an error occurred while creating the data store for the given storage.protected DataStore(DataStore parent, StorageConnector connector) throws DataStoreException
parent
- the parent data store, or null
if none.connector
- information about the storage (URL, stream, reader instance, etc).DataStoreException
- if an error occurred while creating the data store for the given storage.public DataStoreProvider getProvider()
DataStore
instance.
The provider gives additional information on this DataStore
such as a format description
and a list of parameters that can be used for opening data stores of the same class.DataStore
instance, or null
if unspecified.provider
public String getDisplayName()
getLocale()
if this data store is capable to produce a name in various languages.
This name should not be used as an identifier since there is no guarantee that the name is unique among data stores, and no guarantee that the name is the same in all locales. The name may also contain any Unicode characters, including characters usually not allowed in identifiers like white spaces.
This method should never throw an exception since it may be invoked for producing error messages, in which case throwing an exception here would mask the original exception.
Default implementation returns the StorageConnector.getStorageName()
value,
or null
if this data store has been created by the no-argument constructor.
Note that this default value may change in any future SIS version. Subclasses should
override this method if they can provide a better name.
null
if unknown.public Locale getLocale()
The default value is the system default locale.
getLocale
in interface Localized
null
if not explicitly defined.public void setLocale(Locale locale)
This locale is used on a best-effort basis; whether messages will honor this locale or not
depends on the code that logged warnings or threw exceptions. In Apache SIS implementation, this locale has
better chances to be honored by the DataStoreException.getLocalizedMessage()
method rather than
getMessage()
. See getLocalizedMessage()
javadoc for more information.
locale
- the new locale to use.DataStoreException.getLocalizedMessage()
public abstract ParameterValueGroup getOpenParameters()
DataStoreProvider.getOpenParameters()
),
but should contain at least a parameter named "location"
with a URI
, Path
or DataSource
value.
In the event a data store must be closed and reopened later, those parameters can be stored in a file or database and used for creating a new store later.
In some cases, for stores reading in-memory data or other inputs that can not fit with
ParameterDescriptorGroup
requirements (for example an InputStream
connected to unknown or no URL
), this method may return null.
DataStore
, or null
if not available.DataStoreProvider.getOpenParameters()
public abstract Metadata getMetadata() throws DataStoreException
getMetadata
in interface Resource
null
if none.DataStoreException
- if an error occurred while reading the data.Resource.getMetadata()
public Resource findResource(String identifier) throws DataStoreException
Implementation may also accept aliases for convenience. For example if the full name of a resource ismetadata
/identificationInfo
/citation
/identifier
"foo:bar"
, then this method may accept "bar"
as a synonymous of "foo:bar"
provided that it does not introduce ambiguity.
The default implementation verifies if above criterion matches to this DataStore
(which is itself a resource), then iterates recursively over Aggregate
components
if this data store is an aggregate.
If a match is found without ambiguity, the associated resource is returned.
Otherwise an exception is thrown. Subclasses are encouraged to override this method with a more efficient
implementation.
identifier
- identifier of the resource to fetch. Must be non-null.null
).IllegalNameException
- if no resource is found for the given identifier, or if more than one resource is found.DataStoreException
- if another kind of error occurred while searching resources.public void addWarningListener(WarningListener<? super DataStore> listener) throws IllegalArgumentException
Level.WARNING
.try
… finally
block if the DataStore
lifetime is longer than the listener lifetime, as below:
datastore.addWarningListener(listener); try { // Do some work... } finally { datastore.removeWarningListener(listener); }
listener
- the listener to add.IllegalArgumentException
- if the given listener is already registered in this data store.public void removeWarningListener(WarningListener<? super DataStore> listener) throws NoSuchElementException
listener
- the listener to remove.NoSuchElementException
- if the given listener is not registered in this data store.public abstract void close() throws DataStoreException
close
in interface AutoCloseable
DataStoreException
- if an error occurred while closing this data store.Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.