## org.apache.commons.configuration
Class DatabaseConfiguration

    java.lang.Object
      org.apache.commons.configuration.event.EventSource
          org.apache.commons.configuration.AbstractConfiguration
              org.apache.commons.configuration.DatabaseConfiguration

All Implemented Interfaces:
  Configuration

    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 is specified in the constructor.

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

     Configuration config = new DatabaseConfiguration(datasource, "myconfig", "key", "value");
     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');

     Configuration config1 = new DatabaseConfiguration(datasource, "myconfigs", "name", "key", "value", "config1");
     String value1 = conf.getString("key1");

     Configuration config2 = new DatabaseConfiguration(datasource, "myconfigs", "name", "key", "value", "config2");
     String value2 = conf.getString("key2");

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
Version:
  $Id: DatabaseConfiguration.java 1208807 2011-11-30 21:34:29Z oheger $
Author:
  Emmanuel Bourg

Field Summary

Fields inherited from class org.apache.commons.configuration.AbstractConfiguration
`END_TOKEN, EVENT_ADD_PROPERTY, EVENT_CLEAR, EVENT_CLEAR_PROPERTY, EVENT_READ_PROPERTY, EVENT_SET_PROPERTY, START_TOKEN`

Constructor Summary
`DatabaseConfiguration(DataSource datasource, String table, String keyColumn, String valueColumn)` Build a configuration from a table.
`DatabaseConfiguration(DataSource datasource, String table, String keyColumn, String valueColumn, boolean commits)` Creates a new instance of `DatabaseConfiguration` that operates on a database table containing a single configuration only.
`DatabaseConfiguration(DataSource datasource, String table, String nameColumn, String keyColumn, String valueColumn, String name)` Build a configuration from a table containing multiple configurations.
`DatabaseConfiguration(DataSource datasource, String table, String nameColumn, String keyColumn, String valueColumn, String name, boolean commits)` Creates a new instance of `DatabaseConfiguration` that operates on a database table containing multiple configurations.

Method Summary
`void` `addProperty(String key, Object value)` Adds a property to this configuration.
`protected void` `addPropertyDirect(String key, Object obj)` Adds a property to this configuration.
`void` `clear()` Removes all entries from this configuration.
`protected void` `clearPropertyDirect(String key)` Removes the specified value from this configuration.
`boolean` `containsKey(String key)` Checks whether this configuration contains the specified key.
`protected Connection` `getConnection()` Deprecated. Use a custom data source to change the connection used by the class. To be removed in Commons Configuration 2.0
`DataSource` `getDatasource()` Returns the used `DataSource` object.
`Iterator<String>` `getKeys()` Returns an iterator with the names of all properties contained in this configuration.
`Object` `getProperty(String key)` Returns the value of the specified property.
`boolean` `isDoCommits()` Returns a flag whether this configuration performs commits after database updates.
`boolean` `isEmpty()` Checks if this configuration is empty.

Methods inherited from class org.apache.commons.configuration.AbstractConfiguration

`addErrorLogListener, append, clearProperty, copy, createInterpolator, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDefaultListDelimiter, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getKeys, getList, getList, getListDelimiter, getLogger, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, getSubstitutor, interpolate, interpolate, interpolatedConfiguration, interpolateHelper, isDelimiterParsingDisabled, isScalarValue, isThrowExceptionOnMissing, resolveContainerStore, setDefaultListDelimiter, setDelimiter, setDelimiterParsingDisabled, setListDelimiter, setLogger, setProperty, setThrowExceptionOnMissing, subset`

Methods inherited from class org.apache.commons.configuration.event.EventSource
`addConfigurationListener, addErrorListener, clearConfigurationListeners, clearErrorListeners, clone, createErrorEvent, createEvent, fireError, fireEvent, getConfigurationListeners, getErrorListeners, isDetailEvents, removeConfigurationListener, removeErrorListener, setDetailEvents`

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### DatabaseConfiguration

    public DatabaseConfiguration(DataSource datasource,
                                 String table,
                                 String nameColumn,
                                 String keyColumn,
                                 String valueColumn,
                                 String name)

  Build a configuration from a table containing multiple configurations. No commits are performed by the new configuration instance.

  Parameters:
    `datasource` - the datasource to connect to the database
    `table` - the name of the table containing the configurations
    `nameColumn` - the column containing the name of the configuration
    `keyColumn` - the column containing the keys of the configuration
    `valueColumn` - the column containing the values of the configuration
    `name` - the name of the configuration

