## org.apache.commons.configuration
Class CompositeConfiguration

    java.lang.Object
      org.apache.commons.configuration.event.EventSource
          org.apache.commons.configuration.AbstractConfiguration
              org.apache.commons.configuration.CompositeConfiguration

All Implemented Interfaces:
  Cloneable, Configuration

    public class CompositeConfiguration

extends AbstractConfiguration
implements Cloneable

`CompositeConfiguration` allows you to add multiple `Configuration` objects to an aggregated configuration. If you add Configuration1, and then Configuration2, any properties shared will mean that the value defined by Configuration1 will be returned. If Configuration1 doesn't have the property, then Configuration2 will be checked. You can add multiple different types or the same type of properties file.

When querying properties the order in which child configurations have been added is relevant. To deal with property updates, a so-called in-memory configuration is used. Per default, such a configuration is created automatically. All property writes target this special configuration. There are constructors which allow you to provide a specific in-memory configuration. If used that way, the in-memory configuration is always the last one in the list of child configurations. This means that for query operations all other configurations take precedence.

Alternatively it is possible to mark a child configuration as in-memory configuration when it is added. In this case the treatment of the in-memory configuration is slightly different: it remains in the list of child configurations at the position it was added, i.e. its priority for property queries can be defined by adding the child configurations in the correct order.

Version:
  $Id: CompositeConfiguration.java 1233058 2012-01-18 20:49:12Z oheger $
Author:
  Eric Pugh, Henning P. Schmiedehausen

Field Summary

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

Constructor Summary
`CompositeConfiguration()` Creates an empty CompositeConfiguration object which can then be added some other Configuration files
`CompositeConfiguration(Collection<? extends Configuration> configurations)` Create a CompositeConfiguration with an empty in memory configuration and adds the collection of configurations specified.
`CompositeConfiguration(Configuration inMemoryConfiguration)` Creates a CompositeConfiguration object with a specified in-memory configuration.
`CompositeConfiguration(Configuration inMemoryConfiguration, Collection<? extends Configuration> configurations)` Creates a CompositeConfiguration with a specified in-memory configuration, and then adds the given collection of configurations.

Method Summary
`void` `addConfiguration(Configuration config)` Add a configuration.
`void` `addConfiguration(Configuration config, boolean asInMemory)` Adds a child configuration and optionally makes it the in-memory configuration.
`protected void` `addPropertyDirect(String key, Object token)` Add this property to the inmemory Configuration.
`void` `clear()` Removes all child configurations and reinitializes the in-memory configuration.
`protected void` `clearPropertyDirect(String key)` Removes the specified property from this configuration.
`Object` `clone()` Returns a copy of this object.
`boolean` `containsKey(String key)` Check if the configuration contains the specified key.
`Configuration` `getConfiguration(int index)` Return the configuration at the specified index.
`Configuration` `getInMemoryConfiguration()` Returns the "in memory configuration".
`Iterator<String>` `getKeys()` Get the list of the keys contained in the configuration.
`Iterator<String>` `getKeys(String key)` Get the list of the keys contained in the configuration that match the specified prefix.
`List<Object>` `getList(String key, List<Object> defaultValue)` Get a List of strings associated with the given configuration key.
`int` `getNumberOfConfigurations()` Return the number of configurations.
`Object` `getProperty(String key)` Read property from underlying composite
`Configuration` `getSource(String key)` Returns the configuration source, in which the specified key is defined.
`String[]` `getStringArray(String key)` Get an array of strings associated with the given configuration key.
`boolean` `isEmpty()` Check if the configuration is empty.
`void` `removeConfiguration(Configuration config)` Remove a configuration.
`void` `setDelimiterParsingDisabled(boolean delimiterParsingDisabled)` Sets a flag whether added values for string properties should be checked for the list delimiter.
`void` `setListDelimiter(char listDelimiter)` Sets the character that is used as list delimiter.

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

`addErrorLogListener, addProperty, append, clearProperty, copy, createInterpolator, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDefaultListDelimiter, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getList, getListDelimiter, getLogger, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getSubstitutor, interpolate, interpolate, interpolatedConfiguration, interpolateHelper, isDelimiterParsingDisabled, isScalarValue, isThrowExceptionOnMissing, resolveContainerStore, setDefaultListDelimiter, setDelimiter, setLogger, setProperty, setThrowExceptionOnMissing, subset`

Methods inherited from class org.apache.commons.configuration.event.EventSource
`addConfigurationListener, addErrorListener, clearConfigurationListeners, clearErrorListeners, createErrorEvent, createEvent, fireError, fireEvent, getConfigurationListeners, getErrorListeners, isDetailEvents, removeConfigurationListener, removeErrorListener, setDetailEvents`

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### CompositeConfiguration

    public CompositeConfiguration()

  Creates an empty CompositeConfiguration object which can then be added some other Configuration files

