Apache Commons logo Commons Configuration

Basic features and AbstractConfiguration

The Configuration interface defines a whole bunch of methods. Implementing these methods all from scratch can be quite hard. Because of that the AbstractConfiguration class exists. This class serves as a common base class for most of the Configuration implementations in Commons Configuration and provides a great deal of the functionality required by the interface. So for creating a custom Configuration implementation this class will be a good starting point.

In addition to base implementations for lots of the methods declared in the Configuration interface the AbstractConfiguration class provides some other handy and convenient features. Because this class is at the very root of the class hierarchy in Commons Configuration these features are available in most of the specific implementations of the Configuration interface provided by this library. We will cover some of these basic features in this section.

Handling of missing properties

What is a configuration object supposed to do if you pass in a key to one of its get methods that does not map to an existing property? Well, the default behavior as implemented in AbstractConfiguration is to return null if the return value is an object type. For primitive types as return values returning null (or any other special value) is not possible, so in this case a NoSuchElementException is thrown:

// This will return null if no property with key "NonExistingProperty" exists
String strValue = config.getString("NonExistingProperty");

// This will throw a NoSuchElementException exception if no property with
// key "NonExistingProperty" exists
long longValue = config.getLong("NonExistingProperty");

For object types like String, BigDecimal, or BigInteger this default behavior can be changed: If the setThrowExceptionOnMissing() method is called with an argument of true, these methods will behave like their primitive counter parts and also throw an exception if the passed in property key cannot be resolved.

Note: Unfortunately support for the throwExceptionOnMissing property is not always consistent: The methods getList() and getStringArray() do not evaluate this flag, but return an empty list or array if the requested property cannot be found. Maybe this behavior will be changed in a future major release.

List handling

With getList() and getStringArray() the Configuration interface defines methods for dealing with properties that have multiple values. When a configuration source (e.g. a properties file, an XML document, or a JNDI context) is processed the corresponding Configuration implementation detects such properties with multiple values and ensures that the data is correctly stored.

When modifying properties the addProperty() and setProperty() methods of AbstractConfiguration also implement special list handling. The property value that is passed to these methods can be a list or an array resulting in a property with multiple values.

For some use cases it makes sense to treat string values in a special way. For instance, some configuration formats do not support lists directly. As an example, properties files can be used: they just consist of key-value pairs, and there is no default syntax to assign multiple values to a key. AbstractConfiguration supports a mechanism to split strings at specific characters, so that effectively multiple values are generated from a single string. To achieve this, an AbstractConfiguration instance collaborates with an object implementing the ListDelimiterHandler interface. This interface defines methods for dealing with objects that may contain multiple values. Examples of such complex objects are arrays, lists, and strings containing a specific list delimiter. Depending on a concrete implementation of the ListDelimiterHandler interface, these objects are treated in a special way.

Per default, AbstractConfiguration uses an instance of the DisabledListDelimiterHandler class as list handler. This class can deal with lists and arrays, but it does not recognize any list delimiter characters in strings. (Hence the name, as splitting of strings at list delimiters is disabled.)

An alternative implementation of ListDelimiterHandler is DefaultListDelimiterHandler. This class actually supports string splitting; the list delimiter character has to be passed to the constructor. Whenever a property is added to the configuration (or the configuration is loaded from its source), it is checked whether the property value is a string and - if so - if it contains the list delimiter character. In this case, the string is split, and its single parts are added one by one. By using the setListDelimiterHandler() method you can set a specific list handler implementation. Here are some examples:

// Enable list delimiter handling using a slash as delimiter character
config.setListDelimiterHandler(new DefaultListDelimiterHandler('/'));
// Now add some properties
config.addProperty("greeting", "Hello, how are you?");
  new String[] { "#FF0000", "#00FF00", "#0000FF" });
config.addProperty("colors.graph", "#808080/#00FFCC/#6422FF");

// Access data
String salut = config.getString("greeting");
List<Object> colPie = config.getList("colors.pie");
String[] colGraph = config.getStringArray("colors.graph");

String firstPieColor = config.getString("colors.pie");

In this example splitting of strings is enabled using the slash character as delimiter. Because this character is not contained in the greeting property it won't be split, but remains a single string. In contrast, the string passed as value for the colors.graph property contains the delimiter character and thus will result in a property with three values. Note that the version of the getList() method used here returns lists of type Object. This is because the concrete class of the values of a property is not known. For instance, if you call addProperty("answer", 42), an Integer object will be stored in the configuration. However, there are overloaded versions of getList() supporting a data type conversion to a specific target class (see below).

Of interest is also the last line of the example fragment. Here the getString() method is called for a property that has multiple values. This call will return the first value of the list.

Variable Interpolation

If you are familiar with Ant or Maven, you have most certainly already encountered the variables (like ${token}) that are automatically expanded when the configuration file is loaded. Commons Configuration supports this feature as well, here is an example (we use a properties file in this example, but other configuration sources work the same way; you can learn more about properties files in the chapter Properties files):

application.name = Killer App
application.version = 1.6.2

