Package org.apache.sis.metadata.sql

## Class MetadataSource

- Object
- - MetadataSource

- All Implemented Interfaces:
    `AutoCloseable`
  Direct Known Subclasses:
    `MetadataWriter`

      public class MetadataSource
      extends Object
      implements AutoCloseable

  A connection to a metadata database in read-only mode. It can be either the database provided by Apache SIS with pre-defined ISO 19115 metadata, or another database specified at construction time. Metadata instances can be obtained as in the example below:

  >     MetadataSource metadata = MetadataSource.getProvided();
  >     Format format = source.lookup(Format.class, "PNG");

  where `id` is the primary key value for the desired record in the `Format` table.
  Properties
  The constructor expects three Java arguments (the metadata standard, the data source and the database schema) completed by an arbitrary amount of optional arguments given as a map of properties. The following keys are recognized by `MetadataSource` and all other entries are ignored:

  Optional properties at construction time
  Key | Value type | Description
  --- | --- | ---
  `"catalog"` | `String` | The database catalog where the metadata schema is stored.
  `"classloader"` | `ClassLoader` | The class loader to use for creating `Proxy` instances.
  `"maxStatements"` | `Integer` | Maximal number of `PreparedStatement`s that can be kept simultaneously open.

  Concurrency
  `MetadataSource` is thread-safe but is not concurrent. If concurrency is desired, multiple instances of `MetadataSource` can be created for the same `DataSource`. The `MetadataSource(MetadataSource)` convenience constructor can be used for this purpose.
  Since:
    0.8

  Defined in the `sis-metadata` module

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected MetadataStandard` | `standard` | The metadata standard to be used for constructing the database schema.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `MetadataSource​(MetadataStandard standard, DataSource dataSource, String schema, Map<String,​?> properties)` | Creates a new metadata source.
    `MetadataSource​(MetadataSource source)` | Creates a new metadata source with the same configuration than the given source.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addWarningListener​(WarningListener<? super MetadataSource> listener)` | Deprecated. `WarningListener` to be replaced by `Filter`.
    `void` | `close()` | Closes the database connection used by this object.
    `static MetadataSource` | `getProvided()` | Returns the metadata source connected to the `"jdbc/SpatialMetadata"` database.
    `<T> T` | `lookup​(Class<T> type, String identifier)` | Returns an implementation of the specified metadata interface filled with the data referenced by the specified identifier.
    `void` | `removeWarningListener​(WarningListener<? super MetadataSource> listener)` | Deprecated. `WarningListener` to be replaced by `Filter`.
    `String` | `search​(Object metadata)` | Searches for the given metadata in the database.

    - ### Methods inherited from class Object

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

- - ### Field Detail

    - #### standard

          protected final MetadataStandard standard

      The metadata standard to be used for constructing the database schema.

  - ### Constructor Detail

    - #### MetadataSource

          public MetadataSource​(MetadataStandard standard,
                                DataSource dataSource,
                                String schema,
                                Map<String,​?> properties)

      Creates a new metadata source. The metadata standard to implement (typically ISO 19115, but not necessarily) and the database source are mandatory information. All other information are optional and can be `null`.
      Parameters:
        `standard` - the metadata standard to implement.
        `dataSource` - the source for getting a connection to the database.
        `schema` - the database schema were metadata tables are stored, or `null` if none.
        `properties` - additional options, or `null` if none. See class javadoc for a description.

    - #### MetadataSource

          public MetadataSource​(MetadataSource source)

      Creates a new metadata source with the same configuration than the given source. The two `MetadataSource` instances will share the same `DataSource` but will use their own `Connection`. This constructor is useful when concurrency is desired.

      The new `MetadataSource` initially contains all warning listeners declared in the given `source`. But listeners added or removed in a `MetadataSource` after the construction will not impact the other `MetadataSource` instance.

      Parameters:
        `source` - the source from which to copy the configuration.

  - ### Method Detail

    - #### getProvided

          public static MetadataSource getProvided()

      Returns the metadata source connected to the `"jdbc/SpatialMetadata"` database. In a default Apache SIS installation, this metadata source contains pre-defined records for some commonly used citations and formats among others.

      If connection to the metadata database can not be established, then this method returns a fallback with a few hard-coded values.

      Returns:
        source of pre-defined metadata records from the `"jdbc/SpatialMetadata"` database.

    - #### search

          public String search​(Object metadata)
                        throws MetadataStoreException

      Searches for the given metadata in the database. If such metadata is found, then its identifier (primary key) is returned. Otherwise this method returns `null`.
      Parameters:
        `metadata` - the metadata to search for.
      Returns:
        the identifier of the given metadata, or `null` if none.
      Throws:
        `MetadataStoreException` - if the metadata object does not implement a metadata interface of the expected package, or if an error occurred while searching in the database.

    - #### lookup

          public <T> T lookup​(Class<T> type,
                              String identifier)
                       throws MetadataStoreException

      Returns an implementation of the specified metadata interface filled with the data referenced by the specified identifier. Alternatively, this method can also return a `CodeList` or `Enum` element.
      Type Parameters:
        `T` - the parameterized type of the `type` argument.
      Parameters:
        `type` - the interface to implement (e.g. `Citation`), or the `ControlledVocabulary` type (`CodeList` or some `Enum`).
        `identifier` - the identifier of the record for the metadata entity to be created. This is usually the primary key of the record to search for.
      Returns:
        an implementation of the required interface, or the code list element.
      Throws:
        `MetadataStoreException` - if a SQL query failed.

    - #### addWarningListener

          @Deprecated
          public void addWarningListener​(WarningListener<? super MetadataSource> listener)
                                  throws IllegalArgumentException

      Deprecated.
      `WarningListener` to be replaced by `Filter`.
      Adds a listener to be notified when a warning occurred while reading from or writing metadata. When a warning occurs, there is a choice:
      - If this metadata source has no warning listener, then the warning is logged at `Level​.WARNING`.
      - If this metadata source has at least one warning listener, then all listeners are notified and the warning is not logged by this metadata source instance.
      Consider invoking this method in a `try` … `finally` block if the `MetadataSource` lifetime is longer than the listener lifetime, as below:

      >     source.addWarningListener(listener);
      >     try {
      >         // Do some work...
      >     } finally {
      >         source.removeWarningListener(listener);
      >     }

      Parameters:
        `listener` - the listener to add.
      Throws:
        `IllegalArgumentException` - if the given listener is already registered in this metadata source.

    - #### removeWarningListener

          @Deprecated
          public void removeWarningListener​(WarningListener<? super MetadataSource> listener)
                                     throws NoSuchElementException

      Deprecated.
      `WarningListener` to be replaced by `Filter`.
      Removes a previously registered listener.
      Parameters:
        `listener` - the listener to remove.
      Throws:
        `NoSuchElementException` - if the given listener is not registered in this metadata source.

    - #### close

          public void close()
                     throws MetadataStoreException

      Closes the database connection used by this object.
      Specified by:
        `close` in interface `AutoCloseable`
      Throws:
        `MetadataStoreException` - if an error occurred while closing the connection.