##### Configuration

- Home
- Download
- Release History
- User's Guide
- Howtos (1.2 release)
- Runtime Dependencies
- Javadoc (current release)
- Javadoc (old releases)

##### Development

- Building
- Roadmap
- Issue Tracking
- SVN

##### Project Documentation

- About Commons Configuration
- Downloads
- Project Info
- Project Reports
- Development Process

##### Commons

- Home
- Components
- Sandbox
- Dormant
- Volunteering
- Contributing Patches
- Building Components
- Releasing Components
- Wiki

## Combined Configuration

The `CombinedConfiguration` class provides an alternative for handling multiple configuration sources. Its API is very similar to the `CompositeConfiguration` class, which was discussed in the last section. There are the following differences however:

- A `CombinedConfiguration` is a truely hierarchical configuration. This means that all the enhanced facilities provided by `HierarchicalConfiguration` (e.g. expression engines) can be used.
- A `CombinedConfiguration` is not limited to implementing an override semantics for the properties of the contained configurations. Instead it has the concept of so-called node combiners, which know how properties of multiple configuration sources can be combined. Node combiners are discussed later in detail. For instance, there is a node combiner implementation available that constructs a union of the contained configurations.
- Contained configurations can be assigned a name. They can later be accessed by their name.
- Each contained configuration can have an optional prefix. Its properties are then added under this prefix to the combined configuration.
- There is no concept of an in memory configuration. Changes to a combined configuration are handled in a different way.

### How it works

A `CombinedConfiguration` provides a logic view on the properties of the configurations it contains. This view is determined by the associated node combiner object. Because of that it must be re-constructed whenever one of these contained configurations is changed.

To achieve this, a `CombinedConfiguration` object registers itself as an event listener at the configurations that are added to it. It will then be notified for every modification that occurs. If such a notification is received, the internally managed view is invalidated. When a property of the combined configuration is to be accessed, the view is checked whether it is valid. If this is the case, the property's value can be directly fetched. Otherwise the associated node combiner is asked to re-construct the view.

### Node combiners

A node combiner is an object of a class that inherits from the abstract `NodeCombiner` class. This class defines an abstract `combine()` method, which takes the root nodes of two hierarchical configurations and returns the root node of the combined node structure. It is up to a concrete implementation how this combined structure will look like. Commons Configuration ships with the two concrete implementations `OverrideCombiner` and `UnionCombiner`, which implement an override and a union semantics respective.

Constructing a combination of multiple node hierarchies is not a trivial task. The available implementations descend the passed in node hierarchies in a recursive manner to decide, which nodes have to be copied into the resulting structure. Under certain circumstances two nodes of the source structures can be combined into a single result node, but unfortunately this process cannot be fully automated, but sometimes needs some hints from the developer. As an example consider the following XML configuration sources:

    <configuration>
      <database>
        <tables>
          <table>
            <name>users</name>
            <fields>
              <field>
                <name>user_id</name>
              </field>
              ...
            </fields>
          </table>
        </tables>
      </database>
    </configuration>

and

    <configuration>
      <database>
        <tables>
          <table>
            <name>documents</name>
            <fields>
              <field>
                <name>document_id</name>
              </field>
              ...
            </fields>
          </table>
        </tables>
      </database>
    </configuration>

These two configuration sources define database tables. Each source defines one table. When constructing a union for these sources the result should look as follows:

    <configuration>
      <database>
        <tables>
          <table>
            <name>users</name>
            <fields>
              <field>
                <name>user_id</name>
              </field>
              ...
            </fields>
          </table>
          <table>
            <name>documents</name>
            <fields>
              <field>
                <name>document_id</name>
              </field>
              ...
            </fields>
          </table>
        </tables>
      </database>
    </configuration>

As you can see, the resulting structure contains two `table` nodes while the nodes `database` and `tables` appear only once. For a human being this is quite logic because `database` and `tables` define the overall structure of the configuration data, and there can be multiple tables. A node combiner however does not know anything about structure nodes, list nodes, or whatever. From its point of view there is no detectable difference between the `tables` nodes and the `table` nodes in the source structures: both appear once in each source file and have no values. So without any assistance the result constructed by the `UnionCombiner` when applied on the two example sources would be a bit different:

    <configuration>
      <database>
        <tables>
          <table>
            <name>users</name>
            <fields>
              <field>
                <name>user_id</name>
              </field>
              ...
            </fields>
            <name>documents</name>
            <fields>
              <field>
                <name>document_id</name>
              </field>
              ...
            </fields>
          </table>
        </tables>
      </database>
    </configuration>

Note that the `table` node would be considered a structure node, too, and would not be duplicated. This is probably not what was desired. To deal with such situations it is possible to tell the node combiner that certain nodes are list nodes and thus should not be combined. So in this concrete example the `table` node should be declared as a list node, then we would get the expected result. We will see below how this is done. Note that this explicit declaration of a list node is necessary only in situations where there is ambiguity. If in one of our example configuration sources multiple tables had been defined, the node combiner would have concluded itself that `table` is a list node and would have acted correspondigly.

### Constructing a CombinedConfiguration

To create a `CombinedConfiguration` object you specify the node combiner to use and then add an arbitrary number of configurations. We will show how to construct a union configuration from the two example sources introduced earlier:

    // Load the source configurations
    XMLConfiguration conf1 = new XMLConfiguration("table1.xml");
    XMLConfiguration conf2 = new XMLConfiguration("table2.xml");

    // Create and initialize the node combiner
    NodeCombiner combiner = new UnionCombiner();
    combiner.addListNode("table");  // mark table as list node
                // this is needed only if there are ambiguities

    // Construct the combined configuration
    CombinedConfiguration cc = new CombinedConfiguration(combiner);
    cc.addConfiguration(conf1, "tab1");
    cc.addConfiguration(conf2);

Here we also specified a name for one of the configurations, so it can later be accessed by `cc.getConfiguration("tab1");`. Access by index is also supported. After that the properties in the combined configuration can be accessed as if it were a normal hierarchical configuration

### Dealing with changes

There is nothing that prevents you from updating a combined configuration, e.g. by calling methods like `addProperty()` or `removeProperty()`. The problem is that depending on the used node combiner it might no be clear, which of the contained configurations will be modified or whether one is modified at all.

Typical node combiners work by copying parts of the node structures of the source configurations into the target structure and linking them togehter using special link nodes. So updates of the combined node structure will either effect nodes from one of the contained configuration (then the changes are directly visible in this configuration) or one of the link nodes (then they cannot really be saved).

It is also possible that a change is done at the combined node structure, which is not compatible with the current node combiner. Imagine that an `OverrideCombiner` is used and that a property should be removed. This property will then be removed from one of the contained configurations. Now it may happen that this removed property had hidden property values of other contained configurations. Their values won't become visible automatically, but only after the combined view was re-constructed.

Because of that it is recommended that changes are not done at the combined configuration, but only at contained configurations. This way the correct configuration to be updated can unambigously be identified. Obtaining the configuration to be updated from the combined configuration is easy when it was given a name.