Package org.apache.commons.configuration2

# Class CompositeConfiguration

java.lang.Object
org.apache.commons.configuration2.event.BaseEventSource
org.apache.commons.configuration2.AbstractConfiguration
org.apache.commons.configuration2.CompositeConfiguration

All Implemented Interfaces:
  `Cloneable`, `Configuration`, `EventSource`, `ImmutableConfiguration`, `SynchronizerSupport`

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.

This configuration class uses a `Synchronizer` to control concurrent access. While all methods for reading and writing configuration properties make use of this `Synchronizer` per default, the methods for managing the list of child configurations and the in-memory configuration (`addConfiguration(), getNumberOfConfigurations(), removeConfiguration(), getConfiguration(), getInMemoryConfiguration()`) are guarded, too. Because most methods for accessing configuration data delegate to the list of child configurations, the thread-safety of a `CompositeConfiguration` object also depends on the `Synchronizer` objects used by these children.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `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

  Modifier and Type
  Method
  Description
  `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.
  `void`
  `addConfigurationFirst(Configuration config)`
  Add a configuration to the start of the list of child configurations.
  `void`
  `addConfigurationFirst(Configuration config, boolean asInMemory)`
  Adds a child configuration to the start of the collection and optionally makes it the in-memory configuration.
  `protected void`
  `addPropertyDirect(String key, Object token)`
  Add this property to the in-memory Configuration.
  `protected void`
  `clearInternal()`
  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.
  `protected boolean`
  `containsKeyInternal(String key)`
  Actually checks whether the specified key is contained in this configuration.
  `protected boolean`
  `containsValueInternal(Object value)`
  Tests whether this configuration contains one or more matches to this value.
  `Configuration`
  `getConfiguration(int index)`
  Gets the configuration at the specified index.
  `Configuration`
  `getInMemoryConfiguration()`
  Gets the "in memory configuration".
  `protected Iterator<String>`
  `getKeysInternal()`
  Actually creates an iterator for iterating over the keys in this configuration.
  `protected Iterator<String>`
  `getKeysInternal(String key)`
  Gets an `Iterator` with all property keys starting with the specified prefix.
  `protected Iterator<String>`
  `getKeysInternal(String key, String delimiter)`
  Gets an `Iterator` with all property keys starting with the specified prefix and specified delimiter.
  `List<Object>`
  `getList(String key, List<?> defaultValue)`
  Gets a List of strings associated with the given configuration key.
  `int`
  `getNumberOfConfigurations()`
  Gets the number of configurations.
  `protected Object`
  `getPropertyInternal(String key)`
  Read property from underlying composite
  `Configuration`
  `getSource(String key)`
  Gets the configuration source, in which the specified key is defined.
  `String[]`
  `getStringArray(String key)`
  Gets an array of strings associated with the given configuration key.
  `protected boolean`
  `isEmptyInternal()`
  Actually checks whether this configuration contains data.
  `void`
  `removeConfiguration(Configuration config)`
  Remove a configuration.
  `void`
  `setListDelimiterHandler(ListDelimiterHandler listDelimiterHandler)`
  Sets the `ListDelimiterHandler` to be used by this instance.

  ### Methods inherited from class org.apache.commons.configuration2.AbstractConfiguration

  `addErrorLogListener, addProperty, addPropertyInternal, append, beginRead, beginWrite, clear, clearProperty, cloneInterpolator, contains, containsKey, containsValue, copy, endRead, endWrite, get, get, getArray, getArray, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getCollection, getCollection, getConfigurationDecoder, getConversionHandler, getDouble, getDouble, getDouble, getDuration, getDuration, getEncodedString, getEncodedString, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getKeys, getKeys, getKeys, getList, getList, getList, getListDelimiterHandler, getLogger, getLong, getLong, getLong, getProperties, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getSynchronizer, immutableSubset, initLogger, installInterpolator, interpolate, interpolate, interpolatedConfiguration, isEmpty, isScalarValue, isThrowExceptionOnMissing, lock, setConfigurationDecoder, setConversionHandler, setDefaultLookups, setInterpolator, setLogger, setParentInterpolator, setPrefixLookups, setProperty, setPropertyInternal, setSynchronizer, setThrowExceptionOnMissing, size, sizeInternal, subset, unlock`

  ### Methods inherited from class org.apache.commons.configuration2.event.BaseEventSource

  `addEventListener, clearErrorListeners, clearEventListeners, copyEventListeners, createErrorEvent, createEvent, fireError, fireEvent, getEventListenerRegistrations, getEventListeners, isDetailEvents, removeEventListener, 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.configuration2.ImmutableConfiguration

  `getEnum, getEnum`

- ## Constructor Details

  - ### CompositeConfiguration

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

  - ### 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)
    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(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 Details

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

  - ### addConfigurationFirst

    public void addConfigurationFirst(Configuration config)
    Add a configuration to the start of the list of child configurations.
    Parameters:
      `config` - the configuration to add
    Since:
      2.3

  - ### addConfigurationFirst

    public void addConfigurationFirst(Configuration config, boolean asInMemory)
    Adds a child configuration to the start of the collection 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:
      2.3

  - ### addPropertyDirect

    protected void addPropertyDirect(String key, Object token)
    Add this property to the in-memory Configuration.
    Specified by:
      `addPropertyDirect` in class `AbstractConfiguration`
    Parameters:
      `key` - The Key to add the property to.
      `token` - The Value to add.

  - ### clearInternal

    protected void clearInternal()
    Removes all child configurations and reinitializes the in-memory configuration. Attention: A new in-memory configuration is created; the old one is lost.
    Overrides:
      `clearInternal` in class `AbstractConfiguration`

  - ### 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 must be overridden in sub classes.
    Specified by:
      `clearPropertyDirect` in class `AbstractConfiguration`
    Parameters:
      `key` - the key to be removed

  - ### 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 `BaseEventSource`
    Returns:
      the copy
    Since:
      1.3

  - ### containsKeyInternal

    protected boolean containsKeyInternal(String key)
    Description copied from class: `AbstractConfiguration`
    Actually checks whether the specified key is contained in this configuration. This method is called by `containsKey()`. It has to be defined by concrete subclasses.
    Specified by:
      `containsKeyInternal` in class `AbstractConfiguration`
    Parameters:
      `key` - the key in question
    Returns:
      true if this key is contained in this configuration, false otherwise

  - ### containsValueInternal

    protected boolean containsValueInternal(Object value)
    Tests whether this configuration contains one or more matches to this value. This operation stops at first match but may be more expensive than the containsKey method.
    Specified by:
      `containsValueInternal` in class `AbstractConfiguration`
    Parameters:
      `value` - the value in question
    Returns:
      `true` if and only if some key maps to the `value` argument in this configuration as determined by the `equals` method; `false` otherwise.
    Since:
      2.11.0

  - ### getConfiguration

    public Configuration getConfiguration(int index)
    Gets 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()
    Gets the "in memory configuration". In this configuration changes are stored.
    Returns:
      the in memory configuration

  - ### getKeysInternal

    protected Iterator<String> getKeysInternal()
    Description copied from class: `AbstractConfiguration`
    Actually creates an iterator for iterating over the keys in this configuration. This method is called by `getKeys()`, it has to be defined by concrete subclasses.
    Specified by:
      `getKeysInternal` in class `AbstractConfiguration`
    Returns:
      an `Iterator` with all property keys in this configuration

  - ### getKeysInternal

    protected Iterator<String> getKeysInternal(String key)
    Description copied from class: `AbstractConfiguration`
    Gets an `Iterator` with all property keys starting with the specified prefix. This method is called by `AbstractConfiguration.getKeys(String)`. It is fully implemented by delegating to `getKeysInternal()` and returning a special iterator which filters for the passed in prefix. Subclasses can override it if they can provide a more efficient way to iterate over specific keys only.
    Overrides:
      `getKeysInternal` in class `AbstractConfiguration`
    Parameters:
      `key` - the prefix for the keys to be taken into account
    Returns:
      an `Iterator` returning the filtered keys

  - ### getKeysInternal

    protected Iterator<String> getKeysInternal(String key, String delimiter)
    Description copied from class: `AbstractConfiguration`
    Gets an `Iterator` with all property keys starting with the specified prefix and specified delimiter. This method is called by `AbstractConfiguration.getKeys(String)`. It is fully implemented by delegating to `getKeysInternal()` and returning a special iterator which filters for the passed in prefix. Subclasses can override it if they can provide a more efficient way to iterate over specific keys only.
    Overrides:
      `getKeysInternal` in class `AbstractConfiguration`
    Parameters:
      `key` - the prefix for the keys to be taken into account
      `delimiter` - the prefix delimiter
    Returns:
      an `Iterator` returning the filtered keys

  - ### getList

    public List<Object> getList(String key, List<?> defaultValue)
    Description copied from interface: `ImmutableConfiguration`
    Gets 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 `ImmutableConfiguration`
    Overrides:
      `getList` in class `AbstractConfiguration`
    Parameters:
      `key` - The configuration key.
      `defaultValue` - The default value.
    Returns:
      The associated List of strings.
    See Also:
      - `ImmutableConfiguration.getList(Class, String, List)`

  - ### getNumberOfConfigurations

    public int getNumberOfConfigurations()
    Gets the number of configurations.
    Returns:
      the number of configuration

  - ### getPropertyInternal

    protected Object getPropertyInternal(String key)
    Read property from underlying composite
    Specified by:
      `getPropertyInternal` in class `AbstractConfiguration`
    Parameters:
      `key` - key to use for mapping
    Returns:
      object associated with the given configuration key.

  - ### getSource

    public Configuration getSource(String key)
    Gets 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

  - ### getStringArray

    public String[] getStringArray(String key)
    Description copied from class: `AbstractConfiguration`
    Gets 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. When 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 the association `ListDelimiterHandler` is consulted to find out whether the string can be split into multiple values.
    Specified by:
      `getStringArray` in interface `ImmutableConfiguration`
    Overrides:
      `getStringArray` in class `AbstractConfiguration`
    Parameters:
      `key` - The configuration key.
    Returns:
      The associated string array if key is found.
    See Also:
      - `AbstractConfiguration.setListDelimiterHandler(ListDelimiterHandler)`

  - ### isEmptyInternal

    protected boolean isEmptyInternal()
    Description copied from class: `AbstractConfiguration`
    Actually checks whether this configuration contains data. This method is called by `isEmpty()`. It has to be defined by concrete subclasses.
    Specified by:
      `isEmptyInternal` in class `AbstractConfiguration`
    Returns:
      true if this configuration contains no data, false otherwise

  - ### removeConfiguration

    public void removeConfiguration(Configuration config)
    Remove a configuration. The in memory configuration cannot be removed.
    Parameters:
      `config` - The configuration to remove

  - ### setListDelimiterHandler

    public void setListDelimiterHandler(ListDelimiterHandler listDelimiterHandler)

    Sets the `ListDelimiterHandler` to be used by this instance. This object is invoked every time when dealing with string properties that may contain a list delimiter and thus have to be split to multiple values. Per default, a `ListDelimiterHandler` implementation is set which does not support list splitting. This can be changed for instance by setting a `DefaultListDelimiterHandler` object.

    Warning: Be careful when changing the list delimiter handler when the configuration has already been loaded/populated. List handling is typically applied already when properties are added to the configuration. If later another handler is set which processes lists differently, results may be unexpected; some operations may even cause exceptions.

    This implementation ensures that the in memory configuration is correctly initialized.
    Overrides:
      `setListDelimiterHandler` in class `AbstractConfiguration`
    Parameters:
      `listDelimiterHandler` - the `ListDelimiterHandler` to be used (must not be null)