org.apache.commons.configuration
Class CombinedConfiguration

java.lang.Object
  extended by org.apache.commons.configuration.event.EventSource
      extended by org.apache.commons.configuration.AbstractConfiguration
          extended by org.apache.commons.configuration.HierarchicalConfiguration
              extended by 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 truly 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 at 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. Note that, depending on the used NodeCombiner, this may be a complex operation.

Because of the way a CombinedConfiguration is working it has more or less view character: it provides a logic view on the configurations it contains. In this constellation not all methods defined for hierarchical configurations - especially methods that update the stored properties - can be implemented in a consistent manner. Using such methods (like addProperty(), or clearProperty() on a CombinedConfiguration is not strictly forbidden, however, depending on the current NodeCombiner and the involved properties, the results may be different than expected. Some examples may illustrate this:

Because of such problems it is recommended to perform updates only on the managed child 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 569412 2007-08-24 15:07:53Z oheger $
Author:
Commons Configuration team
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class org.apache.commons.configuration.HierarchicalConfiguration
HierarchicalConfiguration.BuilderVisitor, 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, EVENT_SUBNODE_CHANGED
 
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
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.
 Object getProperty(String key)
          Returns the value of the specified property.
 ConfigurationNode getRootNode()
          Returns the configuration root node of this combined configuration.
 Configuration getSource(String key)
          Returns the configuration source, in which the specified key is defined.
 void invalidate()
          Invalidates this combined configuration.
 boolean isForceReloadCheck()
          Returns a flag whether an enhanced reload check must be performed.
 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 setForceReloadCheck(boolean forceReloadCheck)
          Sets the force reload check flag.
 void setNodeCombiner(NodeCombiner nodeCombiner)
          Sets the node combiner.
 
Methods inherited from class org.apache.commons.configuration.HierarchicalConfiguration
addNodes, addPropertyDirect, clearNode, clearNode, clearProperty, clearReferences, clearTree, configurationAt, configurationAt, configurationsAt, containsKey, createAddPath, createNode, createSubnodeConfiguration, createSubnodeConfiguration, fetchAddNode, fetchNodeList, findLastPathNode, findPropertyNodes, getDefaultExpressionEngine, getExpressionEngine, getKeys, getKeys, getMaxIndex, getRoot, interpolatedConfiguration, isEmpty, nodeDefined, nodeDefined, removeNode, removeNode, setDefaultExpressionEngine, setExpressionEngine, setProperty, setRoot, setRootNode, subnodeConfigurationChanged, subset
 
Methods inherited from class org.apache.commons.configuration.AbstractConfiguration
addErrorLogListener, addProperty, append, clearPropertyDirect, 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, getList, getListDelimiter, getLogger, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, getSubstitutor, interpolate, interpolate, interpolateHelper, isDelimiterParsingDisabled, isThrowExceptionOnMissing, resolveContainerStore, setDefaultListDelimiter, setDelimiter, setDelimiterParsingDisabled, setListDelimiter, setLogger, setThrowExceptionOnMissing
 
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
 

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

isForceReloadCheck

public boolean isForceReloadCheck()
Returns a flag whether an enhanced reload check must be performed.

Returns:
the force reload check flag
Since:
1.4

setForceReloadCheck

public void setForceReloadCheck(boolean forceReloadCheck)
Sets the force reload check flag. If this flag is set, each property access on this configuration will cause a reload check on the contained configurations. This is a workaround for a problem with some reload implementations that only check if a reload is required when they are triggered. Per default this mode is disabled. If the force reload check flag is set to true, accessing properties will be less performant, but reloads on contained configurations will be detected.

Parameters:
forceReloadCheck - the value of the flag
Since:
1.4

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

getProperty

public Object getProperty(String key)
Returns the value of the specified property. This implementation evaluates the force reload check flag. If it is set, all contained configurations will be triggered before the value of the requested property is retrieved.

Specified by:
getProperty in interface Configuration
Overrides:
getProperty in class HierarchicalConfiguration
Parameters:
key - the key of the desired property
Returns:
the value of this property
Since:
1.4

getSource

public Configuration getSource(String key)
Returns the configuration source, in which the specified key is defined. This method will determine the configuration node that is identified by the given key. The following constellations are possible:

Parameters:
key - the key of a configuration property
Returns:
the configuration, to which this property belongs or null if the key cannot be resolved
Throws:
IllegalArgumentException - if the key maps to multiple properties and the source cannot be determined, or if the key is null
Since:
1.5


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