org.geotoolkit.metadata.sql
Class MetadataWriter

Object
  MetadataSource
      MetadataWriter

@ThreadSafe
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.

Since:

3.03

Version:

3.20

Author:

Martin Desruisseaux (Geomatys)

Module:

metadata/geotk-metadata-sql (download)

View source code for this class

Field Summary

Fields inherited from class MetadataSource

standard

Constructor Summary

MetadataWriter(MetadataStandard standard, DataSource dataSource, String schema)
Creates a new metadata writer.

MetadataWriter(String url, String schema)
Creates a new metadata writer from the given JDBC URL.

Method Summary

String	add(Object metadata) Adds the given metadata object to the database, if it does not already exists.
NullValuePolicy	getColumnCreationPolicy() Whatever the tables should contain a column for every attributes, or only for non-null and non-empty attributes.
int	getMaximumIdentifierLength() Returns the maximal number of characters allowed for primary keys.
int	getMaximumValueLength() Returns the maximal number of characters allowed in text columns.
void	setColumnCreationPolicy(NullValuePolicy policy) Sets whatever columns should be created only for non-empty attributes, or for all attributes.
void	setMaximumIdentifierLength(int length) Sets the maximal number of characters allowed for primary keys.
void	setMaximumValueLength(int length) Sets the maximal number of characters allowed in text columns.
protected String	suggestIdentifier(Object metadata) Suggests an identifier (primary key) to be used for the given metadata.

Methods inherited from class MetadataSource

close, getEntry, search

Methods inherited from class Object

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

Constructor Detail

MetadataWriter

public MetadataWriter(String url,
                      String schema)
               throws SQLException

Creates a new metadata writer from the given JDBC URL. The URL must be conform to the syntax expected by the Driver.connect(...) method, for example "jdbc:postgresql://localhost/mydatabase".

This convenience method assumes that the metadata standard to be implemented is ISO 19115.

Parameters:

url - The URL to the JDBC database.

schema - The schema were metadata are expected to be found.

Throws:

SQLException - If the connection to the given database can not be established.

MetadataWriter

public MetadataWriter(MetadataStandard standard,
                      DataSource dataSource,
                      String schema)
               throws SQLException

Creates a new metadata writer.

Parameters:

standard - The metadata standard to implement.

dataSource - The source for getting a connection to the database.

schema - The schema were metadata are expected to be found.

Throws:

SQLException - If the connection to the given database can not be established.

Method Detail

getColumnCreationPolicy

public NullValuePolicy getColumnCreationPolicy()

Whatever the tables should contain a column for every attributes, or only for non-null and non-empty attributes. The default is NON-EMPTY, which implies that new columns are added only when first needed.

Returns:

The current policy for column creation.

setColumnCreationPolicy

public void setColumnCreationPolicy(NullValuePolicy policy)

Sets whatever columns should be created only for non-empty attributes, or for all attributes. If this policy is set to ALL, then all columns will be added in newly created tables even if their content is empty.

Parameters:

policy - The new policy for column creation.

getMaximumValueLength

public int getMaximumValueLength()

Returns the 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.

Returns:

The maximal number of characters allowed in text columns.

Since:

3.20

setMaximumValueLength

public void setMaximumValueLength(int length)

Sets the maximal number of characters allowed in text columns. Invoking this method will affect only the new columns to be created, if any. This method has no effect on the table columns that already exist in the database.

Parameters:

length - The maximal number of characters allowed in text columns.

Since:

3.20

getMaximumIdentifierLength

public int getMaximumIdentifierLength()

Returns the maximal number of characters allowed for primary keys. This is the value given to the VARCHAR type when creating new "ID" columns.

Primary keys are automatically generated by MetadataWriter. Values longer than this maximal length are truncated, so there is no need for a very high limit.

Returns:

The maximal number of characters allowed for primary keys.

Since:

3.20

See Also:

suggestIdentifier(Object)

setMaximumIdentifierLength

public void setMaximumIdentifierLength(int length)

Sets the maximal number of characters allowed for primary keys. Invoking this method will affect only the new columns to be created, if any. This method has no effect on the table columns that already exist in the database.

Primary keys should be relatively short, for example no more than 20 characters. Those keys are not visible to the end user, but may be used by the database administrator.

Parameters:

length - The maximal number of characters allowed for primary keys.

Since:

3.20

See Also:

suggestIdentifier(Object)

add

public String add(Object metadata)
           throws ClassCastException,
                  SQLException

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:

SQLException - 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).

ClassCastException - if the metadata object doesn't implement a metadata interface of the expected package.

suggestIdentifier

protected String suggestIdentifier(Object metadata)
                            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 of a few "well known" metadata like Identifier and Citation. Subclasses can override this method for implementing their own heuristic.

This method doesn't 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 for which to suggests an identifier.

Returns:

The proposed identifier, or null if this method doesn't have any suggestion.

Throws:

SQLException - If an access to some database was desired but failed.