You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by oh...@apache.org on 2014/09/24 22:29:02 UTC
svn commit: r923442 [2/7] -
/websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/
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>