Java Doc for DefaultConfigurationBuilder.java in  » Library » Apache-commons-configuration-1.4-src » org » apache » commons » configuration » Java Source Code / Java DocumentationJava Source Code and Java Documentation

A factory class that creates a composite configuration from an XML based configuration definition file.

This class provides an easy and flexible means for loading multiple configuration sources and combining the results into a single configuration object. The sources to be loaded are defined in an XML document that can contain certain tags representing the different supported configuration classes. If such a tag is found, the corresponding Configuration class is instantiated and initialized using the classes of the beanutils package (namely org.apache.commons.configuration.beanutils.XMLBeanDeclaration XMLBeanDeclaration will be used to extract the configuration's initialization parameters, which allows for complex initialization szenarios).

It is also possible to add custom tags to the configuration definition file. For this purpose register your own ConfigurationProvider implementation for your tag using the addConfigurationProvider() method. This provider will then be called when the corresponding custom tag is detected. For the default configuration classes providers are already registered.

The configuration definition file has the following basic structure:

 <configuration>
 <header>
 <!-- Optional meta information about the composite configuration -->
 </header>
 <override>
 <!-- Declarations for override configurations -->
 </override>
 <additional>
 <!-- Declarations for union configurations -->
 </additional>
 </configuration>
 

The name of the root element (here configuration) is arbitrary. There are two sections (both of them are optional) for declaring override and additional configurations. Configurations in the former section are evaluated in the order of their declaration, and properties of configurations declared earlier hide those of configurations declared later. Configurations in the latter section are combined to a union configuration, i.e. all of their properties are added to a large hierarchical configuration. Configuration declarations that occur as direct children of the root element are treated as override declarations.

Each configuration declaration consists of a tag whose name is associated with a ConfigurationProvider. This can be one of the pre-defined tags like properties, or xml, or a custom tag, for which a configuration provider was registered. Attributes and sub elements with specific initialization parameters can be added. There are some reserved attributes with a special meaning that can be used in every configuration declaration:

Attribute	Meaning
config-name	Allows to specify a name for this configuration. This name can be used to obtain a reference to the configuration from the resulting combined configuration (see below).
config-at	With this attribute an optional prefix can be specified for the properties of the corresponding configuration.
config-optional	Declares a configuration as optional. This means that errors that occur when creating the configuration are silently ignored.

The optional header section can contain some meta data about the created configuration itself. For instance, it is possible to set further properties of the NodeCombiner objects used for constructing the resulting configuration.

The configuration object returned by this builder is an instance of the CombinedConfiguration class. The return value of the getConfiguration() method can be casted to this type, and the getConfiguration(boolean) method directly declares CombinedConfiguration as return type. This allows for convenient access to the configuration objects maintained by the combined configuration (e.g. for updates of single configuration objects). It has also the advantage that the properties stored in all declared configuration objects are collected and transformed into a single hierarchical structure, which can be accessed using different expression engines.

All declared override configurations are directly added to the resulting combined configuration. If they are given names (using the config-name attribute), they can directly be accessed using the getConfiguration(String) method of CombinedConfiguration. The additional configurations are alltogether added to another combined configuration, which uses a union combiner. Then this union configuration is added to the resulting combined configuration under the name defined by the ADDITIONAL_NAME constant.

Implementation note: This class is not thread-safe. Especially the getConfiguration() methods should be called by a single thread only.