## org.apache.commons.configuration
Class DefaultConfigurationBuilder

    java.lang.Object
      org.apache.commons.configuration.event.EventSource
          org.apache.commons.configuration.AbstractConfiguration
              org.apache.commons.configuration.HierarchicalConfiguration
                  org.apache.commons.configuration.AbstractHierarchicalFileConfiguration
                      org.apache.commons.configuration.XMLConfiguration
                          org.apache.commons.configuration.DefaultConfigurationBuilder

All Implemented Interfaces:
  Serializable, Cloneable, Configuration, ConfigurationBuilder, ConfigurationListener, FileConfiguration

    public class DefaultConfigurationBuilder

extends XMLConfiguration
implements ConfigurationBuilder

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 ``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.

Since:
  1.3
Version:
  $Id: DefaultConfigurationBuilder.java 384601 2006-03-09 20:22:58Z oheger $
Author:
  Commons Configuration team
See Also:
  Serialized Form

Nested Class Summary
`(package private) static class` `DefaultConfigurationBuilder.ConfigurationBeanFactory` A specialized `BeanFactory` implementation that handles configuration declarations.
`(package private) static class` `DefaultConfigurationBuilder.ConfigurationBuilderProvider` A specialized configuration provider class that allows to include other configuration definition files.
`protected static class` `DefaultConfigurationBuilder.ConfigurationDeclaration` A specialized `BeanDeclaration` implementation that represents the declaration of a configuration source.
`static class` `DefaultConfigurationBuilder.ConfigurationProvider` A base class for creating and initializing configuration sources.
`static class` `DefaultConfigurationBuilder.FileConfigurationProvider` A specialized provider implementation that deals with file based configurations.
`(package private) static class` `DefaultConfigurationBuilder.FileExtensionConfigurationProvider` A specialized configuration provider for file based configurations that can handle configuration sources whose concrete type depends on the extension of the file to be loaded.

Nested classes/interfaces inherited from class org.apache.commons.configuration.XMLConfiguration
`XMLConfiguration.XMLBuilderVisitor, XMLConfiguration.XMLNode`

Nested classes/interfaces inherited from class org.apache.commons.configuration.AbstractHierarchicalFileConfiguration
`AbstractHierarchicalFileConfiguration.FileConfigurationDelegate`

Nested classes/interfaces inherited from class org.apache.commons.configuration.HierarchicalConfiguration
`HierarchicalConfiguration.BuilderVisitor, HierarchicalConfiguration.CloneVisitor, HierarchicalConfiguration.DefinedKeysVisitor, HierarchicalConfiguration.DefinedVisitor, HierarchicalConfiguration.Node, HierarchicalConfiguration.NodeVisitor`

Field Summary
`static String` `ADDITIONAL_NAME` Constant for the name of the additional configuration.
`(package private) static String` `ATTR_AT` Constant for the at attribute without the reserved prefix.
`(package private) static String` `ATTR_AT_RES` Constant for the reserved at attribute.
`(package private) static String` `ATTR_ATNAME` Constant for the name of the at attribute.
`(package private) static String` `ATTR_FILENAME` Constant for the file name attribute.
`(package private) static String` `ATTR_NAME` Constant for the reserved name attribute.
`(package private) static String` `ATTR_OPTIONAL` Constant for the optional attribute without the reserved prefix.
`(package private) static String` `ATTR_OPTIONAL_RES` Constant for the reserved optional attribute.
`(package private) static String` `ATTR_OPTIONALNAME` Constant for the name of the optional attribute.
`(package private) static String` `CONFIG_BEAN_FACTORY_NAME` Constant for the name of the configuration bean factory.
`(package private) static XPathExpressionEngine` `EXPRESSION_ENGINE` Constant for the expression engine used by this builder.
`(package private) static String` `EXT_XML` Constant for the XML file extension.
`(package private) static String` `KEY_ADDITIONAL_LIST` Constant for the key that points to the list nodes definition of the additional combiner.
`(package private) static String` `KEY_COMBINER` Constant for the key of the combiner in the result declaration.
`(package private) static String` `KEY_OVERRIDE_LIST` Constant for the key that points to the list nodes definition of the override combiner.
`(package private) static String` `KEY_OVERRIDE1` Constant for an expression that selects override configurations.
`(package private) static String` `KEY_OVERRIDE2` Constant for an expression that selects override configurations in the override section.
`(package private) static String` `KEY_RESULT` Constant for the key of the result declaration.
`(package private) static String` `KEY_UNION` Constant for an expression that selects the union configurations.
`(package private) static String` `SEC_HEADER` Constant for the name of the header section.

