Class DataStore
- All Implemented Interfaces:
- AutoCloseable,- Resource,- Localized
- Direct Known Subclasses:
- GeoTiffStore,- LandsatStore,- NetcdfStore,- SQLStore
DataStore subclasses exist for different formats (netCDF, GeoTIFF, etc.).
 The supported format can be identified 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.
Thread safety policy
Data stores should be thread-safe, but their synchronization lock is implementation-dependent. This base class uses only thesynchronized keyword, applied on the following methods:
 
 Since above properties are used only for information purpose, concurrent modifications during a read or write
 operation should be harmless. Consequently, subclasses are free use their own synchronization mechanism instead
 than synchronized(this) lock.- Since:
- 0.3
- See Also:
Defined in the sis-storage module
- 
Field SummaryFieldsModifier and TypeFieldDescriptionprotected final StoreListenersThe set of registeredStoreListeners for this data store.protected final DataStoreProviderThe factory that created thisDataStoreinstance, ornullif unspecified.
- 
Constructor SummaryConstructorsModifierConstructorDescriptionprotectedCreates a new instance with no provider and initially no listener.protectedDataStore(DataStoreProvider provider, StorageConnector connector) Creates a new instance for the given storage (typically file or database).protectedDataStore(DataStore parent, DataStoreProvider provider, StorageConnector connector, boolean hidden) Creates a new instance as a child of another data store instance.
- 
Method SummaryModifier and TypeMethodDescription<T extends StoreEvent>
 voidaddListener(Class<T> eventType, StoreListener<? super T> listener) Registers a listener to notify when the specified kind of event occurs in this data store or in a resource.abstract voidclose()Closes this data store and releases any underlying resources.findResource(String identifier) Searches for a resource identified by the given identifier.Returns a short name or label for this data store.Returns an identifier for the root resource of this data store, or an empty value if none.The locale to use for formatting warnings and other messages.abstract MetadataReturns information about the data store as a whole.Returns implementation-specific metadata.abstract Optional<ParameterValueGroup>Returns the parameters used to open this data store.Returns the factory that created thisDataStoreinstance.<T extends StoreEvent>
 voidremoveListener(Class<T> eventType, StoreListener<? super T> listener) Unregisters a listener previously added to this data store for the given type of events.voidsetLocale(Locale locale) Sets the locale to use for formatting warnings and other messages.Returns a string representation of this data store for debugging purpose.
- 
Field Details- 
providerThe factory that created thisDataStoreinstance, ornullif unspecified. This information can be useful for fetching information common to allDataStoreinstances of the same class.- Since:
- 0.8
- See Also:
 
- 
listenersThe set of registeredStoreListeners for this data store.
 
- 
- 
Constructor Details- 
DataStoreprotected DataStore()Creates a new instance with no provider and initially no listener.
- 
DataStoreprotected DataStore(DataStoreProvider provider, StorageConnector connector) throws DataStoreException Creates a new instance for the given storage (typically file or database). Theproviderargument is an optional but recommended information. Theconnectorargument is mandatory.- Parameters:
- provider- the factory that created this- DataStoreinstance, or- nullif unspecified.
- connector- information about the storage (URL, stream, reader instance, etc).
- Throws:
- DataStoreException- if an error occurred while creating the data store for the given storage.
- Since:
- 0.8
 
- 
DataStoreprotected DataStore(DataStore parent, DataStoreProvider provider, StorageConnector connector, boolean hidden) throws DataStoreException Creates a new instance as a child of another data store instance. Events will be sent not only to registered listeners of thisDataStore, but also to listeners of theparentdata store. Each listener will be notified only once, even if the same listener is registered in the two places.- Parameters:
- parent- the parent that contains this new- DataStorecomponent, or- nullif none.
- provider- the factory that created this- DataStoreinstance, or- nullif unspecified.
- connector- information about the storage (URL, stream, reader instance, etc).
- hidden-- trueif this store will not be directly accessible from the parent. It is the case if this store is an- Aggregateand the parent store will expose only some components of the aggregate instead of the aggregate itself.
- Throws:
- DataStoreException- if an error occurred while creating the data store for the given storage.
- Since:
- 1.1
 
 
- 
- 
Method Details- 
getProviderReturns the factory that created thisDataStoreinstance. The provider gives additional information on thisDataStoresuch as a format description and a list of parameters that can be used for opening data stores of the same class.The return value should never be null if this DataStorehas been created byDataStores.open(Object)or by aDataStoreProvideropen(…)method. However, it may be null if this object has been instantiated by a direct call to its constructor.- Returns:
- the factory that created this DataStoreinstance, ornullif unspecified.
- Since:
- 0.8
- See Also:
 
