The
CombinedConfiguration
class provides an alternative for handling
multiple configuration sources. Its API is very similar to the
CompositeConfiguration
class, which was discussed in the
last
section. There are the following differences however:
CombinedConfiguration
is a truely
hierarchical
configuration. This means that all the enhanced facilities
provided by HierarchicalConfiguration
(e.g. expression
engines) can be used.CombinedConfiguration
is not limited to implementing
an override semantics for the properties of the contained configurations.
Instead it has the concept of so-called node combiners, which
know how properties of multiple configuration sources can be combined.
Node combiners are discussed later in detail. For instance, there is a
node combiner implementation available that constructs a union of the
contained configurations.
A CombinedConfiguration
provides a logic view on the
properties of the configurations it contains. This view is determined
by the associated node combiner object. Because of that it must be
re-constructed whenever one of these contained configurations is
changed.
To achieve this, a CombinedConfiguration
object registers
itself as an event listener at the configurations that are added to it.
It will then be notified for every modification that occurs. If such a
notification is received, the internally managed view is invalidated.
When a property of the combined configuration is to be accessed, the view
is checked whether it is valid. If this is the case, the property's value
can be directly fetched. Otherwise the associated node combiner is asked
to re-construct the view.
A node combiner is an object of a class that inherits from the
abstract NodeCombiner
class. This class defines an abstract combine()
method, which
takes the root nodes of two hierarchical configurations and returns the
root node of the combined node structure. It is up to a concrete
implementation how this combined structure will look like. Commons
Configuration ships with the two concrete implementations
OverrideCombiner
and UnionCombiner
,
which implement an override and a union semantics respective.
Constructing a combination of multiple node hierarchies is not a trivial task. The available implementations descend the passed in node hierarchies in a recursive manner to decide, which nodes have to be copied into the resulting structure. Under certain circumstances two nodes of the source structures can be combined into a single result node, but unfortunately this process cannot be fully automated, but sometimes needs some hints from the developer. As an example consider the following XML configuration sources:
<configuration> <database> <tables> <table> <name>users</name> <fields> <field> <name>user_id</name> </field> ... </fields> </table> </tables> </database> </configuration>
and
<configuration> <database> <tables> <table> <name>documents</name> <fields> <field> <name>document_id</name> </field> ... </fields> </table> </tables> </database> </configuration>
These two configuration sources define database tables. Each source defines one table. When constructing a union for these sources the result should look as follows:
<configuration> <database> <tables> <table> <name>users</name> <fields> <field> <name>user_id</name> </field> ... </fields> </table> <table> <name>documents</name> <fields> <field> <name>document_id</name> </field> ... </fields> </table> </tables> </database> </configuration>
As you can see, the resulting structure contains two table
nodes while the nodes database
and tables
appear
only once. For a human being this is quite logic because database
and tables
define the overall structure of the configuration
data, and there can be multiple tables. A node combiner however does not
know anything about structure nodes, list nodes, or whatever. From its point of
view there is no detectable difference between the tables
nodes and the table
nodes in the source structures: both
appear once in each source file and have no values. So without any
assistance the result constructed by the UnionCombiner
when
applied on the two example sources would be a bit different:
<configuration> <database> <tables> <table> <name>users</name> <fields> <field> <name>user_id</name> </field> ... </fields> <name>documents</name> <fields> <field> <name>document_id</name> </field> ... </fields> </table> </tables> </database> </configuration>
Note that the table
node would be considered a structure
node, too, and would not be duplicated. This is probably not what was
desired. To deal with such situations it is possible to tell the node
combiner that certain nodes are list nodes and thus should not be
combined. So in this concrete example the table
node should
be declared as a list node, then we would get the expected result. We will
see below how this is done. Note that this explicit declaration of a list
node is necessary only in situations where there is ambiguity. If in one
of our example configuration sources multiple tables had been defined, the
node combiner would have concluded itself that table
is a list
node and would have acted correspondigly.
To create a CombinedConfiguration
object you specify the node
combiner to use and then add an arbitrary number of configurations. We will
show how to construct a union configuration from the two example sources
introduced earlier:
// Load the source configurations XMLConfiguration conf1 = new XMLConfiguration("table1.xml"); XMLConfiguration conf2 = new XMLConfiguration("table2.xml"); // Create and initialize the node combiner NodeCombiner combiner = new UnionCombiner(); combiner.addListNode("table"); // mark table as list node // this is needed only if there are ambiguities // Construct the combined configuration CombinedConfiguration cc = new CombinedConfiguration(combiner); cc.addConfiguration(conf1, "tab1"); cc.addConfiguration(conf2);
Here we also specified a name for one of the configurations, so it can
later be accessed by cc.getConfiguration("tab1");
. Access by
index is also supported. After that the properties in the combined
configuration can be accessed as if it were a normal hierarchical
configuration
There is nothing that prevents you from updating a combined configuration,
e.g. by calling methods like addProperty()
or
removeProperty()
. The problem is that depending on the used
node combiner it might no be clear, which of the contained configurations
will be modified or whether one is modified at all.
Typical node combiners work by copying parts of the node structures of the source configurations into the target structure and linking them togehter using special link nodes. So updates of the combined node structure will either effect nodes from one of the contained configuration (then the changes are directly visible in this configuration) or one of the link nodes (then they cannot really be saved).
It is also possible that a change is done at the combined node structure,
which is not compatible with the current node combiner. Imagine that an
OverrideCombiner
is used and that a
property should be removed. This property will then be removed from one
of the contained configurations. Now it may happen that this removed
property had hidden property values of other contained configurations.
Their values won't become visible automatically, but only after the
combined view was re-constructed.
Because of that it is recommended that changes are not done at the combined configuration, but only at contained configurations. This way the correct configuration to be updated can unambigously be identified. Obtaining the configuration to be updated from the combined configuration is easy when it was given a name.