org.apache.commons.configuration
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
object can be set. This makes it possible to specify different algorithms for
the combination process.
NodeCombiner
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
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.
OverrideCombiner
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 484692 2006-12-08 18:30:15Z oheger $
Nested Class Summary | |
---|---|
static class | CombinedConfiguration.ConfigData
An internal helper class for storing information about contained
configurations. |
Field Summary | |
---|---|
static DefaultExpressionEngine | AT_ENGINE Constant for the expression engine for parsing the at path. |
ConfigurationNode | combinedRoot Stores the combined root node. |
List | configurations Stores a list with the contained configurations. |
static NodeCombiner | DEFAULT_COMBINER Constant for the default node combiner. |
static int | EVENT_COMBINED_INVALIDATE
Constant for the invalidate event that is fired when the internal node
structure becomes invalid. |
boolean | forceReloadCheck A flag whether an enhanced reload check is to be performed. |
Map | namedConfigurations Stores a map with the named configurations. |
NodeCombiner | nodeCombiner Stores the combiner. |
static String | PROP_RELOAD_CHECK Constant for the name of the property used for the reload check. |
static long | serialVersionUID
The serial version ID. |
Constructor Summary | |
---|---|
CombinedConfiguration(NodeCombiner comb)
Creates a new instance of CombinedConfiguration and
initializes the combiner to be used.
| |
CombinedConfiguration()
Creates a new instance of CombinedConfiguration that uses
a union combiner.
|
Method Summary | |
---|---|
void | addConfiguration(AbstractConfiguration config, String name, String at)
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)
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. |
ConfigurationNode | constructCombinedNode()
Creates the root node of this combined configuration.
|
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. |
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. |
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
that uses
a union combiner.
See Also: UnionCombiner
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)
Parameters: config the configuration to add (must not be null) name the name of this configuration (can be null)
Parameters: config the configuration to add (must not be null)
Returns: the copied object
Parameters: event the update event
Returns: the combined root node
Parameters: index the index
Returns: the configuration at this index
Parameters: name the name of the configuration
Returns: the configuration with this name
Returns: a set with the names of the contained configurations (never null)
Returns: the node combiner
Returns: the number of contained configurations
Parameters: key the key of the desired property
Returns: the value of this property
Since: 1.4
Returns: the combined root node
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).Returns: the force reload check flag
Since: 1.4
Parameters: config the configuration to be removed
Returns: a flag whether this configuration was found and could be removed
Parameters: name the name of the configuration to be removed
Returns: the removed configuration (null if this configuration was not found)
Parameters: index the index
Returns: the removed configuration
Parameters: forceReloadCheck the value of the flag
Since: 1.4
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