### DatabaseConfiguration

    public DatabaseConfiguration(DataSource datasource,
                                 String table,
                                 String nameColumn,
                                 String keyColumn,
                                 String valueColumn,
                                 String name,
                                 boolean commits)

  Creates a new instance of `DatabaseConfiguration` that operates on a database table containing multiple configurations.

  Parameters:
    `datasource` - the `DataSource` to connect to the database
    `table` - the name of the table containing the configurations
    `nameColumn` - the column containing the name of the configuration
    `keyColumn` - the column containing the keys of the configuration
    `valueColumn` - the column containing the values of the configuration
    `name` - the name of the configuration
    `commits` - a flag whether the configuration should perform a commit after a database update

### DatabaseConfiguration

    public DatabaseConfiguration(DataSource datasource,
                                 String table,
                                 String keyColumn,
                                 String valueColumn)

  Build a configuration from a table.

  Parameters:
    `datasource` - the datasource to connect to the database
    `table` - the name of the table containing the configurations
    `keyColumn` - the column containing the keys of the configuration
    `valueColumn` - the column containing the values of the configuration

### DatabaseConfiguration

    public DatabaseConfiguration(DataSource datasource,
                                 String table,
                                 String keyColumn,
                                 String valueColumn,
                                 boolean commits)

  Creates a new instance of `DatabaseConfiguration` that operates on a database table containing a single configuration only.

  Parameters:
    `datasource` - the `DataSource` to connect to the database
    `table` - the name of the table containing the configurations
    `keyColumn` - the column containing the keys of the configuration
    `valueColumn` - the column containing the values of the configuration
    `commits` - a flag whether the configuration should perform a commit after a database update

Method Detail

### isDoCommits

    public boolean isDoCommits()

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

  Returns:
    a flag whether commits are performed

### getProperty

    public Object getProperty(String key)

  Returns the value of the specified property. If this causes a database error, an error event will be generated of type `EVENT_READ_PROPERTY` with the causing exception. The event's `propertyName` is set to the passed in property key, the `propertyValue` is undefined.

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

### addProperty

    public void addProperty(String key,
                            Object value)

  Adds a property to this configuration. This implementation will temporarily disable list delimiter parsing, so that even if the value contains the list delimiter, only a single record will be written into the managed table. The implementation of `getProperty()` will take care about delimiters. So list delimiters are fully supported by `DatabaseConfiguration`, but internally treated a bit differently.

  Specified by:
    `addProperty` in interface `Configuration`
  Overrides:
    `addProperty` in class `AbstractConfiguration`
  Parameters:
    `key` - the key of the new property
    `value` - the value to be added

### isEmpty

    public boolean isEmpty()

  Checks if this configuration is empty. If this causes a database error, an error event will be generated of type `EVENT_READ_PROPERTY` with the causing exception. Both the event's `propertyName` and `propertyValue` will be undefined.

  Returns:
    a flag whether this configuration is empty.

### containsKey

    public boolean containsKey(String key)

  Checks whether this configuration contains the specified key. If this causes a database error, an error event will be generated of type `EVENT_READ_PROPERTY` with the causing exception. The event's `propertyName` will be set to the passed in key, the `propertyValue` will be undefined.

  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 `EVENT_CLEAR_PROPERTY` with the causing exception. The event's `propertyName` will be set to the passed in key, the `propertyValue` will be undefined.

  Overrides:
    `clearPropertyDirect` in class `AbstractConfiguration`
  Parameters:
    `key` - the key of the property to be removed

### clear

    public void clear()

  Removes all entries from this configuration. If this causes a database error, an error event will be generated of type `EVENT_CLEAR` with the causing exception. Both the event's `propertyName` and the `propertyValue` will be undefined.

  Specified by:
    `clear` in interface `Configuration`
  Overrides:
    `clear` in class `AbstractConfiguration`

### getKeys

    public Iterator<String> getKeys()

  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 `EVENT_READ_PROPERTY` with the causing exception. Both the event's `propertyName` and the `propertyValue` will be undefined.

  Returns:
    an iterator with the contained keys (an empty iterator in case of an error)

### getDatasource

    public DataSource getDatasource()

  Returns the used `DataSource` object.

  Returns:
    the data source
  Since:
    1.4

### getConnection

    @Deprecated
    protected Connection getConnection()
                                throws SQLException

  Deprecated. Use a custom data source to change the connection used by the class. To be removed in Commons Configuration 2.0

  Returns a `Connection` object. This method is called when ever the database is to be accessed. This implementation returns a connection from the current `DataSource`.

  Returns:
    the `Connection` object to be used
  Throws:
    `SQLException` - if an error occurs
  Since:
    1.4

Copyright © 2001-2012 The Apache Software Foundation. All Rights Reserved.