|
Combined ConfigurationThe 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:
How it worksA 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. Node combinersA 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 three concrete implementations OverrideCombiner, MergeCombiner and UnionCombiner, which implement an override, merge, and union semantics respectively. 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. The examples the follow are provided to further illustrate the differences between the combiners that are delivered with Commons Configuration. The first two files are the files that will be combined.
The first listing shows the result of using the OverrideCombiner.
The next file is the the result of using the UnionCombiner
Finally, the last file is the result of using the MergeCombiner
Constructing a CombinedConfigurationTo 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 Dealing with changesThere 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. |