- 
getOpenParametersReturns the parameters used to open this data store. The collection of legal parameters is implementation-dependent (their description is given byDataStoreProvider.getOpenParameters()), but should contain at least a parameter named "location" with aURI,PathorDataSourcevalue.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 cannot fit with ParameterDescriptorGrouprequirements (for example anInputStreamconnected to unknown or noURL), this method may return an empty value.- Returns:
- parameters used for opening this DataStore.
- Since:
- 0.8
- See Also:
 
- 
setLocaleSets the locale to use for formatting warnings and other messages. In a client-server architecture, it should be the locale on the client side.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 thangetMessage(). SeegetLocalizedMessage()javadoc for more information.- Parameters:
- locale- the new locale to use.
- See Also:
 
- 
getLocaleThe locale to use for formatting warnings and other messages. This locale is for user interfaces only – it has no effect on the data to be read or written from/to the data store.The default value is the system default locale. - Specified by:
- getLocalein interface- Localized
- Returns:
- the locale, or nullif not explicitly defined.
- See Also:
 
- 
getDisplayNameReturns a short name or label for this data store. The returned name can be used in user interfaces or in error messages. It may be a title in natural language, but should be relatively short. The name may be localized in the language specified by the value ofgetLocale()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 hide the original exception. This method differs from getIdentifier()in that it is typically a file name known at construction time instead of a property read from metadata. Default implementation returns theStorageConnector.getStorageName()value, ornullif this data store has been created by the no-argument constructor. Subclasses should override this method if they can provide a better name.- Returns:
- a short name of label for this data store, or nullif unknown.
- Since:
- 0.8
- See Also:
 
- 
getIdentifierReturns an identifier for the root resource of this data store, or an empty value if none. If this data store contains many resources (as in anAggregate), the returned identifier shall be different than the identifiers of those child resources. In other words, the following equality shall hold without ambiguity:
 Note that this identifier is not guaranteed to be unique between differentfindResource(getIdentifier().toString()) == this DataStoreinstances; it only needs to be unique among the resources provided by this data store instance.Default implementationThe default implementation searches for an identifier in the metadata, at the location shown below, provided that conditions are met: 
 Subclasses are encouraged to override this method with more efficient implementations.Path: metadata/identificationInfo/citation/identifierCondition: in default implementation, the identifier is presents only if exactly one citationis found at above path. If two or morecitationinstances are found, the identification is considered ambiguous and an empty value is returned.Selection: the first identifier implementing the GenericNameinterface is returned. If there is no such identifier, then aNamedIdentifieris created from the first identifier. If there is no identifier at all, then an empty value is returned.- Specified by:
- getIdentifierin interface- Resource
- Returns:
- an identifier for the root resource of this data store.
- Throws:
- DataStoreException- if an error occurred while fetching the identifier.
- Since:
- 1.0
- See Also:
 
- 
getMetadataReturns information about the data store as a whole. The returned metadata object can contain information such as the spatiotemporal extent of all contained resources, contact information about the creator or distributor, data quality, update frequency, usage constraints, file format and more.- Specified by:
- getMetadatain interface- Resource
- Returns:
- information about resources in the data store. Should not be null.
- Throws:
- DataStoreException- if an error occurred while reading the metadata.
- See Also:
 