Fields inherited from class org.apache.commons.configuration.HierarchicalConfiguration
`EVENT_ADD_NODES, EVENT_CLEAR_TREE`

Fields inherited from class org.apache.commons.configuration.AbstractConfiguration
`END_TOKEN, EVENT_ADD_PROPERTY, EVENT_CLEAR, EVENT_CLEAR_PROPERTY, EVENT_SET_PROPERTY, START_TOKEN`

Constructor Summary
`DefaultConfigurationBuilder()` Creates a new instance of `DefaultConfigurationBuilder`.
`DefaultConfigurationBuilder(File file)` Creates a new instance of `DefaultConfigurationBuilder` and sets the specified configuration definition file.
`DefaultConfigurationBuilder(String fileName)` Creates a new instance of `DefaultConfigurationBuilder` and sets the specified configuration definition file.
`DefaultConfigurationBuilder(URL url)` Creates a new instance of `DefaultConfigurationBuilder` and sets the specified configuration definition file.

Method Summary
`void` `addConfigurationProvider(String tagName, DefaultConfigurationBuilder.ConfigurationProvider provider)` Adds a configuration provider for the specified tag.
`protected CombinedConfiguration` `createResultConfiguration()` Creates the resulting combined configuration.
`Configuration` `getConfiguration()` Returns the configuration provided by this builder.
`CombinedConfiguration` `getConfiguration(boolean load)` Returns the configuration provided by this builder.
`String` `getConfigurationBasePath()` Returns the base path for the configuration sources to load.
`protected void` `initCombinedConfiguration(CombinedConfiguration config, List containedConfigs, String keyListNodes)` Initializes a combined configuration for the configurations of a specific section.
`protected Object` `interpolate(Object value)` Performs interpolation.
`DefaultConfigurationBuilder.ConfigurationProvider` `providerForTag(String tagName)` Returns the configuration provider for the given tag.
`protected void` `registerDefaultProviders()` Registers the default configuration providers supported by this class.
`DefaultConfigurationBuilder.ConfigurationProvider` `removeConfigurationProvider(String tagName)` Removes the configuration provider for the specified tag name.
`void` `setConfigurationBasePath(String configurationBasePath)` Sets the base path for the configuration sources to load.

Methods inherited from class org.apache.commons.configuration.XMLConfiguration
`clear, clone, createDelegate, createDocument, createDocumentBuilder, createNode, createTransformer, getDocument, getDocumentBuilder, getPublicID, getRootElementName, getSystemID, initProperties, isValidating, load, load, save, setDocumentBuilder, setPublicID, setRootElementName, setSystemID, setValidating`

Methods inherited from class org.apache.commons.configuration.AbstractHierarchicalFileConfiguration

`addPropertyDirect, clearProperty, clearTree, configurationChanged, containsKey, getBasePath, getDelegate, getEncoding, getFile, getFileName, getKeys, getProperty, getReloadingStrategy, getURL, isAutoSave, isEmpty, load, load, load, load, load, reload, save, save, save, save, save, save, setAutoSave, setBasePath, setDelegate, setEncoding, setFile, setFileName, setProperty, setReloadingStrategy, setURL`

Methods inherited from class org.apache.commons.configuration.HierarchicalConfiguration
`addNodes, clearNode, clearNode, configurationAt, configurationsAt, createAddPath, createSubnodeConfiguration, fetchAddNode, fetchNodeList, findLastPathNode, findPropertyNodes, getDefaultExpressionEngine, getExpressionEngine, getKeys, getMaxIndex, getRoot, getRootNode, nodeDefined, nodeDefined, removeNode, removeNode, setDefaultExpressionEngine, setExpressionEngine, setRoot, setRootNode, subset`

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

`addProperty, clearPropertyDirect, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDefaultListDelimiter, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getList, getList, getListDelimiter, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, interpolate, interpolateHelper, isDelimiterParsingDisabled, isThrowExceptionOnMissing, resolveContainerStore, setDefaultListDelimiter, setDelimiter, setDelimiterParsingDisabled, setListDelimiter, setThrowExceptionOnMissing`

