Package org.apache.commons.configuration2.builder.combined

# Class CombinedConfigurationBuilder

java.lang.Object
org.apache.commons.configuration2.builder.BasicConfigurationBuilder<CombinedConfiguration>
org.apache.commons.configuration2.builder.combined.CombinedConfigurationBuilder

All Implemented Interfaces:
  `ConfigurationBuilder<CombinedConfiguration>`, `EventSource`

Direct Known Subclasses:
  `ReloadingCombinedConfigurationBuilder`

public class CombinedConfigurationBuilder extends BasicConfigurationBuilder<CombinedConfiguration>

A specialized `ConfigurationBuilder` implementation that creates a `CombinedConfiguration` from multiple configuration sources defined by 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, a corresponding `ConfigurationBuilder` 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 scenarios).

It is also possible to add custom tags to the configuration definition file. For this purpose an implementation of `CombinedConfigurationBuilderProvider` has to be created which is responsible for the creation of a `ConfigurationBuilder` associated with the custom tag. An instance of this class has to be registered at the `CombinedBuilderParametersImpl` object which is used to initialize this `CombinedConfigurationBuilder`. This provider will then be called when the corresponding custom tag is detected. For many default configuration classes providers are already registered.

The configuration definition file has the following basic structure:

     <configuration systemProperties="properties file name">
       <header>
         <!-- Optional meta information about the combined 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. The optional `systemProperties` attribute identifies the path to a property file containing properties that should be added to the system properties. If specified on the root element, the system properties are set before the rest of the configuration is processed.

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 `CombinedConfigurationBuilderProvider`. This can be one of the predefined tags like `properties`, or `xml`, or a custom tag, for which a configuration builder provider was registered (as described above). 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:

