Class DataStore

  • All Implemented Interfaces:
    Auto­Closeable, Resource, Localized
    Direct Known Subclasses:
    Geo­Tiff­Store, Landsat­Store, Netcdf­Store, SQLStore

    public abstract class DataStore
    extends Object
    implements Resource, Localized, AutoCloseable
    Manages a series of features, coverages or sensor data. Different Data­Store 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 Data­Store for ShapeFiles will implement the Feature­Set interface, while a Data­Store 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 the synchronized 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:
    Data­Stores​.open(Object)

    Defined in the sis-storage module

    • Field Detail

      • provider

        protected final DataStoreProvider provider
        The factory that created this Data­Store instance, or null if unspecified. This information can be useful for fetching information common to all Data­Store instances of the same class.
        Since:
        0.8
        See Also:
        get­Provider()
    • Constructor Detail

      • DataStore

        protected DataStore()
        Creates a new instance with no provider and initially no listener.
      • DataStore

        protected DataStore​(DataStoreProvider provider,
                            StorageConnector connector)
                     throws DataStoreException
        Creates a new instance for the given storage (typically file or database). The provider argument is an optional but recommended information. The connector argument is mandatory.
        Parameters:
        provider - the factory that created this Data­Store instance, or null if unspecified.
        connector - information about the storage (URL, stream, reader instance, etc).
        Throws:
        Data­Store­Exception - if an error occurred while creating the data store for the given storage.
        Since:
        0.8
      • DataStore

        protected DataStore​(DataStore parent,
                            StorageConnector connector)
                     throws DataStoreException
        Creates a new instance as a child of another data store instance. The new instance inherits the parent provider. Events created by this Data­Store are forwarded to listeners registered into the parent data store too.
        Parameters:
        parent - the parent data store, or null if none.
        connector - information about the storage (URL, stream, reader instance, etc).
        Throws:
        Data­Store­Exception - if an error occurred while creating the data store for the given storage.
        Since:
        0.8
    • Method Detail

      • getProvider

        public DataStoreProvider getProvider()
        Returns the factory that created this Data­Store instance. The provider gives additional information on this Data­Store such 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 Data­Store has been created by Data­Stores​.open(Object) or by a Data­Store­Provider open(…) 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 Data­Store instance, or null if unspecified.
        Since:
        0.8
        See Also:
        provider
      • setLocale

        public void setLocale​(Locale locale)
        Sets 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 Data­Store­Exception​.get­Localized­Message() method rather than get­Message(). See get­Localized­Message() javadoc for more information.

        Parameters:
        locale - the new locale to use.
        See Also:
        Data­Store­Exception​.get­Localized­Message()
      • getLocale

        public Locale getLocale()
        The locale to use for formatting warnings and other messages. This locale if 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:
        get­Locale in interface Localized
        Returns:
        the locale, or null if not explicitly defined.
        See Also:
        Store­Event​.get­Locale()
      • getDisplayName

        public String getDisplayName()
        Returns 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 of get­Locale() 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.

        This method differs from get­Identifier() in that it is typically a file name known at construction time instead than a property read from metadata. Default implementation returns the Storage­Connector​.get­Storage­Name() value, or null if 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 null if unknown.
        Since:
        0.8
        See Also:
        get­Identifier(), get­Locale()
      • getIdentifier

        public Optional<GenericName> getIdentifier()
                                            throws DataStoreException
        Returns an identifier for the root resource of this data store, or null if none. If this data store contains many resources (as in an Aggregate), the returned identifier shall be different than the identifiers of those child resources. In other words, the following equality shall hold without ambiguity:
        findResource(getIdentifier().toString()) == this
        Note that this identifier is not guaranteed to be unique between different Data­Store instances; it only needs to be unique among the resources provided by this data store instance.
        Default implementation

        The default implementation searches for an identifier in the metadata, at the location shown below, provided that conditions are met:

        Path: metadata / identification­Info / citation / identifier

        Condition: in default implementation, the identifier is presents only if exactly one citation is found at above path. If two or more citation instances are found, the identification is considered ambiguous and an empty value is returned.

        Selection: the first identifier implementing the Generic­Name interface is returned. If there is no such identifier, then a Named­Identifier is created from the first identifier. If there is no identifier at all, then an empty value is returned.

        Subclasses are encouraged to override this method with more efficient implementations.
        Specified by:
        get­Identifier in interface Resource
        Returns:
        an identifier for the root resource of this data store.
        Throws:
        Data­Store­Exception - if an error occurred while fetching the identifier.
        Since:
        1.0
        See Also:
        get­Metadata(), get­Display­Name()
      • getMetadata

        public abstract Metadata getMetadata()
                                      throws DataStoreException
        Returns 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:
        get­Metadata in interface Resource
        Returns:
        information about resources in the data store. Should not be null.
        Throws:
        Data­Store­Exception - if an error occurred while reading the data.
        See Also:
        get­Identifier()
      • findResource

        public Resource findResource​(String identifier)
                              throws DataStoreException
        Searches for a resource identified by the given identifier. The given identifier should be the string representation of the return value of Resource​.get­Identifier() 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 does not introduce ambiguity.

        The default implementation verifies if above criterion matches to this Data­Store (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.

        Parameters:
        identifier - identifier of the resource to fetch. Must be non-null.
        Returns:
        resource associated to the given identifier (never null).
        Throws:
        Illegal­Name­Exception - if no resource is found for the given identifier, or if more than one resource is found.
        Data­Store­Exception - if another kind of error occurred while searching resources.
        See Also:
        Resource​.get­Identifier(), Feature­Naming
      • addListener

        public <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 the Store­Listener​.event­Occured(Store­Event) method when new events matching the event­Type occur. 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 event­Type also register the listener for all event sub-types. The same listener can be registered many times, but its Store­Listener​.event­Occured(Store­Event) 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 Data­Store is 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 events
        If event­Type is assignable from Warning­Event.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:
        add­Listener in interface Resource
        Type Parameters:
        T - compile-time value of the event­Type argument.
        Parameters:
        event­Type - type of Store­Event to listen (can not be null).
        listener - listener to notify about events.
        Since:
        1.0
      • removeListener

        public <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. The event­Type must be the exact same class than the one given to the add­Listener(…) 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 add­Listener(type, ls) has been invoked twice, then remove­Listener(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 events
        If event­Type is Warning­Event.class and if, after this method invocation, there is no remaining listener for warning events, then this Data­Store will send future warnings to the loggers.
        Specified by:
        remove­Listener in interface Resource
        Type Parameters:
        T - compile-time value of the event­Type argument.
        Parameters:
        event­Type - type of Store­Event which were listened (can not be null).
        listener - listener to stop notifying about events.
        Since:
        1.0
      • addWarningListener

        @Deprecated
        public void addWarningListener​(WarningListener<? super DataStore> listener)
                                throws IllegalArgumentException
        Deprecated.
        Replaced by add­Listener(listener, Warning­Event​.class).
        Adds a listener to be notified when a warning occurred while reading from or writing to the storage. When a warning occurs, there is a choice:
        • If this data store has no warning listener, then the warning is logged at Level​.WARNING.
        • If this data store has at least one warning listener, then all listeners are notified and the warning is not logged by this data store instance.
        Consider invoking this method in a tryfinally block if the Data­Store lifetime is longer than the listener lifetime, as below:
        datastore.addWarningListener(listener);
        try {
            // Do some work...
        } finally {
            datastore.removeWarningListener(listener);
        }
        Parameters:
        listener - the listener to add.
        Throws:
        Illegal­Argument­Exception - if the given listener is already registered in this data store.
      • toString

        public String toString()
        Returns 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.
        Overrides:
        to­String in class Object
        Returns:
        a string representation of this data store for debugging purpose.