Methods inherited from class org.apache.commons.configuration.event.EventSource
`addConfigurationListener, clearConfigurationListeners, createEvent, fireEvent, getConfigurationListeners, isDetailEvents, removeConfigurationListener, 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.configuration.Configuration
`addProperty, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getKeys, getList, getList, getLong, getLong, getLong, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, subset`

Field Detail

### ADDITIONAL_NAME

    public static final String ADDITIONAL_NAME

  Constant for the name of the additional configuration. If the configuration definition file contains an `additional` section, a special union configuration is created and added under this name to the resulting combined configuration.

### EXPRESSION_ENGINE

    static final XPathExpressionEngine EXPRESSION_ENGINE

  Constant for the expression engine used by this builder.

### CONFIG_BEAN_FACTORY_NAME

    static final String CONFIG_BEAN_FACTORY_NAME

  Constant for the name of the configuration bean factory.

### ATTR_NAME

    static final String ATTR_NAME

  Constant for the reserved name attribute.

  See Also:
    Constant Field Values

### ATTR_ATNAME

    static final String ATTR_ATNAME

  Constant for the name of the at attribute.

  See Also:
    Constant Field Values

### ATTR_AT_RES

    static final String ATTR_AT_RES

  Constant for the reserved at attribute.

  See Also:
    Constant Field Values

### ATTR_AT

    static final String ATTR_AT

  Constant for the at attribute without the reserved prefix.

  See Also:
    Constant Field Values

### ATTR_OPTIONALNAME

    static final String ATTR_OPTIONALNAME

  Constant for the name of the optional attribute.

  See Also:
    Constant Field Values

### ATTR_OPTIONAL_RES

    static final String ATTR_OPTIONAL_RES

  Constant for the reserved optional attribute.

  See Also:
    Constant Field Values

### ATTR_OPTIONAL

    static final String ATTR_OPTIONAL

  Constant for the optional attribute without the reserved prefix.

  See Also:
    Constant Field Values

### ATTR_FILENAME

    static final String ATTR_FILENAME

  Constant for the file name attribute.

  See Also:
    Constant Field Values

### SEC_HEADER

    static final String SEC_HEADER

  Constant for the name of the header section.

  See Also:
    Constant Field Values

### KEY_UNION

    static final String KEY_UNION

  Constant for an expression that selects the union configurations.

  See Also:
    Constant Field Values

### KEY_OVERRIDE1

    static final String KEY_OVERRIDE1

  Constant for an expression that selects override configurations.

  See Also:
    Constant Field Values

### KEY_OVERRIDE2

    static final String KEY_OVERRIDE2

  Constant for an expression that selects override configurations in the override section.

  See Also:
    Constant Field Values

### KEY_OVERRIDE_LIST

    static final String KEY_OVERRIDE_LIST

  Constant for the key that points to the list nodes definition of the override combiner.

  See Also:
    Constant Field Values

### KEY_ADDITIONAL_LIST

    static final String KEY_ADDITIONAL_LIST

  Constant for the key that points to the list nodes definition of the additional combiner.

  See Also:
    Constant Field Values

### KEY_RESULT

    static final String KEY_RESULT

  Constant for the key of the result declaration. This key can point to a bean declaration, which defines properties of the resulting combined configuration.

  See Also:
    Constant Field Values

### KEY_COMBINER

    static final String KEY_COMBINER

  Constant for the key of the combiner in the result declaration.

  See Also:
    Constant Field Values

### EXT_XML

    static final String EXT_XML

  Constant for the XML file extension.

  See Also:
    Constant Field Values

Constructor Detail

### DefaultConfigurationBuilder

    public DefaultConfigurationBuilder()

  Creates a new instance of `DefaultConfigurationBuilder`. A configuration definition file is not yet loaded. Use the diverse setter methods provided by file based configurations to specify the configuration definition file.

### DefaultConfigurationBuilder

    public DefaultConfigurationBuilder(File file)

  Creates a new instance of `DefaultConfigurationBuilder` and sets the specified configuration definition file.

  Parameters:
    `file` - the configuration definition file

### DefaultConfigurationBuilder

    public DefaultConfigurationBuilder(String fileName)
                                throws ConfigurationException

  Creates a new instance of `DefaultConfigurationBuilder` and sets the specified configuration definition file.

  Parameters:
    `fileName` - the name of the configuration definition file
  Throws:
    `ConfigurationException` - if an error occurs when the file is loaded

### DefaultConfigurationBuilder

    public DefaultConfigurationBuilder(URL url)
                                throws ConfigurationException

  Creates a new instance of `DefaultConfigurationBuilder` and sets the specified configuration definition file.

  Parameters:
    `url` - the URL to the configuration definition file
  Throws:
    `ConfigurationException` - if an error occurs when the file is loaded

Method Detail

### getConfigurationBasePath

    public String getConfigurationBasePath()

  Returns the base path for the configuration sources to load. This path is used to resolve relative paths in the configuration definition file.

  Returns:
    the base path for configuration sources

### setConfigurationBasePath

    public void setConfigurationBasePath(String configurationBasePath)

  Sets the base path for the configuration sources to load. Normally a base path need not to be set because it is determined by the location of the configuration definition file to load. All relative pathes in this file are resolved relative to this file. Setting a base path makes sense if such relative pathes should be otherwise resolved, e.g. if the configuration file is loaded from the class path and all sub configurations it refers to are stored in a special config directory.

  Parameters:
    `configurationBasePath` - the new base path to set

### addConfigurationProvider

    public void addConfigurationProvider(String tagName,
                                         DefaultConfigurationBuilder.ConfigurationProvider provider)

  Adds a configuration provider for the specified tag. Whenever this tag is encountered in the configuration definition file this provider will be called to create the configuration object.

  Parameters:
    `tagName` - the name of the tag in the configuration definition file
    `provider` - the provider for this tag

### removeConfigurationProvider

    public DefaultConfigurationBuilder.ConfigurationProvider removeConfigurationProvider(String tagName)

  Removes the configuration provider for the specified tag name.

  Parameters:
    `tagName` - the tag name
  Returns:
    the removed configuration provider or null if none was registered for that tag

### providerForTag

    public DefaultConfigurationBuilder.ConfigurationProvider providerForTag(String tagName)

  Returns the configuration provider for the given tag.

  Parameters:
    `tagName` - the name of the tag
  Returns:
    the provider that was registered for this tag or null if there is none

### getConfiguration

    public Configuration getConfiguration()
                                   throws ConfigurationException

  Returns the configuration provided by this builder. Loads and parses the configuration definition file and creates instances for the declared configurations.

  Specified by:
    `getConfiguration` in interface `ConfigurationBuilder`
  Returns:
    the configuration
  Throws:
    `ConfigurationException` - if an error occurs

### getConfiguration

    public CombinedConfiguration getConfiguration(boolean load)
                                           throws ConfigurationException

  Returns the configuration provided by this builder. If the boolean parameter is true, the configuration definition file will be loaded. It will then be parsed, and instances for the declared configurations will be created.

  Parameters:
    `load` - a flag whether the configuration definition file should be loaded; a value of false would make sense if the file has already been created or its content was manipulated using some of the property accessor methods
  Returns:
    the configuration
  Throws:
    `ConfigurationException` - if an error occurs

### createResultConfiguration

    protected CombinedConfiguration createResultConfiguration()
                                                       throws ConfigurationException

  Creates the resulting combined configuration. This method is called by `getConfiguration()`. It checks whether the `header` section of the configuration definition file contains a `result` element. If this is the case, it will be used to initialize the properties of the newly created configuration object.

  Returns:
    the resulting configuration object
  Throws:
    `ConfigurationException` - if an error occurs

### initCombinedConfiguration

    protected void initCombinedConfiguration(CombinedConfiguration config,
                                             List containedConfigs,
                                             String keyListNodes)
                                      throws ConfigurationException

  Initializes a combined configuration for the configurations of a specific section. This method is called for the override and for the additional section (if it exists).

  Parameters:
    `config` - the configuration to be initialized
    `containedConfigs` - the list with the declaratinos of the contained configurations
    `keyListNodes` - a list with the declaration of list nodes
  Throws:
    `ConfigurationException` - if an error occurs

### registerDefaultProviders

    protected void registerDefaultProviders()

  Registers the default configuration providers supported by this class. This method will be called during initialization. It registers configuration providers for the tags that are supported by default.

### interpolate

    protected Object interpolate(Object value)

  Performs interpolation. This method will not only take this configuration instance into account (which is the one that loaded the configuration definition file), but also the so far constructed combined configuration. So variables can be used that point to properties that are defined in configuration sources loaded by this builder.

  Overrides:
    `interpolate` in class `AbstractConfiguration`
  Parameters:
    `value` - the value to be interpolated
  Returns:
    the interpolated value

Copyright © 2001-2006 The Apache Software Foundation. All Rights Reserved.