Added: websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_combinedconfiguration.html ============================================================================== --- websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_combinedconfiguration.html (added) +++ websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_combinedconfiguration.html Wed Sep 24 20:29:01 2014 @@ -0,0 +1,1070 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia at 24 September 2014 + | Rendered using Apache Maven Fluido Skin 1.3.0 +--> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> + <head> + <meta charset="iso-8859-1" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="author" content="Oliver Heger" /> + <meta name="Date-Revision-yyyymmdd" content="20140924" /> + <meta http-equiv="Content-Language" content="en" /> + <title>Commons Configuration - + Combined Configurations</title> + + <link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css" /> + <link rel="stylesheet" href="../css/site.css" type="text/css" /> + <link rel="stylesheet" href="../css/print.css" media="print" /> + + <script type="text/javascript" src="../js/jquery.min.js"></script> + <script type="text/javascript" src="../js/bootstrap.min.js"></script> + <script type="text/javascript" src="../js/prettify.min.js"></script> + <script type="text/javascript" src="../js/site.js"></script> + + +<link rel="stylesheet" type="text/css" media="all" href="../css/prettify.css"/> +<script src="../js/prettify.js" type="text/javascript"></script> +<script type="text/javascript">window.onload=function() { + prettyPrint(); + }</script> + </head> + + <body class="composite"> + <a href="http://commons.apache.org/"; id="bannerLeft" title="Apache Commons logo"> + <img class="logo-left" src="../images/commons-logo.png" alt="Apache Commons logo"/> + </a> + <a href="../index.html" id="bannerRight"> + <img class="logo-right" src="../images/logo.png" alt="Commons Configuration"/> + </a> + <div class="clear"></div> + + <div class="navbar"> + <div class="navbar-inner"> + <div class="container-fluid"> + <a class="brand" href="http://commons.apache.org/proper/commons-configuration/";>Apache Commons Configuration ™</a> + <ul class="nav"> + + <li id="publishDate">Last Published: 24 September 2014</li> + <li class="divider">|</li> <li id="projectVersion">Version: 1.10</li> + </ul> + <div class="pull-right"> <ul class="nav"> + <li> + <a href="http://www.apachecon.com/"; class="externalLink" title="ApacheCon"> + ApacheCon</a> + </li> + <li> + <a href="http://www.apache.org"; class="externalLink" title="Apache"> + Apache</a> + </li> + <li> + <a href="../../../" title="Commons"> + Commons</a> + </li> + </ul> +</div> + </div> + </div> + </div> + + <div class="container-fluid"> + <table class="layout-table"> + <tr> + <td class="sidebar"> + <div class="well sidebar-nav"> + <ul class="nav nav-list"> + <li class="nav-header">Configuration</li> + <li class="none"> + <a href="../index.html" title="Home"> + Home</a> + </li> + <li class="none"> + <a href="../../../configuration/download_configuration.cgi" title="Download"> + Download</a> + </li> + <li class="none"> + <a href="../changes-report.html" title="Release History"> + Release History</a> + </li> + <li class="none"> + <a href="../userguide/user_guide.html" title="User's Guide"> + User's Guide</a> + </li> + <li class="none"> + <a href="../dependencies.html" title="Runtime Dependencies"> + Runtime Dependencies</a> + </li> + <li class="none"> + <a href="../apidocs/index.html" title="Javadoc"> + Javadoc</a> + </li> + </ul> + <ul class="nav nav-list"> + <li class="nav-header"><i class="icon-cog"></i>Development</li> + <li class="none"> + <a href="../building.html" title="Building"> + Building</a> + </li> + <li class="none"> + <a href="../issue-tracking.html" title="Issue Tracking"> + Issue Tracking</a> + </li> + </ul> + <ul class="nav nav-list"> + <li class="nav-header"><i class="icon-info-sign"></i>Project Documentation</li> + <li class="collapsed"> + <a href="../project-info.html" title="Project Information"> + Project Information</a> + </li> + <li class="collapsed"> + <a href="../project-reports.html" title="Project Reports"> + Project Reports</a> + </li> + </ul> + <ul class="nav nav-list"> + <li class="nav-header">Commons</li> + <li class="none"> + <a href="../../../" title="Home"> + Home</a> + </li> + <li class="none"> + <a href="http://www.apache.org/licenses/"; class="externalLink" title="License"> + License</a> + </li> + <li class="collapsed"> + <a href="../../../components.html" title="Components"> + Components</a> + </li> + <li class="collapsed"> + <a href="../../../sandbox/index.html" title="Sandbox"> + Sandbox</a> + </li> + <li class="collapsed"> + <a href="../../../dormant/index.html" title="Dormant"> + Dormant</a> + </li> + </ul> + <ul class="nav nav-list"> + <li class="nav-header">General Information</li> + <li class="none"> + <a href="../../../volunteering.html" title="Volunteering"> + Volunteering</a> + </li> + <li class="none"> + <a href="../../../patches.html" title="Contributing Patches"> + Contributing Patches</a> + </li> + <li class="none"> + <a href="../../../building.html" title="Building Components"> + Building Components</a> + </li> + <li class="none"> + <a href="../../../releases/index.html" title="Releasing Components"> + Releasing Components</a> + </li> + <li class="none"> + <a href="http://wiki.apache.org/commons/FrontPage"; class="externalLink" title="Wiki"> + Wiki</a> + </li> + </ul> + <ul class="nav nav-list"> + <li class="nav-header">ASF</li> + <li class="none"> + <a href="http://www.apache.org/foundation/how-it-works.html"; class="externalLink" title="How the ASF works"> + How the ASF works</a> + </li> + <li class="none"> + <a href="http://www.apache.org/foundation/getinvolved.html"; class="externalLink" title="Get Involved"> + Get Involved</a> + </li> + <li class="none"> + <a href="http://www.apache.org/dev/"; class="externalLink" title="Developer Resources"> + Developer Resources</a> + </li> + <li class="none"> + <a href="http://www.apache.org/foundation/sponsorship.html"; class="externalLink" title="Sponsorship"> + Sponsorship</a> + </li> + <li class="none"> + <a href="http://www.apache.org/foundation/thanks.html"; class="externalLink" title="Thanks"> + Thanks</a> + </li> + </ul> + </div> + <div id="poweredBy"> + <a href="http://www.apache.org/events/current-event.html"; title="ApacheCon" class="builtBy"> + <img class="builtBy" alt="ApacheCon" src="http://www.apache.org/events/current-event-125x125.png"; /> + </a> + <a href="http://maven.apache.org/"; title="Maven" class="builtBy"> + <img class="builtBy" alt="Maven" src="http://maven.apache.org/images/logos/maven-feather.png"; /> + </a> + </div> + </td> + <td class="content"> + <!-- Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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. --> + + + <div class="section"> +<h2>Combined Configuration<a name="Combined_Configuration"></a></h2> + +<p> + The <tt><a href="../apidocs/org/apache/commons/configuration/CombinedConfiguration.html"> + CombinedConfiguration</a></tt> class provides an alternative for handling + multiple configuration sources. Its API is very similar to the + <tt>CompositeConfiguration</tt> 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> + </p> +<ul> + +<li>A <tt>CombinedConfiguration</tt> is a truely + <a href="howto_xml.html#Hierarchical_properties">hierarchical + configuration</a>. This means that all the enhanced facilities + provided by <tt>HierarchicalConfiguration</tt> (e.g. expression + engines) can be used.</li> + +<li>A <tt>CombinedConfiguration</tt> is not limited to implementing + an override semantics for the properties of the contained configurations. + Instead it has the concept of so-called <i>node combiners</i>, 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 <i>in memory configuration</i>. Changes + to a combined configuration are handled in a different way.</li> + </ul> + + + +<div class="section"> +<h3>How it works<a name="How_it_works"></a></h3> + +<p> + A <tt>CombinedConfiguration</tt> 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 <tt>CombinedConfiguration</tt> 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> + </div> + + +<div class="section"> +<h3>Node combiners<a name="Node_combiners"></a></h3> + +<p> + A <i>node combiner</i> is an object of a class that inherits from the + abstract <tt><a href="../apidocs/org/apache/commons/configuration/tree/NodeCombiner.html">NodeCombiner</a></tt> + class. This class defines an abstract <tt>combine()</tt> 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 + <tt><a href="../apidocs/org/apache/commons/configuration/tree/OverrideCombiner.html">OverrideCombiner</a></tt>, + <tt><a href="../apidocs/org/apache/commons/configuration/tree/MergeCombiner.html">MergeCombiner</a></tt> + and <tt><a href="../apidocs/org/apache/commons/configuration/tree/UnionCombiner.html">UnionCombiner</a></tt>, + which implement an override, merge, and union semantics respectively. + </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> + +<div class="source"> +<pre> +<configuration> + <database> + <tables> + <table> + <name>users</name> + <fields> + <field> + <name>user_id</name> + </field> + ... + </fields> + </table> + </tables> + </database> +</configuration> +</pre></div> + +<p>and</p> + +<div class="source"> +<pre> +<configuration> + <database> + <tables> + <table> + <name>documents</name> + <fields> + <field> + <name>document_id</name> + </field> + ... + </fields> + </table> + </tables> + </database> +</configuration> +</pre></div> + +<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> + +<div class="source"> +<pre> +<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> +</pre></div> + +<p> + As you can see, the resulting structure contains two <tt>table</tt> + nodes while the nodes <tt>database</tt> and <tt>tables</tt> appear + only once. For a human being this is quite logic because <tt>database</tt> + and <tt>tables</tt> 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 <tt>tables</tt> + nodes and the <tt>table</tt> 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 <tt>UnionCombiner</tt> when + applied on the two example sources would be a bit different: + </p> + +<div class="source"> +<pre> +<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> +</pre></div> + +<p> + Note that the <tt>table</tt> 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 <tt>table</tt> 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 <tt>table</tt> is a list + node and would have acted correspondigly. + </p> + +<p> + 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. + </p> + +<table class="bodyTable" border="0"> + +<tr class="a"> + +<th width="50%">testfile1.xml</th> + +<th width="50%">testfile2.xml</th> + </tr> + +<tr class="b"> +<td width="50%"> + +<div class="source"> +<pre><config> + <gui> + <bgcolor>green</bgcolor> + <selcolor>yellow</selcolor> + <level default="2">1</level> + </gui> + <net> + <proxy> + <url>http://www.url1.org</url> + <url>http://www.url2.org</url> + <url>http://www.url3.org</url> + </proxy> + <service> + <url>http://service1.org</url> + </service> + <server> + </server> + </net> + <base> + <services> + <security> + <login> + <user>Admin</user> + <passwd type="secret"/> + </login> + </security> + </services> + </base> + <database> + <tables> + <table id="1"> + <name>documents</name> + <fields> + <field> + <name>docid</name> + <type>long</type> + </field> + <field> + <name>docname</name> + <type>varchar</type> + </field> + <field> + <name>authorID</name> + <type>int</type> + </field> + </fields> + </table> + </tables> + </database> + <Channels> + <Channel id="1" type="half"> + <Name>My Channel</Name> + </Channel> + <Channel id="2"> + <MoreChannelData>more test 2 data</MoreChannelData> + </Channel> + <Channel id="3" type="half"> + <Name>Test Channel</Name> + </Channel> + <Channel id="4"> + <Name>Channel 4</Name> + </Channel> + </Channels> +</config> +</pre></div></td> +<td width="50%"> + +<div class="source"> +<pre><config> + <base> + <services> + <security> + <login> + <user type="default">scotty</user> + <passwd>BeamMeUp</passwd> + </login> + </security> + </services> + </base> + <gui> + <bgcolor>black</bgcolor> + <fgcolor>blue</fgcolor> + <level min="1">4</level> + </gui> + <net> + <server> + <url>http://appsvr1.com</url> + <url>http://appsvr2.com</url> + <url>http://testsvr.com</url> + <url>http://backupsvr.com</url> + </server> + <service> + <url type="2">http://service2.org</url> + <url type="2">http://service3.org</url> + </service> + </net> + <database> + <tables> + <table id="2"> + <name>tasks</name> + <fields> + <field> + <name>taskid</name> + <type>long</type> + </field> + <field> + <name>taskname</name> + <type>varchar</type> + </field> + </fields> + </table> + </tables> + </database> + <Channels> + <Channel id="1"> + <Name>Channel 1</Name> + <ChannelData>test 1 data</ChannelData> + </Channel> + <Channel id="2" type="full"> + <Name>Channel 2</Name> + <ChannelData>test 2 data</ChannelData> + </Channel> + <Channel id="3" type="full"> + <Name>Channel 3</Name> + <ChannelData>test 3 data</ChannelData> + </Channel> + <Channel id="4" type="half"> + <Name>Test Channel 1</Name> + </Channel> + <Channel id="4" type="full"> + <Name>Test Channel 2</Name> + </Channel> + </Channels> +</config> +</pre></div></td></tr></table> + +<p> + The first listing shows the result of using the <tt>OverrideCombiner</tt>. + </p> + +<table border="0" class="bodyTable"> + +<tr class="a"> +<th width="40%">OverrideCombiner Results</th> +<th width="60%">Notes</th></tr> + +<tr class="b"> +<td width="40%"> + +<div class="source"> +<pre><config> + <gui> + <bgcolor>green</bgcolor> + <selcolor>yellow</selcolor> + <level default='2' min='1'>1</level> + <fgcolor>blue</fgcolor> + </gui> + <net> + <proxy> + <url>http://www.url1.org</url> + <url>http://www.url2.org</url> + <url>http://www.url3.org</url> + </proxy> + <service> + <url>http://service1.org</url> + </service> + <server> + <url>http://appsvr1.com</url> + <url>http://appsvr2.com</url> + <url>http://testsvr.com</url> + <url>http://backupsvr.com</url> + </server> + </net> + <base> + <services> + <security> + <login> + <user type='default'>Admin</user> + <passwd type='secret'>BeamMeUp</passwd> + </login> + </security> + </services> + </base> + <database> + <tables> + <table id='1'> + <name>documents</name> + <fields> + <field> + <name>docid</name> + <type>long</type> + </field> + <field> + <name>docname</name> + <type>varchar</type> + </field> + <field> + <name>authorID</name> + <type>int</type> + </field> + </fields> + </table> + </tables> + </database> + <Channels> + <Channel id='1' type='half'> + <Name>My Channel</Name> + </Channel> + <Channel id='2'> + <MoreChannelData>more test 2 data</MoreChannelData> + </Channel> + <Channel id='3' type='half'> + <Name>Test Channel</Name> + </Channel> + </Channels> +</config> +</pre></div></td> +<td width="60%"> + +<p> + The features that are significant in this file are: + </p> +<ul> + +<li>In the gui section each of the child elements only appears once. The level element + merges the attributes from the two files and uses the element value of the first file.</li> + +<li>In the security section the user type attribute was obtained from the second file + while the user value came from the first file. Alternately, the password type was + obtained from the first file while the value came from the second.</li> + +<li>Only the data from table 1 was included.</li> + +<li>Channel 1 in the first file completely overrode Channel 1 in the second file.</li> + +<li>Channel 2 in the first file completely overrode Channel 2 in the second file. While + the attributes were merged in the case of the login elements the type attribute + was not merged in this case.</li> + +<li>Again, only Channel 3 from the first file was included.</li> + </ul> + + +<p> + How the Channel elements ended up may not at first be obvious. The <tt>OverrideCombiner</tt> + simply noticed that the Channels element had three child elements named Channel and + used that to determine that only the contents of the Channels element in the first file + would be used. + </p></td></tr></table> + +<p> + The next file is the the result of using the <tt>UnionCombiner</tt> + </p> + +<table border="0" class="bodyTable"> + +<tr class="a"> + +<th width="40%">UnionCombiner Results</th> + +<th width="60%">Notes</th> + </tr> + +<tr class="b"> +<td width="40%"> + +<div class="source"> +<pre><config> + <gui> + <bgcolor>green</bgcolor> + <selcolor>yellow</selcolor> + <level default='2'>1</level> + <bgcolor>black</bgcolor> + <fgcolor>blue</fgcolor> + <level min='1'>4</level> + </gui> + <net> + <proxy> + <url>http://www.url1.org</url> + <url>http://www.url2.org</url> + <url>http://www.url3.org</url> + </proxy> + <service> + <url>http://service1.org</url> + <url type='2'>http://service2.org</url> + <url type='2'>http://service3.org</url> + </service> + <server></server> + <server> + <url>http://appsvr1.com</url> + <url>http://appsvr2.com</url> + <url>http://testsvr.com</url> + <url>http://backupsvr.com</url> + </server> + </net> + <base> + <services> + <security> + <login> + <user>Admin</user> + <passwd type='secret'></passwd> + <user type='default'>scotty</user> + <passwd>BeamMeUp</passwd> + </login> + </security> + </services> + </base> + <database> + <tables> + <table id='1' id='2'> + <name>documents</name> + <fields> + <field> + <name>docid</name> + <type>long</type> + </field> + <field> + <name>docname</name> + <type>varchar</type> + </field> + <field> + <name>authorID</name> + <type>int</type> + </field> + <field> + <name>taskid</name> + <type>long</type> + </field> + <field> + <name>taskname</name> + <type>varchar</type> + </field> + </fields> + <name>tasks</name> + </table> + </tables> + </database> + <Channels> + <Channel id='1' type='half'> + <Name>My Channel</Name> + </Channel> + <Channel id='2'> + <MoreChannelData>more test 2 data</MoreChannelData> + </Channel> + <Channel id='3' type='half'> + <Name>Test Channel</Name> + </Channel> + <Channel id='1'> + <Name>Channel 1</Name> + <ChannelData>test 1 data</ChannelData> + </Channel> + <Channel id='2' type='full'> + <Name>Channel 2</Name> + <ChannelData>test 2 data</ChannelData> + </Channel> + <Channel id='3' type='full'> + <Name>Channel 3</Name> + <ChannelData>test 3 data</ChannelData> + </Channel> + </Channels> +</config> +</pre></div></td> +<td width="60%"> + +<p> + The feature that is significant in this file is rather obvious. It is just a simple + union of the contents of the two files. + </p> + </td></tr></table> + +<p> + Finally, the last file is the result of using the <tt>MergeCombiner</tt> + </p> + +<table border="0" class="bodyTable"> + +<tr class="a"> + +<th width="40%">MergeCombiner Results</th> + +<th width="60%">Notes</th> + </tr> + +<tr class="b"> +<td width="40%"> + +<div class="source"> +<pre><config> + <gui> + <bgcolor>green</bgcolor> + <selcolor>yellow</selcolor> + <level default='2' min='1'>1</level> + <fgcolor>blue</fgcolor> + </gui> + <net> + <proxy> + <url>http://www.url1.org</url> + <url>http://www.url2.org</url> + <url>http://www.url3.org</url> + </proxy> + <service> + <url>http://service1.org</url> + </service> + <server> + <url>http://appsvr1.com</url> + <url>http://appsvr2.com</url> + <url>http://testsvr.com</url> + <url>http://backupsvr.com</url> + </server> + </net> + <base> + <services> + <security> + <login> + <user type='default'>Admin</user> + <passwd type='secret'></passwd> + </login> + </security> + </services> + </base> + <database> + <tables> + <table id='1'> + <name>documents</name> + <fields> + <field> + <name>docid</name> + <type>long</type> + </field> + <field> + <name>docname</name> + <type>varchar</type> + </field> + <field> + <name>authorID</name> + <type>int</type> + </field> + </fields> + </table> + <table id='2'> + <name>tasks</name> + <fields> + <field> + <name>taskid</name> + <type>long</type> + </field> + <field> + <name>taskname</name> + <type>varchar</type> + </field> + </fields> + </table> + </tables> + </database> + <Channels> + <Channel id='1' type='half'> + <Name>My Channel</Name> + <ChannelData>test 1 data</ChannelData> + </Channel> + <Channel id='2' type='full'> + <MoreChannelData>more test 2 data</MoreChannelData> + <Name>Channel 2</Name> + <ChannelData>test 2 data</ChannelData> + </Channel> + <Channel id='3' type='half'> + <Name>Test Channel</Name> + </Channel> + <Channel id='3' type='full'> + <Name>Channel 3</Name> + <ChannelData>test 3 data</ChannelData> + </Channel> + </Channels> +</config> +</pre></div></td> +<td width="60%"> + +<p> + The features that are significant in this file are: + </p> +<ul> + +<li>In the gui section the elements were merged.</li> + +<li>In the net section the elements were merged, with the exception of the urls.</li> + +<li>In the security section the user and password were merged. Notice that the + empty value for the password from the first file overrode the password in the + second file.</li> + +<li>Both table elements appear</li> + +<li>Channel 1 and Channel 2 were merged</li> + +<li>Both Channel 3 elements appear as they were determined to not be the same.</li> + </ul> + + +<p> + When merging elements attributes play a critical role. If an element has an attribute that + appears in both sources, the value of that attribute must be the same for the elements to be + merged. + </p> + +<p> + Merging is only allowed between a single node in each of the files, so if an element + in the first file matches more than one element in the second file no merging will take + place and the element from the first file (and its contents) are included and the elements + in the second file are not. If the element is marked as a list node then the elements from + the second file will also be included. + </p></td></tr></table> + </div> + + +<div class="section"> +<h3>Constructing a CombinedConfiguration<a name="Constructing_a_CombinedConfiguration"></a></h3> + +<p> + To create a <tt>CombinedConfiguration</tt> 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> + +<div class="source"> +<pre> +// 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); +</pre></div> + +<p> + Here we also specified a name for one of the configurations, so it can + later be accessed by <tt>cc.getConfiguration("tab1");</tt>. 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> + </div> + + +<div class="section"> +<h3>Dealing with changes<a name="Dealing_with_changes"></a></h3> + +<p> + There is nothing that prevents you from updating a combined configuration, + e.g. by calling methods like <tt>addProperty()</tt> or + <tt>removeProperty()</tt>. 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 + <tt>OverrideCombiner</tt> 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> + </div> + </div> + + + + </td> + </tr> + </table> + </div> + + <div class="footer"> + <p>Copyright © 2001-2014 + <a href="http://www.apache.org/";>The Apache Software Foundation</a>. + All Rights Reserved.</p> + +<div class="center">Apache Commons, Apache Commons Configuration, Apache, the Apache feather logo, and the Apache Commons project logos are trademarks of The Apache Software Foundation. + All other marks mentioned may be trademarks or registered trademarks of their respective owners.</div> + </div> + </body> + +</html>
Added: websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_compositeconfiguration.html ============================================================================== --- websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_compositeconfiguration.html (added) +++ websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_compositeconfiguration.html Wed Sep 24 20:29:01 2014 @@ -0,0 +1,327 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia at 24 September 2014 + | Rendered using Apache Maven Fluido Skin 1.3.0 +--> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> + <head> + <meta charset="iso-8859-1" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="author" content="Eric Pugh" /> + <meta name="Date-Revision-yyyymmdd" content="20140924" /> + <meta http-equiv="Content-Language" content="en" /> + <title>Commons Configuration - + Composite Configuration Details</title> + + <link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css" /> + <link rel="stylesheet" href="../css/site.css" type="text/css" /> + <link rel="stylesheet" href="../css/print.css" media="print" /> + + <script type="text/javascript" src="../js/jquery.min.js"></script> + <script type="text/javascript" src="../js/bootstrap.min.js"></script> + <script type="text/javascript" src="../js/prettify.min.js"></script> + <script type="text/javascript" src="../js/site.js"></script> + + +<link rel="stylesheet" type="text/css" media="all" href="../css/prettify.css"/> +<script src="../js/prettify.js" type="text/javascript"></script> +<script type="text/javascript">window.onload=function() { + prettyPrint(); + }</script> + </head> + + <body class="composite"> + <a href="http://commons.apache.org/"; id="bannerLeft" title="Apache Commons logo"> + <img class="logo-left" src="../images/commons-logo.png" alt="Apache Commons logo"/> + </a> + <a href="../index.html" id="bannerRight"> + <img class="logo-right" src="../images/logo.png" alt="Commons Configuration"/> + </a> + <div class="clear"></div> + + <div class="navbar"> + <div class="navbar-inner"> + <div class="container-fluid"> + <a class="brand" href="http://commons.apache.org/proper/commons-configuration/";>Apache Commons Configuration ™</a> + <ul class="nav"> + + <li id="publishDate">Last Published: 24 September 2014</li> + <li class="divider">|</li> <li id="projectVersion">Version: 1.10</li> + </ul> + <div class="pull-right"> <ul class="nav"> + <li> + <a href="http://www.apachecon.com/"; class="externalLink" title="ApacheCon"> + ApacheCon</a> + </li> + <li> + <a href="http://www.apache.org"; class="externalLink" title="Apache"> + Apache</a> + </li> + <li> + <a href="../../../" title="Commons"> + Commons</a> + </li> + </ul> +</div> + </div> + </div> + </div> + + <div class="container-fluid"> + <table class="layout-table"> + <tr> + <td class="sidebar"> + <div class="well sidebar-nav"> + <ul class="nav nav-list"> + <li class="nav-header">Configuration</li> + <li class="none"> + <a href="../index.html" title="Home"> + Home</a> + </li> + <li class="none"> + <a href="../../../configuration/download_configuration.cgi" title="Download"> + Download</a> + </li> + <li class="none"> + <a href="../changes-report.html" title="Release History"> + Release History</a> + </li> + <li class="none"> + <a href="../userguide/user_guide.html" title="User's Guide"> + User's Guide</a> + </li> + <li class="none"> + <a href="../dependencies.html" title="Runtime Dependencies"> + Runtime Dependencies</a> + </li> + <li class="none"> + <a href="../apidocs/index.html" title="Javadoc"> + Javadoc</a> + </li> + </ul> + <ul class="nav nav-list"> + <li class="nav-header"><i class="icon-cog"></i>Development</li> + <li class="none"> + <a href="../building.html" title="Building"> + Building</a> + </li> + <li class="none"> + <a href="../issue-tracking.html" title="Issue Tracking"> + Issue Tracking</a> + </li> + </ul> + <ul class="nav nav-list"> + <li class="nav-header"><i class="icon-info-sign"></i>Project Documentation</li> + <li class="collapsed"> + <a href="../project-info.html" title="Project Information"> + Project Information</a> + </li> + <li class="collapsed"> + <a href="../project-reports.html" title="Project Reports"> + Project Reports</a> + </li> + </ul> + <ul class="nav nav-list"> + <li class="nav-header">Commons</li> + <li class="none"> + <a href="../../../" title="Home"> + Home</a> + </li> + <li class="none"> + <a href="http://www.apache.org/licenses/"; class="externalLink" title="License"> + License</a> + </li> + <li class="collapsed"> + <a href="../../../components.html" title="Components"> + Components</a> + </li> + <li class="collapsed"> + <a href="../../../sandbox/index.html" title="Sandbox"> + Sandbox</a> + </li> + <li class="collapsed"> + <a href="../../../dormant/index.html" title="Dormant"> + Dormant</a> + </li> + </ul> + <ul class="nav nav-list"> + <li class="nav-header">General Information</li> + <li class="none"> + <a href="../../../volunteering.html" title="Volunteering"> + Volunteering</a> + </li> + <li class="none"> + <a href="../../../patches.html" title="Contributing Patches"> + Contributing Patches</a> + </li> + <li class="none"> + <a href="../../../building.html" title="Building Components"> + Building Components</a> + </li> + <li class="none"> + <a href="../../../releases/index.html" title="Releasing Components"> + Releasing Components</a> + </li> + <li class="none"> + <a href="http://wiki.apache.org/commons/FrontPage"; class="externalLink" title="Wiki"> + Wiki</a> + </li> + </ul> + <ul class="nav nav-list"> + <li class="nav-header">ASF</li> + <li class="none"> + <a href="http://www.apache.org/foundation/how-it-works.html"; class="externalLink" title="How the ASF works"> + How the ASF works</a> + </li> + <li class="none"> + <a href="http://www.apache.org/foundation/getinvolved.html"; class="externalLink" title="Get Involved"> + Get Involved</a> + </li> + <li class="none"> + <a href="http://www.apache.org/dev/"; class="externalLink" title="Developer Resources"> + Developer Resources</a> + </li> + <li class="none"> + <a href="http://www.apache.org/foundation/sponsorship.html"; class="externalLink" title="Sponsorship"> + Sponsorship</a> + </li> + <li class="none"> + <a href="http://www.apache.org/foundation/thanks.html"; class="externalLink" title="Thanks"> + Thanks</a> + </li> + </ul> + </div> + <div id="poweredBy"> + <a href="http://www.apache.org/events/current-event.html"; title="ApacheCon" class="builtBy"> + <img class="builtBy" alt="ApacheCon" src="http://www.apache.org/events/current-event-125x125.png"; /> + </a> + <a href="http://maven.apache.org/"; title="Maven" class="builtBy"> + <img class="builtBy" alt="Maven" src="http://maven.apache.org/images/logos/maven-feather.png"; /> + </a> + </div> + </td> + <td class="content"> + <!-- Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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. --> + + + + <div class="section"> +<h2>Composite Configuration Details<a name="Composite_Configuration_Details"></a></h2> + +<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 + <tt><a href="../apidocs/org/apache/commons/configuration/CompositeConfiguration.html"> + CompositeConfiguration</a></tt> class. + </p> + +<p> + A <tt>CompositeConfiguration</tt> 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 + <tt>CompositeConfiguration</tt> 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 + Composite Configuration. + </p> + +<div class="section"> +<h3>Setting Up Defaults<a name="Setting_Up_Defaults"></a></h3> + +<p> + Defaults are very simple. You can just add them as your last configuration object, + either through the ConfigurationFactory or manually: + </p> + +<div class="source"> +<pre> +Configuration defaults = new PropertiesConfiguration(fileToDefaults); +Configuration otherProperties = new PropertiesConfiguration(fileToOtherProperties); +CompositeConfiguration cc = new CompositeConfiguration(); +cc.addConfiguration(otherProperties); +cc.addConfiguration(fileToDefaults); +</pre></div> + </div> + + +<div class="section"> +<h3>Saving Changes<a name="Saving_Changes"></a></h3> + +<p> + If you have a non static Configuration where you want to + save changes made to a configuration, and you are using a + CompositeConfiguration, then you will need to pass into + the constructor of the CompositeConfiguration what Configuration + to save the changes via. + </p> + +<div class="source"> +<pre> +PropertiesConfiguration saveConfiguration = new PropertiesConfiguration(fileToSaveChangesIn); +Configuration cc = new CompositeConfiguration(saveConfiguration); +cc.setProperty("newProperty","new value"); + +saveConfiguration.save(); +</pre></div> + +<p> + Alternatively, you can just request the + in-memory configuration that stores the changes. The following + example fragment copies all properties from the in-memory + configuration into a <tt>DatabaseConfiguration</tt>, so + that they are made persistent: + </p> +<div class="source"> +<pre> +Configuration changes = myCompositeConfiguration.getInMemoryConfiguration(); +DatabaseConfiguration config = new DatabaseConfiguration(datasource, "configuration", "key", "value"); +for (Iterator<String> i = changes.getKeys(); i.hasNext()){ + String key = i.next(); + Object value = changes.get(key); + config.setProperty(key,value); +} +</pre></div> + + + </div> + </div> + + + + </td> + </tr> + </table> + </div> + + <div class="footer"> + <p>Copyright © 2001-2014 + <a href="http://www.apache.org/";>The Apache Software Foundation</a>. + All Rights Reserved.</p> + +<div class="center">Apache Commons, Apache Commons Configuration, Apache, the Apache feather logo, and the Apache Commons project logos are trademarks of The Apache Software Foundation. + All other marks mentioned may be trademarks or registered trademarks of their respective owners.</div> + </div> + </body> + +</html>
![http://www.apache.org/events/current-event-125x125.png"](http://www.apache.org/events/current-event-125x125.png"){kind=link}
![http://maven.apache.org/images/logos/maven-feather.png"](http://maven.apache.org/images/logos/maven-feather.png"){kind=link}