- 
getNativeMetadataReturns implementation-specific metadata. The structure of those metadata varies for each file format. The standard metadata should be preferred since they allow abstraction of format details, but those native metadata are sometimes useful when an information is not provided by the standard metadata.The tree table should contain at least the following columns: - TableColumn.NAME— a name for the metadata property, e.g. "Title".
- TableColumn.VALUE— the property value typically as a string, number or date.
 TableColumn.NAMEof the root node should be a format name such as "NetCDF" or "GeoTIFF". That name should be short since it may be used in widget as a designation of implementation-specific details.- Returns:
- resources information structured in an implementation-specific way.
- Throws:
- DataStoreException- if an error occurred while reading the metadata.
- Since:
- 1.1
 
- 
findResourceSearches for a resource identified by the given identifier. The given identifier should be the string representation of the return value ofResource.getIdentifier()on the desired resource. Implementation may also accept aliases for convenience. For example if the full name of a resource is"foo:bar", then this method may accept"bar"as a synonymous of"foo:bar"provided that it is unambiguous.The default implementation verifies if above criterion apply to this DataStore(which is itself a resource), then iterates recursively overAggregatecomponents 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.- Parameters:
- identifier- identifier of the resource to fetch. Must be non-null.
- Returns:
- resource associated to the given identifier (never null).
- Throws:
- 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.
- See Also:
 
- 
addListenerpublic <T extends StoreEvent> void addListener(Class<T> eventType, StoreListener<? super T> listener) Registers a listener to notify when the specified kind of event occurs in this data store or in a resource. The data store will call theStoreListener.eventOccured(StoreEvent)method when new events matching theeventTypeoccur. An event may be a change in data store content or structure, or a warning that occurred during a read or write operation.Registering a listener for a given eventTypealso register the listener for all event sub-types. The same listener can be registered many times, but itsStoreListener.eventOccured(StoreEvent)method will be invoked only once per event. This filtering applies even if the listener is registered on individual resources of this data store.If this data store may produce events of the given type, then the given listener is kept by strong reference; it will not be garbage collected unless explicitly removed or unless this DataStoreis itself garbage collected. However if the given type of events can never happen with this data store, then this method is not required to keep a reference to the given listener.Warning eventsIfeventTypeis assignable fromWarningEvent.class, then registering that listener turns off logging of warning messages for this data store. This side-effect is applied on the assumption that the registered listener will handle warnings in its own way, for example by showing warnings in a widget.- Specified by:
- addListenerin interface- Resource
- Type Parameters:
- T- compile-time value of the- eventTypeargument.
- Parameters:
- eventType- type of- StoreEventto listen (cannot be- null).
- listener- listener to notify about events.
- Since:
- 1.0
 
- 
removeListenerpublic <T extends StoreEvent> void removeListener(Class<T> eventType, StoreListener<? super T> listener) Unregisters a listener previously added to this data store for the given type of events. TheeventTypemust be the exact same class than the one given to theaddListener(…)method; this method does not remove listeners registered for subclasses and does not remove listeners registered in children resources.If the same listener has been registered many times for the same even type, then this method removes only the most recent registration. In other words if addListener(type, ls)has been invoked twice, thenremoveListener(type, ls)needs to be invoked twice in order to remove all instances of that listener. If the given listener is not found, then this method does nothing (no exception is thrown).Warning eventsIfeventTypeisWarningEvent.classand if, after this method invocation, there are no remaining listeners for warning events, then thisDataStorewill send future warnings to the loggers.- Specified by:
- removeListenerin interface- Resource
- Type Parameters:
- T- compile-time value of the- eventTypeargument.
- Parameters:
- eventType- type of- StoreEventwhich were listened (cannot be- null).
- listener- listener to stop notifying about events.
- Since:
- 1.0
 
- 
closeCloses this data store and releases any underlying resources. ACloseEventis sent to listeners before the data store is closed.Note for implementersImplementations should invokelisteners.close()on their first line for sending notification to all listeners before the data store is actually closed.- Specified by:
- closein interface- AutoCloseable
- Throws:
- DataStoreException- if an error occurred while closing this data store.
- See Also:
 
- 
toStringReturns a string representation of this data store for debugging purpose. The content of the string returned by this method may change in any future SIS version.
 
-