application.title = ${application.name} ${application.version}

If you now retrieve the value for the application.title property, the result will be Killer App 1.6.2. So per default variables are interpreted as the keys of other properties. This is only a special case, the general syntax of a variable name is ${prefix:name}. The prefix tells Commons Configuration that the variable is to be evaluated in a certain context. We have already seen that the context is the current configuration instance if the prefix is missing. The following other prefix names are supported by default:

Prefix Description
sys This prefix marks a variable to be a system property. Commons Configuration will search for a system property with the given name and replace the variable by its value. This is a very easy means for accessing the values of system properties in every configuration implementation.
const The const prefix indicates that a variable is to be interpreted as a constant member field of a class (i.e. a field with the static final modifiers). The name of the variable must be of the form <full qualified class name>.<field name>. The specified class will be loaded and the value of this field will be obtained.
env Variables can also reference OS-specific environment properties. This is indicated by the env prefix.
Here are some examples (again using properties syntax):
user.file = ${sys:user.home}/settings.xml

action.key = ${const:java.awt.event.KeyEvent.VK_CANCEL}

java.home = ${env:JAVA_HOME}

If a variable cannot be resolved, e.g. because the name is invalid or an unknown prefix is used, it won't be replaced, but is returned as is including the dollar sign and the curly braces.

Customizing interpolation

This sub section goes a bit behind the scenes of interpolation and explains some approaches how you can add your own interpolation facilities. Under the hood interpolation is implemented using the StrSubstitutor class of the text package of Commons Lang. This class uses objects derived from the StrLookup class for resolving variables. StrLookup defines a simple lookup() method that must be implemented by custom implementations; it expects the name of a variable as argument and returns the corresponding value (further details can be found in the documentation of Commons Lang). The standard prefixes for variables we have covered so far are indeed realized by special classes derived from StrLookup.

It is now possible to create your own implementation of StrLookup and make it available for all configuration objects under a custom prefix. We will show how this can be achieved. The first step is to create a new class derived from StrLookup, which must implement the lookup() method. As an example we implement a rather dull lookup object that simply returns a kind of "echo" for the variable passed in:

import org.apache.commons.lang.text.StrLookup;

public class EchoLookup extends StrLookup
    public String lookup(String varName)
        return "Value of variable " + varName;

Now we want this class to be called for variables with the prefix echo. For this purpose the EchoLookup class has to be registered at the ConfigurationInterpolator class with the desired prefix. ConfigurationInterpolator implements a thin wrapper over the StrLookup API defined by Commons Lang. It has a static registerGlobalLookup() method, which we have to call as follows:

// Place this code somewhere in an initialization section of your application
ConfigurationInterpolator.registerGlobalLookup("echo", new EchoLookup());

Each AbstractConfiguration object that is created after this line is executed will contain the new lookup class and can thus resolve variables of the form ${echo:my_variable}.

Each instance of AbstractConfiguration is associated with a ConfigurationInterpolator object. This object is created by the createInterpolator() method on first access of one of the interpolation features. By overriding this method even deeper intervention in the interpolation mechanism is possible. For instance a custom implementation can add further lookup objects to the interpolator, which are then only used by this configuration instance.

Using Expressions

In addition to the simple lookup mechanisms previously described, Commond Configuration provides ExprLookup which uses Apache Commons Jexl to allow expressions to be resolved wherever a StrLookup is allowed. This example shows an alternate way of obtaining a system property if the ExprLookup is configured.

user.file = ${expr:System.getProperty("user.home"}/settings.xml

ExprLookup is not enabled by default, it must be manually added or configured via DefaultConfigurationBuilder. Builds that use Maven 2 and reference Commons Configuration will not include a dependency on Jexl, so if this feature is used the dependency on Jexl must be manually added to the project.

When using DefaultConfigurationBuilder adding ExprLookup is straightforward.

      <lookup config-prefix="expr"
          <variable name="System" value="Class:java.lang.System"/>
          <variable name"net" value="Class:java.net.InetAddress"/>
          <variable name="String" value="Class:org.apache.commons.lang.StringUtils"/>
    <xml fileName="${expr:System.getProperty('basePath') +
         String.lowercase(net.localHost.hostName) + '/testMultiConfiguration_default.xml'}"
         config-name="defaultConfig" delimiterParsingDisabled="true">

The example above shows how to invoke static methods during expression evaluation. The next example shows mixing expression evaluation with a subordinate lookup to obtain the "basePath" system property. Note the difference in how the system property was obtained in the previous example.

      <lookup config-prefix="expr"
          <variable name"net" value="Class:java.net.InetAddress"/>
          <variable name="String" value="Class:org.apache.commons.lang.StringUtils"/>
    <xml fileName="${expr:$[sys:basePath] +
         String.lowercase(net.localHost.hostName) + '/testMultiConfiguration_default.xml'}"
         config-name="defaultConfig" delimiterParsingDisabled="true">

Data type conversions

As was already mentioned when discussing the Configuration interface, there are various get() methods returning property values in different target data types. If necessary, a data type conversion is performed. Take a look at the following example:

config.addProperty("answer", "42");
int theAnswer = config.getInt("answer");

Here a string value is assigned to the key answer. Then the getInt() method is called to query this key as an integer value. getInt() triggers a type conversion automatically. If such a conversion is not possible, a runtime exception of type ConversionException is thrown.

The Configuration interface defines a bunch of methods returning property values in different data types. All of these methods work in the same way: they obtain the actual value of the property and attempt a data type conversion if necessary. In addition, there are generic methods for accessing properties in specific data types:

<T> get(Class<T> cls, String key);
Obtains the value of the specified property and tries to convert it to the specified target type. If the key cannot be resolved, result is null, or - if the throwExceptionOnMissing flag is set - an exception is thrown.
<T> get(Class<T> cls, String key, T defValue);
Obtains the value of the specified property and tries to convert it to the specified target type. If the key cannot be resolved, the specified default value is returned (which may be null).
In fact, all specialized get() methods are based on these generic methods.

Generic conversion methods are also available for obtaining arrays or collections. For instance, it is possible to obtain the value of a property as an array of int or a list of java.lang.Long objects. This can be achieved using the following methods:

Object getArray(Class<?> cls, String key);
Returns an array of the specified element class. This method can handle both object and primitive arrays. (Therefore, the return type is just Object because there is no common base class for all kinds of arrays.)
<T> List<T> getList(Class<T> cls, String key);
Returns a list of the specified element class.
<T> Collection<T> getCollection(Class<T> cls, String key, Collection<T> target);
This method is similar to getList(), but it allows specifying the target collection. This is useful if the result should be stored in a different collection type, e.g. a set to remove duplicates.

These methods obtain all values stored for the property with the passed in key. For each value a conversion to the desired target type is performed. Then the resulting values are stored in the target array or collection. There are also variants supporting default values.

It is worth to mention that data type conversion plays well together with variable interpolation: Before a data type conversion is attempted interpolation is handled first. Then the resulting object is converted if necessary.

Customizing data type conversions

Commons Configuration supports a number of conversions to standard types out of the box. In addition to the result types of the get() methods in the Configuration interface, some more types are supported. These are listed in the documentation of the DataConfiguration class. DataConfiguration is a decorator providing additional data type conversion methods for more target types; these additional methods are implemented on top of the generic conversion methods provided by AbstractConfiguration.

If your application deals with special objects, there may be the requirement to extend the conversion capabilities offered by the library. To support this use case, there is the ConversionHandler interface. Each instance of a configuration class derived from AbstractConfiguration is associated with such a ConversionHandler object. The interface defines methods for converting an object to a target class, and for converting values to arrays or collections of a given element type. The data type conversion methods implemented in AbstractConfiguration delegate to this handler object.

The ConversionHandler interface gives a developer full control over the whole data conversion process. By implementing the different conversion methods, it is possible to integrate existing conversion libraries (e.g. the converters offered by Commons BeanUtils) with Commons Configuration.

If the conversion facilities provided by Commons Configuration are not to be fully replaced, but only extended by some custom types, the class DefaultConversionHandler is a good starting point. As the name implies, an instance of this class is used per default for doing type conversions. DefaultConversionHandler has some protected methods which can be overridden by subclasses in order to extend data type conversions:

This is the main conversion method for single values. It is called when a single value is to be converted to a target type and also for the single elements of arrays or collections. If a conversion to another target class is to be supported, this is the method to override. A custom implementation typically checks whether the desired target class is one of the classes it supports. If this is the case, the passed in source object is converted, and the result is returned. Otherwise, the super method is called to handle standard conversions.
This boolean method determines whether a passed in object contains multiple values. When doing a conversion to a target class DefaultConversionHandler checks whether the source object is a complex object like an array or a collection. If this is the case, it first extracts the value to be converted from the source object before it calls convertValue().
extractConversionValue() is called if a complex object (i.e. an object containing multiple values) is to be converted to a single object (i.e. not an array or a collection). In this case, it is not directly obvious how the multiple values should be handled. This situation occurs for example if a client calls getInt() on a property which actually has multiple values. The default implementation of extractConversionValue() simply returns the first value available. If an application needs a different behavior, it can provide a custom implementation of this method.
This method contains the logic for converting a single value. It delegates to the other methods discussed here. It first checks whether the object to be converted is a complex one. If so, it extracts the value to be converted. Eventually, it delegates to convertValue() for performing the actual conversion. So in order to gain more control over the whole conversion process, this method is a good candidate for overriding.

After a custom ConversionHandler implementation has been created, it can be installed at a configuration instance by using the setConversionHandler() method:

CustomConversionHandler handler = new CustomConversionHandler(...);

Another feature of DefaultConversionHandler is that is allows defining the format for the conversion of Date and Calendar objects. This can be done by calling setDateFormat() with the corresponding date pattern. The expected string argument must be a pattern string compatible with the java.text.SimpleDateFormat class. If no date format was set, the default pattern yyyy-MM-dd HH:mm:ss is used.