Module org.apache.sis.storage
Package org.apache.sis.storage

Interface Resource

All Known Subinterfaces:
Aggregate, Data­Set, Feature­Set, Grid­Coverage­Resource, Tiled­Resource, Writable­Aggregate, Writable­Feature­Set, Writable­Grid­Coverage­Resource, Writable­Tiled­Resource
All Known Implementing Classes:
Abstract­Feature­Set, Abstract­Grid­Coverage­Resource, Abstract­Resource, Concatenated­Feature­Set, Data­Store, Geo­Tiff­Store, Join­Feature­Set, 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 be 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:

  • Method Details

    • 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:

    • getMetadata

      Metadata getMetadata() throws DataStoreException
      Returns information about this resource. If this resource is an Aggregate, then the metadata may enumerate characteristics (spatiotemporal extents, feature types, range dimensions, etc.) of all components in the aggregate, or summarize them (for example by omitting extents that are fully included in larger extents). If this resource is a Data­Set, then the metadata shall contain only the information that apply to that particular dataset, optionally with a reference to the parent metadata (see below).

      Some relationships between metadata and resources are:

      Metadata edition

      This method often returns an unmodifiable metadata, for making possible to return efficiently a cached instance. If the caller wants to modify some metadata elements, it may be necessary to perform a deep copy first.
      Returns:
      information about this resource. Should not be null.
      Throws:
      Data­Store­Exception - if an error occurred while reading the metadata.
      See Also:

    • 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:
      event­Type - type of Store­Events to listen (cannot be null).
      listener - listener to notify about events.

    • 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 are no remaining listeners 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:
      event­Type - type of Store­Events which were listened (cannot be null).
      listener - listener to stop notifying about events.