## org.apache.commons.configuration
Class CombinedConfiguration

    java.lang.Object
      org.apache.commons.configuration.event.EventSource
          org.apache.commons.configuration.AbstractConfiguration
              org.apache.commons.configuration.HierarchicalConfiguration
                  org.apache.commons.configuration.CombinedConfiguration

All Implemented Interfaces:
  Serializable, Cloneable, Configuration, ConfigurationListener

    public class CombinedConfiguration

extends HierarchicalConfiguration
implements ConfigurationListener, Cloneable

A hierarchical composite configuration class.

This class maintains a list of configuration objects, which can be added using the divers `addConfiguration()` methods. After that the configurations can be accessed either by name (if one was provided when the configuration was added) or by index. For the whole set of managed configurations a logical node structure is constructed. For this purpose a ``NodeCombiner`` object can be set. This makes it possible to specify different algorithms for the combination process.

The big advantage of this class is that it creates a truely hierarchical structure of all the properties stored in the contained configurations - even if some of them are no hierarchical configurations per se. So all enhanced features provided by a hierarchical configuration (e.g. choosing an expression engine) are applicable.

The class works by registering itself as an event listener add all added configurations. So it gets notified whenever one of these configurations is changed and can invalidate its internal node structure. The next time a property is accessed the node structure will be re-constructed using the current state of the managed configurations. Node that, depending on the used `NodeCombiner`, this may be a complex operation.

It is not strictly forbidden to manipulate a `CombinedConfiguration` directly, but the results may be unpredictable. For instance some node combiners use special view nodes for linking parts of the original configurations' data together. If new properties are added to such a special node, they do not belong to any of the managed configurations and thus hang in the air. It is also possible that direct updates on a `CombinedConfiguration` are incompatible with the used node combiner (e.g. if the ``OverrideCombiner`` is used and properties are removed the resulting node structure may be incorrect because some properties that were hidden by the removed properties are not visible). So it is recommended to perform updates only on the managed configurations.

Whenever the node structure of a `CombinedConfiguration` becomes invalid (either because one of the contained configurations was modified or because the `invalidate()` method was directly called) an event is generated. So this can be detected by interested event listeners. This also makes it possible to add a combined configuration into another one.

Implementation note: Adding and removing configurations to and from a combined configuration is not thread-safe. If a combined configuration is manipulated by multiple threads, the developer has to take care about properly synchronization.

Since:
  1.3
Version:
  $Id: CombinedConfiguration.java 439648 2006-09-02 20:42:10Z oheger $
Author:
  Commons Configuration team
See Also:
  Serialized Form

