Package org.apache.sis.metadata.sql

## Class MetadataWriter

- Object
- - MetadataSource
  - - MetadataWriter

- All Implemented Interfaces:
    `AutoCloseable`

      public class MetadataWriter
      extends MetadataSource

  A connection to a metadata database with write capabilities. The database must have a schema of the given name, which can be initially empty. Tables and columns are created as needed when the `add(Object)` method is invoked.

  No more than one instance of `MetadataWriter` should be used for the same database. However multiple instances of `MetadataSource` can be used concurrently with a single `MetadataWriter` instance on the same database.

  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.
  `"maximumIdentifierLength"` | `Integer` | The maximal number of characters allowed for primary keys. This is the value given to the `VARCHAR` type when creating new `"ID"` columns.
  `"maximumValueLength"` | `Integer` | Maximal number of characters allowed in text columns. This is the parameter given to the `VARCHAR` type when creating new columns. Attempts to insert a text longer than this limit will typically throws a `SQLException`, but the exact behavior is database-dependent.
  `"columnCreationPolicy"` | `ValueExistencePolicy` | Whether columns should be created only for non-empty attributes (`NON_EMPTY`, the default) or for all attributes (`ALL`)

  Since:
    0.8

  Defined in the `sis-metadata` module

- - ### Field Summary

    - ### Fields inherited from class MetadataSource

      `standard`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `MetadataWriter​(MetadataStandard standard, DataSource dataSource, String schema, Map<String,​?> properties)` | Creates a new metadata writer.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `String` | `add​(Object metadata)` | Adds the given metadata object to the database, if it does not already exists.
    `protected String` | `suggestIdentifier​(Object metadata, Map<String,​Object> asValueMap)` | Suggests an identifier (primary key) to be used for the given metadata.

    - ### Methods inherited from class MetadataSource

      `addWarningListener, close, getProvided, lookup, removeWarningListener, search`

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### MetadataWriter

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

      Creates a new metadata writer.
      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.

  - ### Method Detail

    - #### add

          public String add​(Object metadata)
                     throws MetadataStoreException

      Adds the given metadata object to the database, if it does not already exists. If the database already contains a metadata equals to the given one, then the database is left unchanged and the identifier of the existing metadata is returned.
      Parameters:
        `metadata` - the metadata object to add.
      Returns:
        the identifier (primary key) of the metadata just added, or the identifier of the existing metadata is one exists.
      Throws:
        `MetadataStoreException` - if the metadata object does not implement a metadata interface of the expected package, if an exception occurred while reading or writing the database. In such case, the database content is left unchanged (i.e. this method is a all or nothing operation).

    - #### suggestIdentifier

          protected String suggestIdentifier​(Object metadata,
                                             Map<String,​Object> asValueMap)
                                      throws SQLException

      Suggests an identifier (primary key) to be used for the given metadata. This method is invoked automatically when a new metadata is about to be inserted in the database. The default implementation uses heuristic rules for a few "well known" metadata like `Identifier` and `Citation`. Subclasses can override this method for implementing their own heuristic.

      This method does not need to care about key collision. The caller will adds some suffix if this is necessary for differentiating otherwise identical identifiers.

      Parameters:
        `metadata` - the metadata instance for which to suggests an identifier.
        `asValueMap` - a view of all metadata properties as a map. Keys are UML identifiers.
      Returns:
        the proposed identifier, or `null` if this method does not have any suggestion.
      Throws:
        `SQLException` - if an access to the database was desired but failed.