You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by oh...@apache.org on 2006/04/28 12:14:02 UTC
svn commit: r397839 - in /jakarta/commons/proper/configuration/trunk/xdocs:
changes.xml howto_combinedconfiguration.xml
howto_compositeconfiguration.xml user_guide.xml
Author: oheger
Date: Fri Apr 28 03:13:53 2006
New Revision: 397839
URL: http://svn.apache.org/viewcvs?rev=397839&view=rev
Log:
Added a section about CombinedConfiguration to the user's guide; updated documentation for CompositeConfiguration
Added:
jakarta/commons/proper/configuration/trunk/xdocs/howto_combinedconfiguration.xml (with props)
Modified:
jakarta/commons/proper/configuration/trunk/xdocs/changes.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration.xml
jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml
Modified: jakarta/commons/proper/configuration/trunk/xdocs/changes.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/changes.xml?rev=397839&r1=397838&r2=397839&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/changes.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/changes.xml Fri Apr 28 03:13:53 2006
@@ -24,6 +24,10 @@
<release version="1.3-SNAPSHOT" date="in SVN">
<action dev="oheger" type="add">
+ The new class CombinedConfiguration was added as a hierarchical
+ alternative to CompositeConfiguration.
+ </action>
+ <action dev="oheger" type="add">
A new method convertToHierarchical() was added to ConfigurationUtils,
which is able to convert an arbitrary configuration object into a
hierarchical configuration.
Added: jakarta/commons/proper/configuration/trunk/xdocs/howto_combinedconfiguration.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/howto_combinedconfiguration.xml?rev=397839&view=auto
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_combinedconfiguration.xml (added)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howto_combinedconfiguration.xml Fri Apr 28 03:13:53 2006
@@ -0,0 +1,288 @@
+<?xml version="1.0"?>
+<!--
+ Copyright 2006 The Apache Software Foundation
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<document>
+
+ <properties>
+ <title>Combined Configurations</title>
+ <author email="oheger@apache.com">Oliver Heger</author>
+ </properties>
+
+<body>
+ <section name="Combined Configuration">
+ <p>
+ The <code><a href="apidocs/org/apache/commons/configuration/CombinedConfiguration.html">
+ CombinedConfiguration</a></code> class provides an alternative for handling
+ multiple configuration sources. Its API is very similar to the
+ <code>CompositeConfiguration</code> class, which was discussed in the
+ <a href="howto_compositeconfiguration.html#Composite Configuration Details">last
+ section</a>. There are the following differences however:
+ </p>
+ <p>
+ <ul>
+ <li>A <code>CombinedConfiguration</code> is a truely
+ <a href="howto_xml.html#Hierarchical properties">hierarchical
+ configuration</a>. This means that all the enhanced facilities
+ provided by <code>HierarchicalConfiguration</code> (e.g. expression
+ engines) can be used.</li>
+ <li>A <code>CombinedConfiguration</code> is not limited to implementing
+ an override semantics for the properties of the contained configurations.
+ Instead it has the concept of so-called <em>node combiners</em>, 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.</li>
+ <li>Contained configurations can be assigned a name. They can later be
+ accessed by their name.</li>
+ <li>Each contained configuration can have an optional prefix. Its
+ properties are then added under this prefix to the combined
+ configuration.</li>
+ <li>There is no concept of an <em>in memory configuration</em>. Changes
+ to a combined configuration are handled in a different way.</li>
+ </ul>
+ </p>
+
+ <subsection name="How it works">
+ <p>
+ A <code>CombinedConfiguration</code> 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.
+ </p>
+ <p>
+ To achieve this, a <code>CombinedConfiguration</code> 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.
+ </p>
+ </subsection>
+
+ <subsection name="Node combiners">
+ <p>
+ A <em>node combiner</em> is an object of a class that inherits from the
+ abstract <code><a href="apidocs/org/apache/commons/configuration/tree/NodeCombiner.html">NodeCombiner</a></code>
+ class. This class defines an abstract <code>combine()</code> 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
+ <code><a href="apidocs/org/apache/commons/configuration/tree/OverrideCombiner.html">OverrideCombiner</a></code>
+ and <code><a href="apidocs/org/apache/commons/configuration/tree/UnionCombiner.html">UnionCombiner</a></code>,
+ which implement an override and a union semantics respective.
+ </p>
+ <p>
+ 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:
+ </p>
+ <source><![CDATA[
+<configuration>
+ <database>
+ <tables>
+ <table>
+ <name>users</name>
+ <fields>
+ <field>
+ <name>user_id</name>
+ </field>
+ ...
+ </fields>
+ </table>
+ </tables>
+ </database>
+</configuration>
+]]></source>
+ <p>and</p>
+ <source><![CDATA[
+<configuration>
+ <database>
+ <tables>
+ <table>
+ <name>documents</name>
+ <fields>
+ <field>
+ <name>document_id</name>
+ </field>
+ ...
+ </fields>
+ </table>
+ </tables>
+ </database>
+</configuration>
+]]></source>
+ <p>
+ 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:
+ </p>
+ <source><![CDATA[
+<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>
+]]></source>
+ <p>
+ As you can see, the resulting structure contains two <code>table</code>
+ nodes while the nodes <code>database</code> and <code>tables</code> appear
+ only once. For a human being this is quite logic because <code>database</code>
+ and <code>tables</code> 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 <code>tables</code>
+ nodes and the <code>table</code> 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 <code>UnionCombiner</code> when
+ applied on the two example sources would be a bit different:
+ </p>
+ <source><![CDATA[
+<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>
+]]></source>
+ <p>
+ Note that the <code>table</code> 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 <code>table</code> 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 <code>table</code> is a list
+ node and would have acted correspondigly.
+ </p>
+ </subsection>
+
+ <subsection name="Constructing a CombinedConfiguration">
+ <p>
+ To create a <code>CombinedConfiguration</code> 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:
+ </p>
+<source><![CDATA[
+// 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);
+]]></source>
+ <p>
+ Here we also specified a name for one of the configurations, so it can
+ later be accessed by <code>cc.getConfiguration("tab1");</code>. 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
+ </p>
+ </subsection>
+
+ <subsection name="Dealing with changes">
+ <p>
+ There is nothing that prevents you from updating a combined configuration,
+ e.g. by calling methods like <code>addProperty()</code> or
+ <code>removeProperty()</code>. 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.
+ </p>
+ <p>
+ 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).
+ </p>
+ <p>
+ 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
+ <code>OverrideCombiner</code> 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.
+ </p>
+ <p>
+ 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.
+ </p>
+ </subsection>
+ </section>
+</body>
+
+</document>
\ No newline at end of file
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_combinedconfiguration.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_combinedconfiguration.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_combinedconfiguration.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Modified: jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration.xml?rev=397839&r1=397838&r2=397839&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration.xml Fri Apr 28 03:13:53 2006
@@ -1,6 +1,6 @@
<?xml version="1.0"?>
<!--
- Copyright 2004-2005 The Apache Software Foundation
+ Copyright 2004-2006 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -25,6 +25,23 @@
<body>
<section name="Composite Configuration Details">
+ <p>
+ There are many use cases when you want to collect the properties
+ of several configuration sources and access them like a single
+ configuration object. One way to do that is using the
+ <code><a href="apidocs/org/apache/commons/configuration/CompositeConfiguration.html">
+ CompositeConfiguration</a></code> class.
+ </p>
+ <p>
+ A <code>CompositeConfiguration</code> object contains a list of
+ other configuration objects. When properties are accessed from a
+ composite configuration the object takes the passed in property key
+ and iterates over the list of the contained configurations. As soon
+ as a value is found for the key it is returned. This means that a
+ <code>CompositeConfiguration</code> implements a kind of override
+ semantics, i.e. the properties of configurations that were added
+ first hide the property values of configurations added later.
+ </p>
<p>
We will discuss how you can establish a "default" choice for your
Composite Configuration as well as save changes made to your
Modified: jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml?rev=397839&r1=397838&r2=397839&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml Fri Apr 28 03:13:53 2006
@@ -78,6 +78,13 @@
<li><a href="howto_compositeconfiguration.html#Setting Up Defaults">Setting Up Defaults</a></li>
<li><a href="howto_compositeconfiguration.html#Saving Changes">Saving Changes</a></li>
</ul>
+ <li><a href="howto_combinedconfiguration.html#Combined Configuration">Combined Configuration</a></li>
+ <ul>
+ <li><a href="howto_combinedconfiguration.html#How it works">How it works</a></li>
+ <li><a href="howto_combinedconfiguration.html#Node combiners">Node combiners</a></li>
+ <li><a href="howto_combinedconfiguration.html#Constructing a CombinedConfiguration">Constructing a CombinedConfiguration</a></li>
+ <li><a href="howto_combinedconfiguration.html#Dealing with changes">Dealing with changes</a></li>
+ </ul>
<li><a href="howto_beans.html#Declaring and Creating Beans">Declaring and Creating Beans</a></li>
<ul>
<li><a href="howto_beans.html#Basic Concepts">Basic Concepts</a></li>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org