Standard attributes for configuration declarations
Attribute | Meaning
--- | ---
`config-name` | Allows specifying a name for this configuration. This name can be used to obtain a reference to the configuration from the resulting combined configuration (see below). It can also be passed to the `getNamedBuilder(String)` method.
`config-at` | With this attribute an optional prefix can be specified for the properties of the corresponding configuration.
`config-optional` | Declares a configuration source as optional. This means that errors that occur when creating the configuration are ignored.
`config-reload` | Many configuration sources support a reloading mechanism. For those sources it is possible to enable reloading by providing this attribute with a value of true.

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 default configuration object returned by this builder is an instance of the `CombinedConfiguration` class. This allows for convenient access to the configuration objects maintained by the combined configuration (for example 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. The actual `CombinedConfiguration` implementation can be overridden by specifying the class in the config-class attribute of the result element.

A custom EntityResolver can be used for all XMLConfigurations by adding

     <entity-resolver config-class="EntityResolver fully qualified class name">

A specific CatalogResolver can be specified for all XMLConfiguration sources by adding

     <entity-resolver catalogFiles="comma separated list of catalog files">

Additional ConfigurationProviders can be added by configuring them in the header section.

     <providers>
       <provider config-tag="tag name" config-class="provider fully qualified class name"/>
     </providers>

Additional variable resolvers can be added by configuring them in the header section.

     <lookups>
       <lookup config-prefix="prefix" config-class="StrLookup fully qualified class name"/>
     </lookups>

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 altogether 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. The `getNamedBuilder(String)` method can be used to access the `ConfigurationBuilder` objects for all configuration sources which have been assigned a name; care has to be taken that these names are unique.

Since:
  1.3

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `ADDITIONAL_NAME`
  Constant for the name of the additional configuration.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CombinedConfigurationBuilder()`
  Creates a new instance of `CombinedConfigurationBuilder`.
  `CombinedConfigurationBuilder(Map<String,Object> params)`
  Creates a new instance of `CombinedConfigurationBuilder` and sets the specified initialization parameters.
  `CombinedConfigurationBuilder(Map<String,Object> params, boolean allowFailOnInit)`
  Creates a new instance of `CombinedConfigurationBuilder` and sets the specified initialization parameters and the allowFailOnInit flag.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Set<String>`
  `builderNames()`
  Returns a set with the names of all child configuration builders.
  `CombinedConfigurationBuilder`
  `configure(BuilderParameters... params)`
  Appends the content of the specified `BuilderParameters` objects to the current initialization parameters.
  `protected void`
  `configureEntityResolver(HierarchicalConfiguration<?> config, XMLBuilderParametersImpl xmlParams)`
  Creates and initializes a default `EntityResolver` if the definition configuration contains a corresponding declaration.
  `protected CombinedConfiguration`
  `createAdditionalsConfiguration(CombinedConfiguration resultConfig)`
  Creates the `CombinedConfiguration` for the configuration sources in the `&lt;additional&gt;` section.
  `protected BeanDeclaration`
  `createResultDeclaration(Map<String,Object> params)`
  Creates a new `BeanDeclaration` which is used for creating new result objects dynamically.
  `protected ConfigurationBuilder<? extends HierarchicalConfiguration<?>>`
  `createXMLDefinitionBuilder(BuilderParameters builderParams)`
  Creates a default builder for the definition configuration and initializes it with a parameters object.
  `protected Collection<ConfigurationBuilder<? extends Configuration>>`
  `getChildBuilders()`
  Gets a collection with the builders for all child configuration sources.
  `ConfigurationBuilder<? extends HierarchicalConfiguration<?>>`
  `getDefinitionBuilder()`
  Gets the `ConfigurationBuilder` which creates the definition configuration.
  `protected HierarchicalConfiguration<?>`
  `getDefinitionConfiguration()`
  Gets the configuration containing the definition of the combined configuration to be created.
  `ConfigurationBuilder<? extends Configuration>`
  `getNamedBuilder(String name)`
  Gets the configuration builder with the given name.
  `protected void`
  `initChildBuilderParameters(BuilderParameters params)`
  Initializes a parameters object for a child builder.
  `protected FileSystem`
  `initFileSystem(HierarchicalConfiguration<?> config)`
  Creates and initializes a default `FileSystem` if the definition configuration contains a corresponding declaration.
  `protected void`
  `initResultInstance(CombinedConfiguration result)`
  Initializes a newly created result object.
  `protected void`
  `initSystemProperties(HierarchicalConfiguration<?> config, String basePath)`
  Handles a file with system properties that may be defined in the definition configuration.
  `protected ConfigurationBuilderProvider`
  `providerForTag(String tagName)`
  Returns the `ConfigurationBuilderProvider` for the given tag.
  `protected void`
  `registerConfiguredLookups(HierarchicalConfiguration<?> defConfig, Configuration resultConfig)`
  Processes custom `Lookup` objects that might be declared in the definition configuration.
  `void`
  `resetParameters()`
  Removes all initialization parameters of this builder.
  `protected ConfigurationBuilder<? extends HierarchicalConfiguration<?>>`
  `setupDefinitionBuilder(Map<String,Object> params)`
  Obtains the `ConfigurationBuilder` object which provides access to the configuration containing the definition of the combined configuration to create.

  ### Methods inherited from class org.apache.commons.configuration2.builder.BasicConfigurationBuilder

  `addEventListener, addParameters, connectToReloadingController, copyEventListeners, copyEventListeners, createResult, createResultInstance, fetchBeanHelper, fireBuilderEvent, getConfiguration, getParameters, getResultClass, getResultDeclaration, installEventListener, isAllowFailOnInit, removeEventListener, reset, resetResult, setParameters`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

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

- ## Constructor Details

  - ### CombinedConfigurationBuilder

    public CombinedConfigurationBuilder()
    Creates a new instance of `CombinedConfigurationBuilder`. No parameters are set.

  - ### CombinedConfigurationBuilder

    public CombinedConfigurationBuilder(Map<String,Object> params)
    Creates a new instance of `CombinedConfigurationBuilder` and sets the specified initialization parameters.
    Parameters:
      `params` - a map with initialization parameters

  - ### CombinedConfigurationBuilder

    public CombinedConfigurationBuilder(Map<String,Object> params, boolean allowFailOnInit)
    Creates a new instance of `CombinedConfigurationBuilder` and sets the specified initialization parameters and the allowFailOnInit flag.
    Parameters:
      `params` - a map with initialization parameters
      `allowFailOnInit` - the allowFailOnInit flag

- ## Method Details

  - ### builderNames

    public Set<String> builderNames()

    Returns a set with the names of all child configuration builders. A tag defining a configuration source in the configuration definition file can have the `config-name` attribute. If this attribute is present, the corresponding builder is assigned this name and can be directly accessed through the `getNamedBuilder(String)` method. This method returns a collection with all available builder names.

    Important note: This method only returns a meaningful result after the result configuration has been created by calling `getConfiguration()`. If called before, always an empty set is returned.

    Returns:
      a set with the names of all builders

  - ### configure

    public CombinedConfigurationBuilder configure(BuilderParameters... params)
    Appends the content of the specified `BuilderParameters` objects to the current initialization parameters. Calling this method multiple times will create a union of the parameters provided. This method is overridden to adapt the return type.
    Overrides:
      `configure` in class `BasicConfigurationBuilder<CombinedConfiguration>`
    Parameters:
      `params` - an arbitrary number of objects with builder parameters
    Returns:
      a reference to this builder for method chaining

  - ### configureEntityResolver

    protected void configureEntityResolver(HierarchicalConfiguration<?> config, XMLBuilderParametersImpl xmlParams) throws ConfigurationException
    Creates and initializes a default `EntityResolver` if the definition configuration contains a corresponding declaration.
    Parameters:
      `config` - the definition configuration
      `xmlParams` - the (already partly initialized) object with XML parameters; here the new resolver is to be stored
    Throws:
      `ConfigurationException` - if an error occurs

  - ### createAdditionalsConfiguration

    protected CombinedConfiguration createAdditionalsConfiguration(CombinedConfiguration resultConfig)
    Creates the `CombinedConfiguration` for the configuration sources in the `&lt;additional&gt;` section. This method is called when the builder constructs the final configuration. It creates a new `CombinedConfiguration` and initializes some properties from the result configuration.
    Parameters:
      `resultConfig` - the result configuration (this is the configuration that will be returned by the builder)
    Returns:
      the `CombinedConfiguration` for the additional configuration sources
    Since:
      1.7

  - ### createResultDeclaration

    protected BeanDeclaration createResultDeclaration(Map<String,Object> params) throws ConfigurationException
    Creates a new `BeanDeclaration` which is used for creating new result objects dynamically. This implementation creates a specialized `BeanDeclaration` object that is initialized from the given map of initialization parameters. The `BeanDeclaration` must be initialized with the result class of this builder, otherwise exceptions will be thrown when the result object is created. Note: This method is invoked in a synchronized block. This implementation evaluates the `result` property of the definition configuration. It creates a combined bean declaration with both the properties specified in the definition file and the properties defined as initialization parameters.
    Overrides:
      `createResultDeclaration` in class `BasicConfigurationBuilder<CombinedConfiguration>`
    Parameters:
      `params` - a snapshot of the current initialization parameters
    Returns:
      the `BeanDeclaration` for creating result objects
    Throws:
      `ConfigurationException` - if an error occurs

  - ### createXMLDefinitionBuilder

    protected ConfigurationBuilder<? extends HierarchicalConfiguration<?>> createXMLDefinitionBuilder(BuilderParameters builderParams)
    Creates a default builder for the definition configuration and initializes it with a parameters object. This method is called if no definition builder is defined in this builder's parameters. This implementation creates a default file-based builder which produces an `XMLConfiguration`; it expects a corresponding file specification. Note: This method is called in a synchronized block.
    Parameters:
      `builderParams` - the parameters object for the builder
    Returns:
      the standard builder for the definition configuration

  - ### getChildBuilders

    protected Collection<ConfigurationBuilder<? extends Configuration>> getChildBuilders()
    Gets a collection with the builders for all child configuration sources. This method can be used by derived classes providing additional functionality on top of the declared configuration sources. It only returns a defined value during construction of the result configuration instance.
    Returns:
      a collection with the builders for child configuration sources

  - ### getDefinitionBuilder

    public ConfigurationBuilder<? extends HierarchicalConfiguration<?>> getDefinitionBuilder() throws ConfigurationException
    Gets the `ConfigurationBuilder` which creates the definition configuration.
    Returns:
      the builder for the definition configuration
    Throws:
      `ConfigurationException` - if an error occurs

  - ### getDefinitionConfiguration

    protected HierarchicalConfiguration<?> getDefinitionConfiguration() throws ConfigurationException
    Gets the configuration containing the definition of the combined configuration to be created. This method only returns a defined result during construction of the result configuration. The definition configuration is obtained from the definition builder at first access and then stored temporarily to ensure that during result construction always the same configuration instance is used. (Otherwise, it would be possible that the definition builder returns a different instance when queried multiple times.)
    Returns:
      the definition configuration
    Throws:
      `ConfigurationException` - if an error occurs

  - ### getNamedBuilder

    public ConfigurationBuilder<? extends Configuration> getNamedBuilder(String name) throws ConfigurationException

    Gets the configuration builder with the given name. With this method a builder of a child configuration which was given a name in the configuration definition file can be accessed directly.

    Important note: This method only returns a meaningful result after the result configuration has been created by calling `getConfiguration()`. If called before, always an exception is thrown.

    Parameters:
      `name` - the name of the builder in question
    Returns:
      the child configuration builder with this name
    Throws:
      `ConfigurationException` - if information about named builders is not yet available or no builder with this name exists

  - ### initChildBuilderParameters

    protected void initChildBuilderParameters(BuilderParameters params)
    Initializes a parameters object for a child builder. This combined configuration builder has a bunch of properties which may be inherited by child configurations, for example the base path, the file system, etc. While processing the builders for child configurations, this method is called for each parameters object for a child builder. It initializes some properties of the passed in parameters objects which are derived from this parent builder.
    Parameters:
      `params` - the parameters object to be initialized

  - ### initFileSystem

    protected FileSystem initFileSystem(HierarchicalConfiguration<?> config) throws ConfigurationException
    Creates and initializes a default `FileSystem` if the definition configuration contains a corresponding declaration. The file system returned by this method is used as default for all file-based child configuration sources.
    Parameters:
      `config` - the definition configuration
    Returns:
      the default `FileSystem` (may be null)
    Throws:
      `ConfigurationException` - if an error occurs

  - ### initResultInstance

    protected void initResultInstance(CombinedConfiguration result) throws ConfigurationException
    Initializes a newly created result object. This is the second step of the process of producing a result object for this builder. This implementation uses the `BeanHelper` class to initialize the object's property based on the `BeanDeclaration` returned by `BasicConfigurationBuilder.getResultDeclaration()`. Note: This method is invoked in a synchronized block. This is required because internal state is accessed. Sub classes must not call this method without proper synchronization. This implementation processes the definition configuration in order to
    - initialize the resulting `CombinedConfiguration`
    - determine the builders for all configuration sources
    - populate the resulting `CombinedConfiguration`
    Overrides:
      `initResultInstance` in class `BasicConfigurationBuilder<CombinedConfiguration>`
    Parameters:
      `result` - the object to be initialized
    Throws:
      `ConfigurationException` - if an error occurs

  - ### initSystemProperties

    protected void initSystemProperties(HierarchicalConfiguration<?> config, String basePath) throws ConfigurationException
    Handles a file with system properties that may be defined in the definition configuration. If such property file is configured, all of its properties are added to the system properties.
    Parameters:
      `config` - the definition configuration
      `basePath` - the base path defined for this builder (may be null)
    Throws:
      `ConfigurationException` - if an error occurs.

  - ### providerForTag

    protected ConfigurationBuilderProvider providerForTag(String tagName)
    Returns the `ConfigurationBuilderProvider` for the given tag. This method is called during creation of the result configuration. (It is not allowed to call it at another point of time; result is then unpredictable!) It supports all default providers and custom providers added through the parameters object as well.
    Parameters:
      `tagName` - the name of the tag
    Returns:
      the provider that was registered for this tag or null if there is none

  - ### registerConfiguredLookups

    protected void registerConfiguredLookups(HierarchicalConfiguration<?> defConfig, Configuration resultConfig) throws ConfigurationException
    Processes custom `Lookup` objects that might be declared in the definition configuration. Each `Lookup` object is registered at the definition configuration and at the result configuration. It is also added to all child configurations added to the resulting combined configuration.
    Parameters:
      `defConfig` - the definition configuration
      `resultConfig` - the resulting configuration
    Throws:
      `ConfigurationException` - if an error occurs

  - ### resetParameters

    public void resetParameters()
    Removes all initialization parameters of this builder. This method can be called if this builder is to be reused for creating result objects with a different configuration. This implementation resets some specific internal state of this builder.
    Overrides:
      `resetParameters` in class `BasicConfigurationBuilder<CombinedConfiguration>`

  - ### setupDefinitionBuilder

    protected ConfigurationBuilder<? extends HierarchicalConfiguration<?>> setupDefinitionBuilder(Map<String,Object> params) throws ConfigurationException
    Obtains the `ConfigurationBuilder` object which provides access to the configuration containing the definition of the combined configuration to create. If a definition builder is defined in the parameters, it is used. Otherwise, we check whether the combined builder parameters object contains a parameters object for the definition builder. If this is the case, a builder for an `XMLConfiguration` is created and configured with this object. As a last resort, it is looked for a `FileBasedBuilderParametersImpl` object in the properties. If found, also a XML configuration builder is created which loads this file. Note: This method is called from a synchronized block.
    Parameters:
      `params` - the current parameters for this builder
    Returns:
      the builder for the definition configuration
    Throws:
      `ConfigurationException` - if an error occurs