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:

• EnvironmentConfiguration Reads the plattform specific environment variables.
• PropertiesConfiguration Loads configuration values from a properties file.
• XMLConfiguration Takes values from an XML document.
• 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

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.

Because concurrency is a complex topic this user's guide contains a dedicated section to this topic: Configurations and Concurrent Access.