### CompositeConfiguration

    public CompositeConfiguration(Configuration inMemoryConfiguration)

  Creates a CompositeConfiguration object with a specified in-memory configuration. This configuration will store any changes made to the `CompositeConfiguration`. Note: Use this constructor if you want to set a special type of in-memory configuration. If you have a configuration which should act as both a child configuration and as in-memory configuration, use `addConfiguration(Configuration, boolean)` with a value of true instead.

  Parameters:
    `inMemoryConfiguration` - the in memory configuration to use

### CompositeConfiguration

    public CompositeConfiguration(Collection<? extends Configuration> configurations)

  Create a CompositeConfiguration with an empty in memory configuration and adds the collection of configurations specified.

  Parameters:
    `configurations` - the collection of configurations to add

### CompositeConfiguration

    public CompositeConfiguration(Configuration inMemoryConfiguration,
                                  Collection<? extends Configuration> configurations)

  Creates a CompositeConfiguration with a specified in-memory configuration, and then adds the given collection of configurations.

  Parameters:
    `inMemoryConfiguration` - the in memory configuration to use
    `configurations` - the collection of configurations to add
  See Also:
    `CompositeConfiguration(Configuration)`

Method Detail

### addConfiguration

    public void addConfiguration(Configuration config)

  Add a configuration.

  Parameters:
    `config` - the configuration to add

### addConfiguration

    public void addConfiguration(Configuration config,
                                 boolean asInMemory)

  Adds a child configuration and optionally makes it the in-memory configuration. This means that all future property write operations are executed on this configuration. Note that the current in-memory configuration is replaced by the new one. If it was created automatically or passed to the constructor, it is removed from the list of child configurations! Otherwise, it stays in the list of child configurations at its current position, but it passes its role as in-memory configuration to the new one.

  Parameters:
    `config` - the configuration to be added
    `asInMemory` - true if this configuration becomes the new in-memory configuration, false otherwise
  Since:
    1.8

### removeConfiguration

    public void removeConfiguration(Configuration config)

  Remove a configuration. The in memory configuration cannot be removed.

  Parameters:
    `config` - The configuration to remove

### getNumberOfConfigurations

    public int getNumberOfConfigurations()

  Return the number of configurations.

  Returns:
    the number of configuration

### clear

    public void clear()

  Removes all child configurations and reinitializes the in-memory configuration. Attention: A new in-memory configuration is created; the old one is lost.

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

### addPropertyDirect

    protected void addPropertyDirect(String key,
                                     Object token)

  Add this property to the inmemory Configuration.

  Specified by:
    `addPropertyDirect` in class `AbstractConfiguration`
  Parameters:
    `key` - The Key to add the property to.
    `token` - The Value to add.

### getProperty

    public Object getProperty(String key)

  Read property from underlying composite

  Specified by:
    `getProperty` in interface `Configuration`
  Parameters:
    `key` - key to use for mapping
  Returns:
    object associated with the given configuration key.

### getKeys

    public Iterator<String> getKeys()

  Description copied from interface: `Configuration`
  Get the list of the keys contained in the configuration. The returned iterator can be used to obtain all defined keys. Note that the exact behavior of the iterator's `remove()` method is specific to a concrete implementation. It may remove the corresponding property from the configuration, but this is not guaranteed. In any case it is no replacement for calling `Configuration.clearProperty(String)` for this property. So it is highly recommended to avoid using the iterator's `remove()` method.

  Specified by:
    `getKeys` in interface `Configuration`
  Returns:
    An Iterator.

### getKeys

    public Iterator<String> getKeys(String key)

  Description copied from class: `AbstractConfiguration`
  Get the list of the keys contained in the configuration that match the specified prefix. For instance, if the configuration contains the following keys:
  `db.user, db.pwd, db.url, window.xpos, window.ypos`,
  an invocation of `getKeys("db");`
  will return the keys below:
  `db.user, db.pwd, db.url`.
  Note that the prefix itself is included in the result set if there is a matching key. The exact behavior - how the prefix is actually interpreted - depends on a concrete implementation. This implementation returns keys that either match the prefix or start with the prefix followed by a dot ('.'). So the call `getKeys("db");` will find the keys `db`, `db.user`, or `db.password`, but not the key `dbdriver`.

  Specified by:
    `getKeys` in interface `Configuration`
  Overrides:
    `getKeys` in class `AbstractConfiguration`
  Parameters:
    `key` - The prefix to test against.
  Returns:
    An Iterator of keys that match the prefix.
  See Also:
    `Configuration.getKeys()`

