Package org.apache.commons.configuration2

# Class DatabaseConfiguration

java.lang.Object
org.apache.commons.configuration2.event.BaseEventSource
org.apache.commons.configuration2.AbstractConfiguration
org.apache.commons.configuration2.DatabaseConfiguration

All Implemented Interfaces:
  `Configuration`, `EventSource`, `ImmutableConfiguration`, `SynchronizerSupport`

public class DatabaseConfiguration extends AbstractConfiguration
Configuration stored in a database. The properties are retrieved from a table containing at least one column for the keys, and one column for the values. It's possible to store several configurations in the same table by adding a column containing the name of the configuration. The name of the table and the columns have to be specified using the corresponding properties.

The recommended way to create an instance of `DatabaseConfiguration` is to use a configuration builder. The builder is configured with a special parameters object defining the database structures used by the configuration. Such an object can be created using the `database()` method of the `Parameters` class. See the examples below for more details.

Example 1 - One configuration per table

     CREATE TABLE myconfig (
         `key`   VARCHAR NOT NULL PRIMARY KEY,
         `value` VARCHAR
     );

     INSERT INTO myconfig (key, value) VALUES ('foo', 'bar');

     BasicConfigurationBuilder<DatabaseConfiguration> builder =
         new BasicConfigurationBuilder<DatabaseConfiguration>(DatabaseConfiguration.class);
     builder.configure(
         Parameters.database()
             .setDataSource(dataSource)
             .setTable("myconfig")
             .setKeyColumn("key")
             .setValueColumn("value")
     );
     Configuration config = builder.getConfiguration();
     String value = config.getString("foo");

Example 2 - Multiple configurations per table

     CREATE TABLE myconfigs (
         `name`  VARCHAR NOT NULL,
         `key`   VARCHAR NOT NULL,
         `value` VARCHAR,
         CONSTRAINT sys_pk_myconfigs PRIMARY KEY (`name`, `key`)
     );

     INSERT INTO myconfigs (name, key, value) VALUES ('config1', 'key1', 'value1');
     INSERT INTO myconfigs (name, key, value) VALUES ('config2', 'key2', 'value2');

     BasicConfigurationBuilder<DatabaseConfiguration> builder =
         new BasicConfigurationBuilder<DatabaseConfiguration>(DatabaseConfiguration.class);
     builder.configure(
         Parameters.database()
             .setDataSource(dataSource)
             .setTable("myconfigs")
             .setKeyColumn("key")
             .setValueColumn("value")
             .setConfigurationNameColumn("name")
             .setConfigurationName("config1")
     );
     Configuration config1 = new DatabaseConfiguration(dataSource, "myconfigs", "name", "key", "value", "config1");
     String value1 = conf.getString("key1");

The configuration can be instructed to perform commits after database updates. This is achieved by setting the `commits` parameter of the constructors to true. If commits should not be performed (which is the default behavior), it should be ensured that the connections returned by the `DataSource` are in auto-commit mode.

Note: Like JDBC itself, protection against SQL injection is left to the user.

