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

    All Methods Instance Methods Concrete Methods
    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 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()` | Gets the used `DataSource` object.
    `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, containsKey, 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, 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 Detail

    - #### DatabaseConfiguration

          public DatabaseConfiguration()

      Creates a new instance of `DatabaseConfiguration`.

  - ### Method Detail

    - #### getDataSource

          public DataSource getDataSource()

      Gets the `DataSource` for obtaining database connections.
      Returns:
        the `DataSource`

    - #### setDataSource

          public void setDataSource​(DataSource dataSource)

      Sets the `DataSource` for obtaining database connections.
      Parameters:
        `dataSource` - the `DataSource`

    - #### getTable

          public String getTable()

      Gets the name of the table containing configuration data.
      Returns:
        the name of the table to be queried

    - #### setTable

          public void setTable​(String table)

      Sets the name of the table containing configuration data.
      Parameters:
        `table` - the table name

    - #### getConfigurationNameColumn

          public String getConfigurationNameColumn()

      Gets the name of the table column with the configuration name.
      Returns:
        the name of the configuration name column

    - #### 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

    - #### getKeyColumn

          public String getKeyColumn()

      Gets the name of the column containing the configuration keys.
      Returns:
        the name of the key column

    - #### setKeyColumn

          public void setKeyColumn​(String keyColumn)

      Sets the name of the column containing the configuration keys.
      Parameters:
        `keyColumn` - the name of the key column

    - #### getValueColumn

          public String getValueColumn()

      Gets the name of the column containing the configuration values.
      Returns:
        the name of the value column

    - #### setValueColumn

          public void setValueColumn​(String valueColumn)

      Sets the name of the column containing the configuration values.
      Parameters:
        `valueColumn` - the name of the value column

    - #### getConfigurationName

          public String getConfigurationName()

      Gets the name of this configuration instance.
      Returns:
        the name of this configuration

    - #### setConfigurationName

          public void setConfigurationName​(String configurationName)

      Sets the name of this configuration instance.
      Parameters:
        `configurationName` - the name of this configuration

    - #### isAutoCommit

          public boolean isAutoCommit()

      Returns a flag whether this configuration performs commits after database updates.
      Returns:
        a flag whether commits are performed

    - #### 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

    - #### 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

    - #### 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

    - #### 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.

    - #### 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

    - #### 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

    - #### 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`

    - #### 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)

    - #### getDatasource

          public DataSource getDatasource()

      Gets the used `DataSource` object.
      Returns:
        the data source
      Since:
        1.4

    - #### 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

    - #### 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