### isEmpty

    public boolean isEmpty()

  Description copied from interface: `Configuration`
  Check if the configuration is empty.

  Specified by:
    `isEmpty` in interface `Configuration`
  Returns:
    `true` if the configuration contains no property, `false` otherwise.

### clearPropertyDirect

    protected void clearPropertyDirect(String key)

  Description copied from class: `AbstractConfiguration`
  Removes the specified property from this configuration. This method is called by `clearProperty()` after it has done some preparations. It should be overridden in sub classes. This base implementation is just left empty.

  Overrides:
    `clearPropertyDirect` in class `AbstractConfiguration`
  Parameters:
    `key` - the key to be removed

### containsKey

    public boolean containsKey(String key)

  Description copied from interface: `Configuration`
  Check if the configuration contains the specified key.

  Specified by:
    `containsKey` in interface `Configuration`
  Parameters:
    `key` - the key whose presence in this configuration is to be tested
  Returns:
    `true` if the configuration contains a value for this key, `false` otherwise

### getList

    public List<Object> getList(String key,
                                List<Object> defaultValue)

  Description copied from interface: `Configuration`
  Get a List of strings associated with the given configuration key. If the key doesn't map to an existing object, the default value is returned.

  Specified by:
    `getList` in interface `Configuration`
  Overrides:
    `getList` in class `AbstractConfiguration`
  Parameters:
    `key` - The configuration key.
    `defaultValue` - The default value.
  Returns:
    The associated List of strings.

### getStringArray

    public String[] getStringArray(String key)

  Description copied from class: `AbstractConfiguration`
  Get an array of strings associated with the given configuration key. If the key doesn't map to an existing object, an empty array is returned. If a property is added to a configuration, it is checked whether it contains multiple values. This is obvious if the added object is a list or an array. For strings it is checked whether the string contains the list delimiter character that can be specified using the `setListDelimiter()` method. If this is the case, the string is split at these positions resulting in a property with multiple values.

  Specified by:
    `getStringArray` in interface `Configuration`
  Overrides:
    `getStringArray` in class `AbstractConfiguration`
  Parameters:
    `key` - The configuration key.
  Returns:
    The associated string array if key is found.
  See Also:
    `AbstractConfiguration.setListDelimiter(char)`, `AbstractConfiguration.setDelimiterParsingDisabled(boolean)`

### getConfiguration

    public Configuration getConfiguration(int index)

  Return the configuration at the specified index.

  Parameters:
    `index` - The index of the configuration to retrieve
  Returns:
    the configuration at this index

### getInMemoryConfiguration

    public Configuration getInMemoryConfiguration()

  Returns the "in memory configuration". In this configuration changes are stored.

  Returns:
    the in memory configuration

### clone

    public Object clone()

  Returns a copy of this object. This implementation will create a deep clone, i.e. all configurations contained in this composite will also be cloned. This only works if all contained configurations support cloning; otherwise a runtime exception will be thrown. Registered event handlers won't get cloned.

  Overrides:
    `clone` in class `EventSource`
  Returns:
    the copy
  Since:
    1.3

### setDelimiterParsingDisabled

    public void setDelimiterParsingDisabled(boolean delimiterParsingDisabled)

  Sets a flag whether added values for string properties should be checked for the list delimiter. This implementation ensures that the in memory configuration is correctly initialized.

  Overrides:
    `setDelimiterParsingDisabled` in class `AbstractConfiguration`
  Parameters:
    `delimiterParsingDisabled` - the new value of the flag
  Since:
    1.4

### setListDelimiter

    public void setListDelimiter(char listDelimiter)

  Sets the character that is used as list delimiter. This implementation ensures that the in memory configuration is correctly initialized.

  Overrides:
    `setListDelimiter` in class `AbstractConfiguration`
  Parameters:
    `listDelimiter` - the new list delimiter character
  Since:
    1.4

### getSource

    public Configuration getSource(String key)

  Returns the configuration source, in which the specified key is defined. This method will iterate over all existing child configurations and check whether they contain the specified key. The following constellations are possible:
  - If exactly one child configuration contains the key, this configuration is returned as the source configuration. This may be the in memory configuration (this has to be explicitly checked by the calling application).
  - If none of the child configurations contain the key, null is returned.
  - If the key is contained in multiple child configurations or if the key is null, a `IllegalArgumentException` is thrown. In this case the source configuration cannot be determined.

  Parameters:
    `key` - the key to be checked
  Returns:
    the source configuration of this key
  Throws:
    `IllegalArgumentException` - if the source configuration cannot be determined
  Since:
    1.5

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