Package org.apache.sis.storage

Interface Resource

  • All Known Subinterfaces:
    Aggregate, Data­Set, Feature­Set, Grid­Coverage­Resource, Writable­Aggregate, Writable­Feature­Set
    All Known Implementing Classes:
    Data­Store, Geo­Tiff­Store, Landsat­Store, Netcdf­Store, SQLStore
    public interface Resource
    Provides access to geospatial data in a Data­Store. The ISO 19115 specification defines resource as an “identifiable asset or means that fulfills a requirement”. For example a resource can be a coverage of Sea Surface Temperature, or a coverage of water salinity, or the set of all buoys in a harbor, or an aggregation of all the above. A resource is not necessarily digital; it can be a paper document or an organization, in which case only metadata are provided. If the resource is digital, then Resources should be instances of sub-types like Aggregate or Feature­Set.

    Data­Stores are themselves closeable resources. If the data store contains resources for many feature types or coverages, then the data store will be an instance of Aggregate. The components of an aggregate can be themselves other aggregates, thus forming a tree.

    Relationship with ISO 19115: this type is closely related to the DS_Resource type defined by ISO 19115. The Apache SIS type differs from the ISO type by being more closely related to data extraction, as can been seen from the checked Data­Store­Exception thrown by most methods. Convenience methods for frequently requested information – for example Data­Set​.get­Envelope() – were added. The sub-types performing the actual data extraction – for example Feature­Set – are specific to Apache SIS.
    Since:
    0.8
    See Also:
    Aggregate​.components()

    Defined in the sis-storage module

    • Method Detail

      • getIdentifier

        Optional<GenericName> getIdentifier()
                             throws DataStoreException
        Returns the resource persistent identifier. This identifier can be used to uniquely identify a resource in the containing Data­Store. For this identifier to be reliable the following conditions must hold:
        • It shall be unique in the Data­Store which contains it, if there is one.
        • It's value shall not change after closing and reopening the Data­Store on the same data.
        • It should be consistent with the get­Metadata()/​identification­Info/​citation/​identifier value.
        If any of above conditions is not met, then this identifier should be absent. This case may happen when a resource is an intermediate result of an ongoing process or is a temporary resource generated on-the-fly, for example a sensor event.
        Returns:
        a persistent identifier unique within the data store, or absent if this resource has no such identifier.
        Throws:
        Data­Store­Exception - if an error occurred while fetching the identifier.
        Since:
        1.0
        See Also:
        Data­Store​.get­Identifier(), Data­Store​.find­Resource(String)

      • addListener

        <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 resource or in children. The resource 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 resource 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 different resources in the same tree, for example a parent and its children.

        If this resource 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 Resource is itself garbage collected. However if the given type of events can never happen with this resource, 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 resource. 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.
        Type Parameters:
        T - compile-time value of the event­Type argument.
        Parameters:
        listener - listener to notify about events.
        event­Type - type of Store­Event to listen (can not be null).

      • removeListener

        <T extends StoreEvent> void removeListener​(Class<T> eventType,
                                           StoreListener<? super T> listener)
        Unregisters a listener previously added to this resource 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 parent 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 Resource will send future warnings to the loggers.
        Type Parameters:
        T - compile-time value of the event­Type argument.
        Parameters:
        listener - listener to stop notifying about events.
        event­Type - type of Store­Event which were listened (can not be null).