Package org.apache.sis.storage.sql

# Class SQLStore

Object
DataStore
SQLStore

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

public class SQLStore extends DataStore implements Aggregate
A data store capable to read and create features from a spatial database. `SQLStore` requires a `DataSource` to be specified (indirectly) at construction time. The `DataSource` should provide pooled connections, because `SQLStore` will frequently opens and closes them.

Since:
  1.0

Defined in the `sis-sqlstore` module

- ## Field Summary

  ### Fields inherited from class DataStore

  `listeners, provider`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SQLStore(SQLStoreProvider provider, StorageConnector connector, ResourceDefinition... resources)`
  Creates a new `SQLStore` for the given data source and tables, views or queries.
  `SQLStore(SQLStoreProvider provider, StorageConnector connector, GenericName... tableNames)`
  Deprecated.
  Replaced by `SQLStore(SQLStoreProvider, StorageConnector, ResourceDefinition...)`.

- ## 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 SQL store and releases any underlying resources.
  `Collection<FeatureSet>`
  `components()`
  Returns the tables (feature sets) in this SQL store.
  `FeatureSet`
  `findResource(String identifier)`
  Searches for a resource identified by the given identifier.
  `Optional<GenericName>`
  `getIdentifier()`
  SQL data store root resource has no identifier.
  `Metadata`
  `getMetadata()`
  Returns information about the dataset as a whole.
  `Optional<ParameterValueGroup>`
  `getOpenParameters()`
  Returns the parameters used to open this netCDF data store.

  ### Methods inherited from class DataStore

  `getDisplayName, getLocale, getNativeMetadata, getProvider, removeListener, setLocale, toString`

  ### Methods inherited from class Object

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

  ### Methods inherited from interface Resource

  `removeListener`

- ## Constructor Details

  - ### SQLStore

    @Deprecated public SQLStore(SQLStoreProvider provider, StorageConnector connector, GenericName... tableNames) throws DataStoreException
    Deprecated.
    Replaced by `SQLStore(SQLStoreProvider, StorageConnector, ResourceDefinition...)`.
    Creates a new instance for the given storage. The given `connector` shall contain a `DataSource`. The given table names shall be qualified names of 1, 2 or 3 components. The name components are `<catalog>.<schema pattern>.<table pattern>` where:
    - `<catalog>`, if present, is the name of a catalog as stored in the database.
    - `<schema pattern>`, if present, is the pattern of a schema. The pattern can use `'_'` and `'%'` wildcards characters.
    - `<table pattern>` (mandatory) is the pattern of a table. The pattern can use `'_'` and `'%'` wildcards characters.
    Qualified table names can be created by the `SQLStoreProvider​.createTableName(String, String, String)` convenience method. Only the main tables need to be specified; dependencies will be followed automatically.
    Parameters:
      `provider` - the factory that created this `DataStore` instance, or `null` if unspecified.
      `connector` - information about the storage (JDBC data source, etc).
      `tableNames` - fully qualified names (including catalog and schema) of the tables to include in this store.
    Throws:
      `DataStoreException` - if an error occurred while creating the data store for the given storage.

  - ### SQLStore

    public SQLStore(SQLStoreProvider provider, StorageConnector connector, ResourceDefinition... resources) throws DataStoreException
    Creates a new `SQLStore` for the given data source and tables, views or queries. The given `connector` shall contain a `DataSource` instance. Tables or views to include in the store are specified by the `resources` argument. Only the main tables need to be specified; dependencies will be followed automatically.
    Parameters:
      `provider` - the factory that created this `DataStore` instance, or `null` if unspecified.
      `connector` - information about the storage (JDBC data source, etc).
      `resources` - tables, views or queries to include in this store.
    Throws:
      `DataStoreException` - if an error occurred while creating the data store for the given storage.
    Since:
      1.1

- ## Method Details

  - ### getOpenParameters

    public Optional<ParameterValueGroup> getOpenParameters()
    Returns the parameters used to open this netCDF data store. The parameters are described by `SQLStoreProvider​.getOpenParameters()` and contains at least a parameter named "location" with a `DataSource` value.
    Specified by:
      `getOpenParameters` in class `DataStore`
    Returns:
      parameters used for opening this data store.
    See Also:
      - `DataStoreProvider​.getOpenParameters()`

  - ### getIdentifier

    public Optional<GenericName> getIdentifier() throws DataStoreException
    SQL data store root resource has no identifier.
    Specified by:
      `getIdentifier` in interface `Resource`
    Overrides:
      `getIdentifier` in class `DataStore`
    Returns:
      empty.
    Throws:
      `DataStoreException` - if an error occurred while fetching the identifier.
    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 list of feature types.
    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)`

  - ### components

    public Collection<FeatureSet> components() throws DataStoreException
    Returns the tables (feature sets) in this SQL store. The list contains only the tables explicitly named at construction time.
    Specified by:
      `components` in interface `Aggregate`
    Returns:
      children resources that are components of this SQL store.
    Throws:
      `DataStoreException` - if an error occurred while fetching the components.

  - ### findResource

    public FeatureSet findResource(String identifier) throws DataStoreException
    Searches for a resource identified by the given identifier. The given identifier should match one of the table names. It may be one of the tables named at construction time, or one of the dependencies. The given name may be qualified with the schema name, or may be only the table name if there is no ambiguity.
    Overrides:
      `findResource` in class `DataStore`
    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:
      - `Resource​.getIdentifier()`
      - `FeatureNaming`

  - ### 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 (can not be `null`).
      `listener` - listener to notify about events.

  - ### close

    public void close() throws DataStoreException
    Closes this SQL store and releases any underlying resources.
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in class `DataStore`
    Throws:
      `DataStoreException` - if an error occurred while closing the SQL store.