Nested Class Summary
`(package private) static class` `CombinedConfiguration.ConfigData` An internal helper class for storing information about contained configurations.

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 int` `EVENT_COMBINED_INVALIDATE` Constant for the invalidate event that is fired when the internal node structure becomes invalid.

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
`CombinedConfiguration()` Creates a new instance of `CombinedConfiguration` that uses a union combiner.
`CombinedConfiguration(NodeCombiner comb)` Creates a new instance of `CombinedConfiguration` and initializes the combiner to be used.

Method Summary
`void` `addConfiguration(AbstractConfiguration config)` Adds a new configuration to this combined configuration.
`void` `addConfiguration(AbstractConfiguration config, String name)` Adds a new configuration to this combined configuration with an optional name.
`void` `addConfiguration(AbstractConfiguration config, String name, String at)` Adds a new configuration to this combined configuration.
`void` `clear()` Clears this configuration.
`Object` `clone()` Returns a copy of this object.
`void` `configurationChanged(ConfigurationEvent event)` Event listener call back for configuration update events.
`Configuration` `getConfiguration(int index)` Returns the configuration at the specified index.
`Configuration` `getConfiguration(String name)` Returns the configuration with the given name.
`Set` `getConfigurationNames()` Returns a set with the names of all configurations contained in this combined configuration.
`NodeCombiner` `getNodeCombiner()` Returns the node combiner that is used for creating the combined node structure.
`int` `getNumberOfConfigurations()` Returns the number of configurations that are contained in this combined configuration.
`ConfigurationNode` `getRootNode()` Returns the configuration root node of this combined configuration.
`void` `invalidate()` Invalidates this combined configuration.
`boolean` `removeConfiguration(Configuration config)` Removes the specified configuration from this combined configuration.
`Configuration` `removeConfiguration(String name)` Removes the configuration with the specified name.
`Configuration` `removeConfigurationAt(int index)` Removes the configuration at the specified index.
`void` `setNodeCombiner(NodeCombiner nodeCombiner)` Sets the node combiner.

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

`addNodes, addPropertyDirect, clearNode, clearNode, clearProperty, clearTree, configurationAt, configurationsAt, containsKey, createAddPath, createNode, createSubnodeConfiguration, fetchAddNode, fetchNodeList, findLastPathNode, findPropertyNodes, getDefaultExpressionEngine, getExpressionEngine, getKeys, getKeys, getMaxIndex, getProperty, getRoot, isEmpty, nodeDefined, nodeDefined, removeNode, removeNode, setDefaultExpressionEngine, setExpressionEngine, setProperty, 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, 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`

Field Detail

### EVENT_COMBINED_INVALIDATE

    public static final int EVENT_COMBINED_INVALIDATE

  Constant for the invalidate event that is fired when the internal node structure becomes invalid.

  See Also:
    Constant Field Values

Constructor Detail

### CombinedConfiguration

    public CombinedConfiguration(NodeCombiner comb)

  Creates a new instance of `CombinedConfiguration` and initializes the combiner to be used.

  Parameters:
    `comb` - the node combiner (can be null, then a union combiner is used as default)

### CombinedConfiguration

    public CombinedConfiguration()

  Creates a new instance of `CombinedConfiguration` that uses a union combiner.

  See Also:
    `UnionCombiner`

Method Detail

### getNodeCombiner

    public NodeCombiner getNodeCombiner()

  Returns the node combiner that is used for creating the combined node structure.

  Returns:
    the node combiner

### setNodeCombiner

    public void setNodeCombiner(NodeCombiner nodeCombiner)

  Sets the node combiner. This object will be used when the combined node structure is to be constructed. It must not be null, otherwise an `IllegalArgumentException` exception is thrown. Changing the node combiner causes an invalidation of this combined configuration, so that the new combiner immediately takes effect.

  Parameters:
    `nodeCombiner` - the node combiner

### addConfiguration

    public void addConfiguration(AbstractConfiguration config,
                                 String name,
                                 String at)

  Adds a new configuration to this combined configuration. It is possible (but not mandatory) to give the new configuration a name. This name must be unique, otherwise a `ConfigurationRuntimeException` will be thrown. With the optional `at` argument you can specify where in the resulting node structure the content of the added configuration should appear. This is a string that uses dots as property delimiters (independent on the current expression engine). For instance if you pass in the string `"database.tables"`, all properties of the added configuration will occur in this branch.

  Parameters:
    `config` - the configuration to add (must not be null)
    `name` - the name of this configuration (can be null)
    `at` - the position of this configuration in the combined tree (can be null)

### addConfiguration

    public void addConfiguration(AbstractConfiguration config,
                                 String name)

  Adds a new configuration to this combined configuration with an optional name. The new configuration's properties will be added under the root of the combined node structure.

  Parameters:
    `config` - the configuration to add (must not be null)
    `name` - the name of this configuration (can be null)

### addConfiguration

    public void addConfiguration(AbstractConfiguration config)

  Adds a new configuration to this combined configuration. The new configuration is not given a name. Its properties will be added under the root of the combined node structure.

  Parameters:
    `config` - the configuration to add (must not be null)

### getNumberOfConfigurations

    public int getNumberOfConfigurations()

  Returns the number of configurations that are contained in this combined configuration.

  Returns:
    the number of contained configurations

### getConfiguration

    public Configuration getConfiguration(int index)

  Returns the configuration at the specified index. The contained configurations are numbered in the order they were added to this combined configuration. The index of the first configuration is 0.

  Parameters:
    `index` - the index
  Returns:
    the configuration at this index

### getConfiguration

    public Configuration getConfiguration(String name)

  Returns the configuration with the given name. This can be null if no such configuration exists.

  Parameters:
    `name` - the name of the configuration
  Returns:
    the configuration with this name

### removeConfiguration

    public boolean removeConfiguration(Configuration config)

  Removes the specified configuration from this combined configuration.

  Parameters:
    `config` - the configuration to be removed
  Returns:
    a flag whether this configuration was found and could be removed

### removeConfigurationAt

    public Configuration removeConfigurationAt(int index)

  Removes the configuration at the specified index.

  Parameters:
    `index` - the index
  Returns:
    the removed configuration

### removeConfiguration

    public Configuration removeConfiguration(String name)

  Removes the configuration with the specified name.

  Parameters:
    `name` - the name of the configuration to be removed
  Returns:
    the removed configuration (null if this configuration was not found)

### getConfigurationNames

    public Set getConfigurationNames()

  Returns a set with the names of all configurations contained in this combined configuration. Of course here are only these configurations listed, for which a name was specified when they were added.

  Returns:
    a set with the names of the contained configurations (never null)

### invalidate

    public void invalidate()

  Invalidates this combined configuration. This means that the next time a property is accessed the combined node structure must be re-constructed. Invalidation of a combined configuration also means that an event of type `EVENT_COMBINED_INVALIDATE` is fired. Note that while other events most times appear twice (once before and once after an update), this event is only fired once (after update).

### configurationChanged

    public void configurationChanged(ConfigurationEvent event)

  Event listener call back for configuration update events. This method is called whenever one of the contained configurations was modified. It invalidates this combined configuration.

  Specified by:
    `configurationChanged` in interface `ConfigurationListener`
  Parameters:
    `event` - the update event

### getRootNode

    public ConfigurationNode getRootNode()

  Returns the configuration root node of this combined configuration. This method will construct a combined node structure using the current node combiner if necessary.

  Overrides:
    `getRootNode` in class `HierarchicalConfiguration`
  Returns:
    the combined root node

### clear

    public void clear()

  Clears this configuration. All contained configurations will be removed.

  Specified by:
    `clear` in interface `Configuration`
  Overrides:
    `clear` in class `AbstractConfiguration`

### clone

    public Object clone()

  Returns a copy of this object. This implementation performs a deep clone, i.e. all contained configurations will be cloned, too. For this to work, all contained configurations must be cloneable. Registered event listeners won't be cloned. The clone will use the same node combiner than the original.

  Overrides:
    `clone` in class `HierarchicalConfiguration`
  Returns:
    the copied object

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