Using Configuration

Commons Configuration allows you to access configuration properties from
a variety of different sources. No matter if they are stored in a properties file,
a XML document, or a JNDI tree, they can all be accessed in the same way
through the generic Configuration
interface.

Another strength of Commons Configuration is its ability to mix configurations
from heterogeneous sources and treat them like a single logic configuration.
This section will introduce you to the different configurations
available and will show you how to combine them.

Configuration Sources

Currently there are quite a number of different sources of Configuration objects. But,
by just using a Configuration object versus a specific type like XMLConfiguration or
JNDIConfiguration, you are sheltered from the mechanics of actually retrieving the
configuration values. These various sources include:

INIConfiguration
Loads the values from a .ini file as used by Windows.

PropertyListConfiguration
Loads values from an OpenStep .plist file. XMLPropertyListConfiguration is also
available to read the XML variant used by Mac OS X.

JNDIConfiguration
Using a key in the JNDI tree, can retrieve values as configuration properties.

BaseConfiguration
An in-memory method of populating a Configuration object.

HierarchicalConfiguration
An in-memory Configuration object that is able to deal with complex
structured data.

SystemConfiguration
A configuration using the system properties

ConfigurationConverter
Takes a java.util.Properties or an org.apache.commons.collections.ExtendedProperties
and converts it to a Configuration object.

The Configuration interface

All the classes in this package that represent different kinds of configuration
sources share a single interface:
Configuration.
This interface allows you to access and manipulate configuration properties
in a generic way.

The methods defined in the Configuration interface can be
divided into methods which query data from the configuration and
methods which alter the configuration object. In fact, the
Configuration interface extends a base interface called
ImmutableConfiguration. ImmutableConfiguration
defines all methods which read data from a configuration object without
changing its state. Configuration adds methods for
manipulating the configuration.

A major part of the methods defined in the ImmutableConfiguration
interface deals with retrieving properties of different data types. All
these methods take a key as an argument that points to the desired
property. This is a string value whose exact meaning depends on the
concrete Configuration implementation used. They try to
find the property specified by the passed in key and convert it to their
target type; this converted value will be returned. There are also
overloaded variants of all methods that allow to specify a default value,
which will be returned if the property cannot be found. The following
data types are supported out of the box:

BigDecimal

BigInteger

boolean

byte

double

float

int

long

short

String

The names of these methods start with get followed by their
data type. The getString() method for instance will return
String values, getInt() will operate on integers.

Properties can have multiple values, so it is also possible to query a
list or an array containing all of the available values. This is done
using the getList() or getArray() methods.

In addition, there are a couple of generic get methods which try to
convert the requested property value to a specified data type. Such
conversions are also supported for the elements of collections or arrays.
More details about conversions can be found in the section
Data type conversions.

The subset() method is useful if configuration settings
are organized in a specific structure and a module of an
application is only interested in a part of this structure.
subset() is passed a String with a key prefix and returns
a Configuration object that contains only the keys starting
with this prefix.

For manipulating properties or their values the following methods can
be used:

addProperty()

Adds a new property to the configuration. If this property already
exists, another value is added to it (so it becomes a multi-valued
property).

clearProperty()

Removes the specified property from the configuration.

setProperty()

Overwrites the value of the specified property. This is the same
as removing the property and then calling addProperty()
with the new property value.

clear()

Wipes out the whole configuration

Immutable Configurations

Most of the classes provided by the Commons Configuration
library implement the Configuration interface, i.e. they
allow client code to change their internal state. For some use cases,
this may not be desired. For instance, an application may want to
protect a central configuration object against uncontrolled modifications
done by sub modules.

There is an easy way to convert a normal Configuration
object into an ImmutableConfiguration: just pass the
configuration in question to the unmodifiableConfiguration()
method of the
ConfigurationUtils utility class. This results in an
immutable configuration containing the same data as the original
configuration.

Threading issues

When accessing configurations from multiple threads - be it in a
read-only or in a manipulating manner - the question arises whether
Configuration implementations are thread-safe. When
using immutable configurations as described in the previous section
you are typically on the safe side because immutable objects can
safely be shared between multiple threads. However, the
ImmutableConfiguration objects created by
ConfigurationUtils are just wrappers around a mutable
Configuration object. So if code holds a reference to the
underlying Configuration, it can still be changed.

Apache Commons, Apache Commons Configuration, Apache, the Apache feather logo, and the Apache Commons project logos are trademarks of The Apache Software Foundation.
All other marks mentioned may be trademarks or registered trademarks of their respective owners.