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

# Class NetcdfStore

Object
DataStore
NetcdfStore

All Implemented Interfaces:
  `AutoCloseable`, `Aggregate`, `Resource`, `Localized`

public class NetcdfStore extends DataStore implements Aggregate
A data store backed by netCDF files. Instances of this data store are created by `NetcdfStoreProvider​.open(StorageConnector)`.

Since:
  0.3
See Also:
  - `NetcdfStoreProvider`

- ## Field Summary

  ### Fields inherited from class DataStore

  `listeners, provider`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `NetcdfStore(NetcdfStoreProvider provider, StorageConnector connector)`
  Creates a new netCDF store from the given file, URL, stream or `NetcdfFile` object.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<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.
  `void`
  `close()`
  Closes this netCDF store and releases any underlying resources.
  `Collection<Resource>`
  `components()`
  Returns the resources (features or coverages) in this netCDF store.
  `Version`
  `getConventionVersion()`
  Returns the version number of the Climate and Forecast (CF) conventions used in the netCDF file.
  `Optional<GenericName>`
  `getIdentifier()`
  Returns an identifier constructed from global attributes or the filename of the netCDF file.
  `Metadata`
  `getMetadata()`
  Returns information about the dataset as a whole.
  `Optional<TreeTable>`
  `getNativeMetadata()`
  Returns netCDF attributes.
  `Optional<ParameterValueGroup>`
  `getOpenParameters()`
  Returns the parameters used to open this netCDF data store.
  `String`
  `toString()`
  Returns a string representation of this netCDF store for debugging purpose.

  ### Methods inherited from class DataStore

  `findResource, getDisplayName, getLocale, getProvider, removeListener, setLocale`

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface Resource

  `removeListener`

- ## Constructor Details

  - ### NetcdfStore

    public NetcdfStore(NetcdfStoreProvider provider, StorageConnector connector) throws DataStoreException
    Creates a new netCDF store from the given file, URL, stream or `NetcdfFile` object. This constructor invokes `StorageConnector​.closeAllExcept(Object)`, keeping open only the needed resource.
    Parameters:
      `provider` - the factory that created this `DataStore` instance, or `null` if unspecified.
      `connector` - information about the storage (URL, stream, `NetcdfFile` instance, etc).
    Throws:
      `DataStoreException` - if an error occurred while opening the netCDF file.
    Since:
      0.8

- ## Method Details

  - ### getOpenParameters

    public Optional<ParameterValueGroup> getOpenParameters()
    Returns the parameters used to open this netCDF data store. If non-null, the parameters are described by `NetcdfStoreProvider​.getOpenParameters()` and contains at least a parameter named "location" with a `URI` value. This method may return `null` if the storage input cannot be described by a URI (for example a netCDF file reading directly from a `ReadableByteChannel`).
    Specified by:
      `getOpenParameters` in class `DataStore`
    Returns:
      parameters used for opening this data store.
    Since:
      0.8
    See Also:
      - `DataStoreProvider​.getOpenParameters()`

  - ### getConventionVersion

    public Version getConventionVersion() throws DataStoreException
    Returns the version number of the Climate and Forecast (CF) conventions used in the netCDF file. The use of CF convention is mandated by the OGC 11-165r2 standard (CF-netCDF3 Data Model Extension standard).
    Returns:
      CF-convention version, or `null` if no information about CF convention has been found.
    Throws:
      `DataStoreException` - if an error occurred while reading the data.
    Since:
      0.8

  - ### getIdentifier

    public Optional<GenericName> getIdentifier() throws DataStoreException
    Returns an identifier constructed from global attributes or the filename of the netCDF file.
    Specified by:
      `getIdentifier` in interface `Resource`
    Overrides:
      `getIdentifier` in class `DataStore`
    Returns:
      the identifier fetched from global attributes or the filename. May be absent.
    Throws:
      `DataStoreException` - if an error occurred while fetching the identifier.
    Since:
      1.0
    See Also:
      - `DataStore​.getMetadata()`
      - `DataStore​.getDisplayName()`

  - ### getMetadata

    public Metadata getMetadata() throws DataStoreException
    Returns information about the dataset as a whole. The returned metadata object can contain information such as the spatiotemporal extent of the dataset, contact information about the creator or distributor, data quality, usage constraints and more.
    Specified by:
      `getMetadata` in interface `Resource`
    Specified by:
      `getMetadata` in class `DataStore`
    Returns:
      information about the dataset.
    Throws:
      `DataStoreException` - if an error occurred while reading the data.
    See Also:
      - `DataStore​.getIdentifier()`
      - `DefaultMetadata​.deepCopy(Metadata)`

  - ### getNativeMetadata

    public Optional<TreeTable> getNativeMetadata() throws DataStoreException
    Returns netCDF attributes. The meaning of those attributes may vary depending on data provider. The standard metadata should be preferred since they allow abstraction of data format details, but those native metadata are sometimes useful when an information is not provided by the standard metadata.
    Overrides:
      `getNativeMetadata` in class `DataStore`
    Returns:
      resources information structured in an implementation-specific way.
    Throws:
      `DataStoreException` - if an error occurred while reading the metadata.
    Since:
      1.1

  - ### components

    public Collection<Resource> components() throws DataStoreException
    Returns the resources (features or coverages) in this netCDF store.
    Specified by:
      `components` in interface `Aggregate`
    Returns:
      children resources that are components of this netCDF store.
    Throws:
      `DataStoreException` - if an error occurred while fetching the components.
    Since:
      0.8

  - ### 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. The current implementation of this data store can emit only `WarningEvent`s; any listener specified for another kind of events will be ignored.
    Specified by:
      `addListener` in interface `Resource`
    Overrides:
      `addListener` in class `DataStore`
    Type Parameters:
      `T` - compile-time value of the `eventType` argument.
    Parameters:
      `eventType` - type of `StoreEvent` to listen (cannot be `null`).
      `listener` - listener to notify about events.

  - ### close

    public void close() throws DataStoreException
    Closes this netCDF store and releases any underlying resources. This method can be invoked asynchronously for interrupting a long reading process.
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in class `DataStore`
    Throws:
      `DataStoreException` - if an error occurred while closing the netCDF file.
    See Also:
      - `StoreListeners​.close()`

  - ### toString

    public String toString()
    Returns a string representation of this netCDF store for debugging purpose. The content of the string returned by this method may change in any future SIS version.
    Overrides:
      `toString` in class `DataStore`
    Returns:
      a string representation of this data store for debugging purpose.