Since:
  1.0

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DatabaseConfiguration()`
  Creates a new instance of `DatabaseConfiguration`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `addPropertyDirect(String key, Object obj)`
  Adds a property to this configuration.
  `protected void`
  `addPropertyInternal(String key, Object value)`
  Adds a property to this configuration.
  `protected void`
  `clearInternal()`
  Removes all entries from this configuration.
  `protected void`
  `clearPropertyDirect(String key)`
  Removes the specified value from this configuration.
  `protected void`
  `close(Connection conn, Statement stmt, ResultSet rs)`
  Close the specified database objects.
  `protected boolean`
  `containsKeyInternal(String key)`
  Checks whether this configuration contains the specified key.
  `protected boolean`
  `containsValueInternal(Object value)`
  Tests whether this configuration contains one or more matches to this value.
  `protected Object`
  `extractPropertyValue(ResultSet rs)`
  Extracts the value of a property from the given result set.
  `String`
  `getConfigurationName()`
  Gets the name of this configuration instance.
  `String`
  `getConfigurationNameColumn()`
  Gets the name of the table column with the configuration name.
  `DataSource`
  `getDatasource()`
  Deprecated.
  Use `getDataSource()`
  `DataSource`
  `getDataSource()`
  Gets the `DataSource` for obtaining database connections.
  `String`
  `getKeyColumn()`
  Gets the name of the column containing the configuration keys.
  `protected Iterator<String>`
  `getKeysInternal()`
  Returns an iterator with the names of all properties contained in this configuration.
  `protected Object`
  `getPropertyInternal(String key)`
  Gets the value of the specified property.
  `String`
  `getTable()`
  Gets the name of the table containing configuration data.
  `String`
  `getValueColumn()`
  Gets the name of the column containing the configuration values.
  `boolean`
  `isAutoCommit()`
  Returns a flag whether this configuration performs commits after database updates.
  `protected boolean`
  `isEmptyInternal()`
  Checks if this configuration is empty.
  `void`
  `setAutoCommit(boolean autoCommit)`
  Sets the auto commit flag.
  `void`
  `setConfigurationName(String configurationName)`
  Sets the name of this configuration instance.
  `void`
  `setConfigurationNameColumn(String configurationNameColumn)`
  Sets the name of the table column with the configuration name.
  `void`
  `setDataSource(DataSource dataSource)`
  Sets the `DataSource` for obtaining database connections.
  `void`
  `setKeyColumn(String keyColumn)`
  Sets the name of the column containing the configuration keys.
  `void`
  `setTable(String table)`
  Sets the name of the table containing configuration data.
  `void`
  `setValueColumn(String valueColumn)`
  Sets the name of the column containing the configuration values.

  ### Methods inherited from class org.apache.commons.configuration2.AbstractConfiguration

  `addErrorLogListener, addProperty, append, beginRead, beginWrite, clear, clearProperty, cloneInterpolator, contains, containsKey, containsValue, copy, endRead, endWrite, get, get, getArray, getArray, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getCollection, getCollection, getConfigurationDecoder, getConversionHandler, getDouble, getDouble, getDouble, getDuration, getDuration, getEncodedString, getEncodedString, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getKeys, getKeys, getKeys, getKeysInternal, getKeysInternal, getList, getList, getList, getList, getListDelimiterHandler, getLogger, getLong, getLong, getLong, getProperties, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getStringArray, getSynchronizer, immutableSubset, initLogger, installInterpolator, interpolate, interpolate, interpolatedConfiguration, isEmpty, isScalarValue, isThrowExceptionOnMissing, lock, setConfigurationDecoder, setConversionHandler, setDefaultLookups, setInterpolator, setListDelimiterHandler, setLogger, setParentInterpolator, setPrefixLookups, setProperty, setPropertyInternal, setSynchronizer, setThrowExceptionOnMissing, size, sizeInternal, subset, unlock`

  ### Methods inherited from class org.apache.commons.configuration2.event.BaseEventSource

  `addEventListener, clearErrorListeners, clearEventListeners, clone, copyEventListeners, createErrorEvent, createEvent, fireError, fireEvent, getEventListenerRegistrations, getEventListeners, isDetailEvents, removeEventListener, setDetailEvents`

  ### Methods inherited from class java.lang.Object

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

  ### Methods inherited from interface org.apache.commons.configuration2.ImmutableConfiguration

  `getEnum, getEnum`

- ## Constructor Details

  - ### DatabaseConfiguration

    public DatabaseConfiguration()
    Creates a new instance of `DatabaseConfiguration`.

- ## Method Details

  - ### addPropertyDirect

    protected void addPropertyDirect(String key, Object obj)
    Adds a property to this configuration. If this causes a database error, an error event will be generated of type `ADD_PROPERTY` with the causing exception. The event's `propertyName` is set to the passed in property key, the `propertyValue` points to the passed in value.
    Specified by:
      `addPropertyDirect` in class `AbstractConfiguration`
    Parameters:
      `key` - the property key
      `obj` - the value of the property to add

  - ### addPropertyInternal

    protected void addPropertyInternal(String key, Object value)
    Adds a property to this configuration. This implementation temporarily disables list delimiter parsing, so that even if the value contains the list delimiter, only a single record is written into the managed table. The implementation of `getProperty()` takes care about delimiters. So list delimiters are fully supported by `DatabaseConfiguration`, but internally treated a bit differently.
    Overrides:
      `addPropertyInternal` in class `AbstractConfiguration`
    Parameters:
      `key` - the key of the new property
      `value` - the value to be added

  - ### clearInternal

    protected void clearInternal()
    Removes all entries from this configuration. If this causes a database error, an error event will be generated of type `CLEAR` with the causing exception. Both the event's `propertyName` and the `propertyValue` will be undefined.
    Overrides:
      `clearInternal` in class `AbstractConfiguration`

  - ### clearPropertyDirect

    protected void clearPropertyDirect(String key)
    Removes the specified value from this configuration. If this causes a database error, an error event will be generated of type `CLEAR_PROPERTY` with the causing exception. The event's `propertyName` will be set to the passed in key, the `propertyValue` will be undefined.
    Specified by:
      `clearPropertyDirect` in class `AbstractConfiguration`
    Parameters:
      `key` - the key of the property to be removed

  - ### close

    protected void close(Connection conn, Statement stmt, ResultSet rs)
    Close the specified database objects. Avoid closing if null and hide any SQLExceptions that occur.
    Parameters:
      `conn` - The database connection to close
      `stmt` - The statement to close
      `rs` - the result set to close

  - ### containsKeyInternal

    protected boolean containsKeyInternal(String key)
    Checks whether this configuration contains the specified key. If this causes a database error, an error event will be generated of type `READ` with the causing exception. The event's `propertyName` will be set to the passed in key, the `propertyValue` will be undefined.
    Specified by:
      `containsKeyInternal` in class `AbstractConfiguration`
    Parameters:
      `key` - the key to be checked
    Returns:
      a flag whether this key is defined

  - ### containsValueInternal

    protected boolean containsValueInternal(Object value)
    Tests whether this configuration contains one or more matches to this value. This operation stops at first match but may be more expensive than the containsKey method.
    Specified by:
      `containsValueInternal` in class `AbstractConfiguration`
    Parameters:
      `value` - the value in question
    Returns:
      `true` if and only if some key maps to the `value` argument in this configuration as determined by the `equals` method; `false` otherwise.
    Since:
      2.11.0

  - ### extractPropertyValue

    protected Object extractPropertyValue(ResultSet rs) throws SQLException
    Extracts the value of a property from the given result set. The passed in `ResultSet` was created by a SELECT statement on the underlying database table. This implementation reads the value of the column determined by the `valueColumn` property. Normally the contained value is directly returned. However, if it is of type `CLOB`, text is extracted as string.
    Parameters:
      `rs` - the current `ResultSet`
    Returns:
      the value of the property column
    Throws:
      `SQLException` - if an error occurs

  - ### getConfigurationName

    public String getConfigurationName()
    Gets the name of this configuration instance.
    Returns:
      the name of this configuration

  - ### getConfigurationNameColumn

    public String getConfigurationNameColumn()
    Gets the name of the table column with the configuration name.
    Returns:
      the name of the configuration name column

  - ### getDatasource

    @Deprecated public DataSource getDatasource()
    Deprecated.
    Use `getDataSource()`
    Gets the used `DataSource` object.
    Returns:
      the data source
    Since:
      1.4

  - ### getDataSource

    public DataSource getDataSource()
    Gets the `DataSource` for obtaining database connections.
    Returns:
      the `DataSource`

  - ### getKeyColumn

    public String getKeyColumn()
    Gets the name of the column containing the configuration keys.
    Returns:
      the name of the key column

  - ### getKeysInternal

    protected Iterator<String> getKeysInternal()
    Returns an iterator with the names of all properties contained in this configuration. If this causes a database error, an error event will be generated of type `READ` with the causing exception. Both the event's `propertyName` and the `propertyValue` will be undefined.
    Specified by:
      `getKeysInternal` in class `AbstractConfiguration`
    Returns:
      an iterator with the contained keys (an empty iterator in case of an error)

  - ### getPropertyInternal

    protected Object getPropertyInternal(String key)
    Gets the value of the specified property. If this causes a database error, an error event will be generated of type `READ` with the causing exception. The event's `propertyName` is set to the passed in property key, the `propertyValue` is undefined.
    Specified by:
      `getPropertyInternal` in class `AbstractConfiguration`
    Parameters:
      `key` - the key of the desired property
    Returns:
      the value of this property

  - ### getTable

    public String getTable()
    Gets the name of the table containing configuration data.
    Returns:
      the name of the table to be queried

  - ### getValueColumn

    public String getValueColumn()
    Gets the name of the column containing the configuration values.
    Returns:
      the name of the value column

  - ### isAutoCommit

    public boolean isAutoCommit()
    Returns a flag whether this configuration performs commits after database updates.
    Returns:
      a flag whether commits are performed

  - ### isEmptyInternal

    protected boolean isEmptyInternal()
    Checks if this configuration is empty. If this causes a database error, an error event will be generated of type `READ` with the causing exception. Both the event's `propertyName` and `propertyValue` will be undefined.
    Specified by:
      `isEmptyInternal` in class `AbstractConfiguration`
    Returns:
      a flag whether this configuration is empty.

  - ### setAutoCommit

    public void setAutoCommit(boolean autoCommit)
    Sets the auto commit flag. If set to true, this configuration performs a commit after each database update.
    Parameters:
      `autoCommit` - the auto commit flag

  - ### setConfigurationName

    public void setConfigurationName(String configurationName)
    Sets the name of this configuration instance.
    Parameters:
      `configurationName` - the name of this configuration

  - ### setConfigurationNameColumn

    public void setConfigurationNameColumn(String configurationNameColumn)
    Sets the name of the table column with the configuration name.
    Parameters:
      `configurationNameColumn` - the name of the column with the configuration name

  - ### setDataSource

    public void setDataSource(DataSource dataSource)
    Sets the `DataSource` for obtaining database connections.
    Parameters:
      `dataSource` - the `DataSource`

  - ### setKeyColumn

    public void setKeyColumn(String keyColumn)
    Sets the name of the column containing the configuration keys.
    Parameters:
      `keyColumn` - the name of the key column

  - ### setTable

    public void setTable(String table)
    Sets the name of the table containing configuration data.
    Parameters:
      `table` - the table name

  - ### setValueColumn

    public void setValueColumn(String valueColumn)
    Sets the name of the column containing the configuration values.
    Parameters:
      `valueColumn` - the name of the value column