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 and Description

DatabaseConfiguration()
Creates a new instance of DatabaseConfiguration.

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

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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()` Returns the name of this configuration instance.
`String`	`getConfigurationNameColumn()` Returns the name of the table column with the configuration name.
`DataSource`	`getDatasource()` Returns the used `DataSource` object.
`DataSource`	`getDataSource()` Returns the `DataSource` for obtaining database connections.
`String`	`getKeyColumn()` Returns 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)` Returns the value of the specified property.
`String`	`getTable()` Returns the name of the table containing configuration data.
`String`	`getValueColumn()` Returns 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()
```
    Returns 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()
```
    Returns 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()
```
    Returns 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()
```
    Returns 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()
```
    Returns 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()
```
    Returns 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)
```
    Returns 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()
```
    Returns 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

Class DatabaseConfiguration

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

Constructor Summary

Method Summary

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

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

Methods inherited from class java.lang.Object

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

Constructor Detail

DatabaseConfiguration

Method Detail

getDataSource

setDataSource

getTable

setTable

getConfigurationNameColumn

setConfigurationNameColumn

getKeyColumn

setKeyColumn

getValueColumn

setValueColumn

getConfigurationName

setConfigurationName

isAutoCommit

setAutoCommit

getPropertyInternal

addPropertyDirect

addPropertyInternal

isEmptyInternal

containsKeyInternal

clearPropertyDirect

clearInternal

getKeysInternal

getDatasource

close

extractPropertyValue