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 `MD_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 and Description
    --- | ---
    `protected MetadataStandard` | `standard` The metadata standard to be used for constructing the database schema.

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addWarningListener(WarningListener<? super MetadataSource> listener)` Adds a listener to be notified when a warning occurred while reading from or writing metadata.
    `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)` Removes a previously registered listener.
    `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()
                                            throws MetadataStoreException

      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.
      Returns:
        source of pre-defined metadata records from the `"jdbc/SpatialMetadata"` database.
      Throws:
        `MetadataStoreException` - if this method can not connect to the 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

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

      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

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

      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.

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.