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 [3/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_configurationbuilder.html
==============================================================================
--- websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_configurationbuilder.html (added)
+++ websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_configurationbuilder.html Wed Sep 24 20:29:01 2014
@@ -0,0 +1,1257 @@
+<!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="Date-Revision-yyyymmdd" content="20140924" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>Commons Configuration -
+ Configuration Builder Howto</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. --><!-- $Id: howto_configurationbuilder.xml 1156501 2011-08-11 06:22:49Z oheger $ -->
+
+
+ <div class="section">
+<h2>Using DefaultConfigurationBuilder<a name="Using_DefaultConfigurationBuilder"></a></h2>
+
+<p>
+ This section explains how a
+ <tt><a href="../apidocs/org/apache/commons/configuration/DefaultConfigurationBuilder.html">
+ DefaultConfigurationBuilder</a></tt>object is setup that provides
+ access to a collection of different configuration sources.
+ <tt>DefaultConfigurationBuilder</tt> is the option of choice for
+ applications that have to deal with multiple configuration sources. It
+ provides the following features:
+ </p>
+<ul>
+
+<li>Various configuration sources can be combined to a single
+ <a href="howto_combinedconfiguration.html#Combined_Configuration">
+ CombinedConfiguration</a> object. This is a truly hierarchical
+ configuration supporting enhanced query facilities.</li>
+
+<li>As configuration sources the most relevant <tt>Configuration</tt>
+ implementations provided by this library are supported. Sources are
+ defined as <a href="howto_beans.html#Declaring_and_Creating_Beans">bean
+ declarations</a>, so complex initializations are possible.</li>
+
+<li>Meta data can be provided to fine-tune the constructed
+ configuration.</li>
+
+<li><tt>DefaultConfigurationBuilder</tt> is extensible. Custom
+ configuration sources can be added.</li>
+ </ul>
+
+
+<p>
+ This document starts with some explanations of
+ <tt>DefaultConfigurationBuilder</tt> basics. Then the <i>configuration
+ definition files</i> processed by <tt>DefaultConfigurationBuilder</tt>
+ are discussed in detail. Finally an advanced example is presented.
+ </p>
+
+
+<div class="section">
+<h3>The configuration definition file<a name="The_configuration_definition_file"></a></h3>
+
+<p>
+ In previous chapters we have already seen how specific configuration
+ classes like <tt>PropertiesConfiguration</tt> or
+ <tt>XMLConfiguration</tt> can be used to load configuration data from
+ a single source. This may be sufficient for small applications, but if
+ requirements for configuration become more complex, additional support
+ for managing a set of different configuration sources is desired. This is
+ the domain of <tt>DefaultConfigurationBuilder</tt> which allows
+ combining multiple configuration sources. The properties defined in these
+ sources can then be accessed as if they were defined in a single
+ configuration file. The sources to be loaded have to be defined in a
+ XML document with a specific structure, a so-called <i>configuration
+ definition file</i>. The following listing shows a simple example of such
+ a definition file:
+ </p>
+
+<div class="source">
+<pre>
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+ <properties fileName="usergui.properties"/>
+</configuration>
+</pre></div>
+
+<p>
+ A configuration definition file can contain an arbitrary number of
+ elements declaring the configuration sources to load. The
+ <tt><properties></tt> element is one of these; it is used to
+ include properties files. For this example we store the definition file
+ in the same directory as the properties file and call it
+ <tt>config.xml</tt>. The properties file used in this example is the
+ same as in the section about <a href="howto_properties.html">properties
+ files</a>.
+ </p>
+ </div>
+
+
+<div class="section">
+<h3>Setting up a DefaultConfigurationBuilder<a name="Setting_up_a_DefaultConfigurationBuilder"></a></h3>
+
+<p>
+ Now we have to create a <tt>DefaultConfigurationBuilder</tt> object
+ and let it read this definition file. This is quite simple: Just create a
+ new instance and set the name of the definition file
+ (<tt>DefaultConfigurationBuilder</tt> is derived from
+ <tt>XMLConfiguration</tt>, so all options for specifying the document
+ to load are available here, too). The combined configuration collecting
+ all sources defined in the configuration definition file can then be
+ obtained by calling the <tt>getConfiguration()</tt> method:
+ </p>
+
+<div class="source">
+<pre>
+DefaultConfigurationBuilder builder = new DefaultConfigurationBuilder();
+builder.setFile(new File("config.xml"));
+Configuration config = builder.getConfiguration(true);
+</pre></div>
+
+<p>
+ Now the <i>config</i> object can be accessed in the usual way to query
+ configuration properties, e.g. by using methods like <tt>getString()</tt>,
+ or <tt>getInt()</tt>. We will see in a moment how properties defined
+ in different configuration sources are accessed.
+ </p>
+ </div>
+
+
+<div class="section">
+<h3>Overriding properties<a name="Overriding_properties"></a></h3>
+
+<p>
+ Using <tt>DefaultConfigurationBuilder</tt> to collect configuration
+ sources does not make much sense if there is only a single source to be
+ loaded. So let's add another one! This time we will embedd a XML file:
+ <i>gui.xml</i> which is shown in the next listing:
+ </p>
+
+<div class="source">
+<pre>
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<gui-definition>
+ <colors>
+ <background>#808080</background>
+ <text>#000000</text>
+ <header>#008000</header>
+ <link normal="#000080" visited="#800080"/>
+ </colors>
+ <rowsPerPage>15</rowsPerPage>
+</gui-definition>
+</pre></div>
+
+<p>
+ To make this XML document part of our global configuration we have to
+ modify our configuration definition file to also include the new file. For
+ XML documents the element <tt><xml></tt> can be used so that we
+ ave now:
+ </p>
+
+<div class="source">
+<pre>
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+ <properties fileName="usergui.properties"/>
+ <xml fileName="gui.xml"/>
+</configuration>
+</pre></div>
+
+<p>
+ The code for setting up the <tt>DefaultConfigurationBuilder</tt>
+ object remains the same. From the <tt>Configuration</tt> object
+ returned by the factory the new properties can be accessed in the usual
+ way.
+ </p>
+
+<p>
+ There is one problem with this example configuration setup: The
+ <tt>color.background</tt> property is defined in both the properties
+ and the XML file, and - to make things worse - with different values.
+ Which value will be returned by a call to <tt>getString()</tt>?
+ </p>
+
+<p>
+ The answer is that the configuration sources are searched in the order
+ they are defined in the configuration definition file. Here the properties
+ file is included first, then comes the XML file. Because the
+ <tt>color.background</tt> property can be found in the properties file
+ the value specified there will be returned (which happens to be
+ <tt>#FFFFFF</tt>).
+ </p>
+
+<p>
+ It might not be obvious why it makes sense to define the value of one and
+ the same property in multiple configuration sources. But consider the
+ following scenario: An application comes with a set of default properties
+ and allows the user to override some or all of them. This can now easily
+ be realized by saving the user's settings in one file and the default
+ settings in another. Then in the configuration definition file the file
+ with the user settings is included first and after that the file with the
+ default values. The application code that queries these settings needs no
+ be aware whether a property was overriden by the user. <tt>DefaultConfigurationBuilder</tt>
+ takes care that properties defined in the first file (the user file) are
+ found; other properties which the user has not changed will still be
+ returned from the second file (the defaults file).
+ </p>
+ </div>
+
+
+<div class="section">
+<h3>Optional configuration sources<a name="Optional_configuration_sources"></a></h3>
+
+<p>
+ The example above with two configuration sources - one for user settings
+ and one with default values - raises an interesting question: What happens
+ if the user has not defined specific properties yet? Or what if a new user
+ starts our application for the first time and thus no user specific
+ properties exist?
+ </p>
+
+<p>
+ The default behavior of <tt>DefaultConfigurationBuilder</tt> is to
+ throw a <tt>ConfigurationException</tt> exception if one of the sources
+ defined in the configuration definition file cannot be loaded. For our
+ example this behavior is not desired: the properties file with specific user
+ settings is not required. If it cannot be loaded, the example application
+ should still work because a complete set of configuration properties is
+ defined in the second file.
+ </p>
+
+<p>
+ <tt>DefaultConfigurationBuilder</tt> supports such optional configuration
+ sources. For this purpose in the definition of a configuration source the
+ <tt>config-optional</tt> attribute can be placed. An example of this
+ is shown below:
+ </p>
+
+<div class="source">
+<pre>
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+ <properties fileName="usersettings.properties" config-optional="true"/>
+ <properties fileName="default.properties"/>
+</configuration>
+</pre></div>
+
+<p>
+ In this configuration definition file the first properties file with user
+ specific settings is marked as optional. This means that if it cannot be
+ loaded, <tt>DefaultConfigurationBuilder</tt> will not throw an exception,
+ but only write a warning message to its logger. Note that the
+ <tt>config-optional</tt> attribute is absent for the second properties
+ file. Thus it is mandatory, and the <tt>getConfiguration()</tt> method
+ of <tt>DefaultConfigurationBuilder</tt> would throw an exception if it
+ could not be found.
+ </p>
+ </div>
+
+
+<div class="section">
+<h3>Union configuration<a name="Union_configuration"></a></h3>
+
+<p>
+ In an earlier section about the configuration definition file for
+ <tt>DefaultConfigurationBuilder</tt> it was stated that configuration
+ files included first can override properties in configuraton files
+ included later, and an example use case for this behaviour was given. There
+ may be cases when there are other requirements.
+ </p>
+
+<p>
+ Let's continue the example with the application that somehow process
+ database tables and that reads the definitions of the affected tables from
+ its configuration. This example and the corresponding XML configuration
+ files were introduced in the section about <a href="howto_xml.html">XMLConfiguration</a>.
+ Now consider that this application grows larger and must be maintained by
+ a team of developers. Each developer works on a separated set of tables.
+ In such a scenario it would be problematic if the definitions for all
+ tables would be kept in a single file. It can be expected that this file
+ needs to be changed very often and thus can be a bottleneck for team
+ development when it is nearly steadily checked out. It would be much better
+ if each developer had an associated file with table definitions and all
+ these information could be linked together at the end.
+ </p>
+
+<p>
+ <tt>DefaultConfigurationBuilder</tt> provides support for such a use case,
+ too. It is possible to specify in the configuration definition file that
+ from a set of configuration sources a logic union configuration is to be
+ constructed. Then all properties defined in the provided sources are
+ collected and can be accessed as if they had been defined in a single source.
+ To demonstrate this feature let us assume that a developer of the database
+ application has defined a specific XML file with a table definition named
+ <tt>tasktables.xml</tt>:
+ </p>
+
+<div class="source">
+<pre>
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<config>
+ <table tableType="application">
+ <name>tasks</name>
+ <fields>
+ <field>
+ <name>taskid</name>
+ <type>long</type>
+ </field>
+ <field>
+ <name>name</name>
+ <type>java.lang.String</type>
+ </field>
+ <field>
+ <name>description</name>
+ <type>java.lang.String</type>
+ </field>
+ <field>
+ <name>responsibleID</name>
+ <type>long</type>
+ </field>
+ <field>
+ <name>creatorID</name>
+ <type>long</type>
+ </field>
+ <field>
+ <name>startDate</name>
+ <type>java.util.Date</type>
+ </field>
+ <field>
+ <name>endDate</name>
+ <type>java.util.Date</type>
+ </field>
+ </fields>
+ </table>
+</config>
+</pre></div>
+
+<p>
+ This file defines the structure of an additional table, which should be
+ added to the so far existing table definitions. To achieve this the
+ configuration definition file has to be changed: A new section is added
+ that contains the include elements of all configuration sources which
+ are to be combined.
+ </p>
+
+<div class="source">
+<pre>
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!-- Configuration definition file that demonstrates the
+ override and additional sections -->
+
+<configuration>
+ <override>
+ <properties fileName="usergui.properties"/>
+ <xml fileName="gui.xml"/>
+ </override>
+
+ <additional>
+ <xml fileName="tables.xml"/>
+ <xml fileName="tasktables.xml" config-at="tables"/>
+ </additional>
+</configuration>
+</pre></div>
+
+<p>
+ Compared to the older versions of this file some changes have been done.
+ One major difference is that the elements for including configuration
+ sources are no longer direct children of the root element, but are now
+ contained in either an <tt><override></tt> or <tt><additional></tt>
+ section. The names of these sections already imply their purpose.
+ </p>
+
+<p>
+ The <tt>override</tt> section is not strictly necessary. Elements in
+ this section are treated as if they were children of the root element, i.e.
+ properties in the included configuration sources override properties in
+ sources included later. So the <tt><override></tt> tags could have
+ been ommitted, but for the sake of clearity it is recommended to use them
+ if there is also an <tt><additional></tt> section.
+ </p>
+
+<p>
+ It is the <tt><additonal></tt> section that introduces a new behaviour.
+ All configuration sources listed here are combined to a union configuration.
+ In our example we have put two <tt>xml</tt> elements in this area
+ that load the available files with database table definitions. The syntax
+ of elements in the <tt>additional</tt> section is analogous to the
+ syntax described so far. In this example the <tt>config-at</tt>
+ attribute is introduced. It specifies the position in the logic union
+ configuration where the included properties are to be added. Here it is set
+ for the second element to the value <i>tables</i>. This is because the
+ file starts with a <tt><table></tt> element, but to be compatible
+ with the other table definition file it should be accessable under the key
+ <tt>tables.table</tt>.
+ </p>
+
+<p>
+ After these modifications have been performed, the configuration obtained
+ from <tt>DefaultConfigurationBuilder</tt> allows access to three database
+ tables. A call of <tt>config.getString("tables.table(2).name");</tt>
+ results in a value of <i>tasks</i>. In an analogous way it is possible
+ to retrieve the fields of the third table.
+ </p>
+
+<p>
+ Note that it is also possible to override properties defined in an
+ <tt>additonal</tt> section. This can be done by placing a configuration
+ source in the <tt>override</tt> section that defines properties that
+ are also defined in one of the sources listed in the <tt>additional</tt>
+ section. The example does not make use of that. Note also that the order of
+ the <tt>override</tt> and <tt>additional</tt> sections in a
+ configuration definition file does not matter. Sources in an <tt>override</tt>
+ section are always treated with higher priority (otherwise they could not
+ override the values of other sources).
+ </p>
+ </div>
+
+
+<div class="section">
+<h3>Configuration definition file reference<a name="Configuration_definition_file_reference"></a></h3>
+
+<p>
+ Configuration definition files are XML documents telling
+ <tt>DefaultConfigurationBuilder</tt> which configuration sources to
+ load and how to process them in order to create the resulting combined
+ configuration.
+ </p>
+
+<p>
+ <b>Overall structure of a configuration definition file</b>
+ </p>
+
+<p>
+ A configuration definition file for <tt>DefaultConfigurationBuilder</tt>
+ can contain three sections, all of which are optional. A skeleton looks as
+ follows:
+ </p>
+
+<div class="source">
+<pre>
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration systemProperties="path to property file">
+ <header>
+ <!-- Meta data about the resulting combined configuration -->
+ </header>
+ <override>
+ <!-- Configuration declarations with override semantics -->
+ </override>
+ <additional>
+ <!-- Configuration declarations that form a union configuration -->
+ </additional>
+</configuration>
+</pre></div>
+
+<p>
+ <b>Declaring configuration sources</b>
+ </p>
+
+<p>
+ The <tt>override</tt> and <tt>additional</tt> sections have already
+ been introduced when the basics of <tt>DefaultConfigurationBuilder</tt>
+ were discussed. They contain declarations for the configuration sources to be
+ embedded. For convenience reasons it is also possible to declare
+ configuration sources outside these sections; they are then treated as if
+ they were placed inside the <tt>override</tt> section.
+ </p>
+
+<p>
+ Each declaration of a configuration source is represented by an XML
+ element whose name determines the type of the configuration source.
+ Attributes or nested elements can be used to provide additional
+ configuration options for the sources to be included (e.g. a name of a
+ file to be loaded or a reloading strategy). Below is a list of all
+ tags which can be used out of the box:
+ </p>
+
+<p>
+ </p>
+<dl>
+
+<dt>properties</dt>
+
+<dd>With this element properties files can be included. The name of
+ the file to load is specified using the <tt>fileName</tt>
+ attribute. Which configuration class is created by this tag
+ depends on the extension of the file to load: If the extension
+ is ".xml", a <tt>XMLPropertiesConfiguration</tt> object is
+ created, which is able to process the XML properties format
+ introduced in Java 5.0. Otherwise a <tt>PropertiesConfiguration</tt>
+ object is created, the default reader for properties files.</dd>
+
+<dt>xml</dt>
+
+<dd>The <tt>xml</tt> element can be used to load XML configuration
+ files. It also uses the <tt>fileName</tt> attribute to
+ determine the name of the file to load and creates an instance
+ of <tt>XMLConfiguration</tt>.</dd>
+
+<dt>jndi</dt>
+
+<dd>As the name implies, with this element JNDI resources can be
+ included in the resulting configuration. Under the hood this is
+ done by an instance of the <tt>JNDIConfiguration</tt>
+ class. The <tt>prefix</tt> attribute can be used to
+ select a subset of the JNDI tree.</dd>
+
+<dt>plist</dt>
+
+<dd>The <tt>plist</tt> element allows to embedd configuration
+ files in the NeXT / OpenStep or Mac OS X format. Again the
+ name of the file to load is specified through the
+ <tt>fileName</tt> attribute. If a XML file is specified,
+ a <tt>XMLPropertyListConfiguration</tt> object is created
+ to process the file. Otherwise this task is delegated to a
+ <tt>PropertyListConfiguration</tt> instance.</dd>
+
+<dt>system</dt>
+
+<dd>With this element an instance of <tt>SystemConfiguration</tt>
+ is added to the resulting configuration allowing access to
+ system properties. <i>Note:</i> Using this element system properties
+ are directly made available. Alternatively the
+ interpolation features introduced in version 1.4 (see
+ <a href="howto_basicfeatures.html#Variable_Interpolation">
+ Variable Interpolation</a> for more details) can be used for referencing
+ system properties.</dd>
+
+<dt>configuration</dt>
+
+<dd>The <tt>configuration</tt> tag allows other configuration
+ definition files to be included. This makes it possible to nest these
+ definition files up to an arbitrary depth. In fact, this tag will
+ create another <tt>DefaultConfigurationBuilder</tt> object,
+ initialize it, and obtain the <tt>CombinedConfiguation</tt> from it.
+ This combined configuration will then be added to the resulting
+ combined configuration. Like all file-based configurations the
+ <tt>fileName</tt> attribute can be used to specify the configuration
+ definition file to be loaded. This file must be an XML document that
+ conforms to the format described here. Some of the most important
+ settings are copied from the original <tt>DefaultConfigurationBuilder</tt>
+ object to the newly created builder:
+
+<ul>
+
+<li>the base path under which configuration files are searched</li>
+
+<li>some flags, e.g. for controlling delimiter parsing or throwing
+ exceptions on missing properties</li>
+
+<li>the logger</li>
+
+<li>the configuration and error listeners</li>
+ </ul>
+ </dd>
+
+<dt>ini</dt>
+
+<dd>This tag can be used to include an ini file into the resulting
+ combined configuration. Behind the scenes an instance of
+ <tt><a href="../apidocs/org/apache/commons/configuration/HierarchicalINIConfiguration.html">
+ HierarchicalINIConfiguration</a></tt> is used to load the ini file.</dd>
+
+<dt>env</dt>
+
+<dd>With this tag direct access to environment properties can be enabled.
+ This works in the same way as the <tt><system></tt> tag for
+ Java system properties.</dd>
+ </dl>
+
+
+<p>
+ In the declaration of a configuration source it is possible to set
+ properties on the corresponding configuration objects. Configuration
+ declarations are indeed
+ <a href="howto_beans.html#Declaring_and_Creating_Beans">Bean
+ declarations</a>. That means they can have attributes matching simple
+ properties of the configuration object to create, and sub elements
+ matching complex properties. The following example fragment shows how
+ complex initialization can be performed in a configuration declaration:
+ </p>
+
+<div class="source">
+<pre>
+ <properties fileName="test.properties" throwExceptionOnMissing="true">
+ <reloadingStrategy refreshDelay="10000"
+ config-class="org.apache.commons.configuration.reloading.FileChangedReloadingStrategy"/>
+ </properties>
+ <xml fileName="test.xml" delimiterParsingDisabled="true">
+ <expressionEngine config-class="org.apache.commons.configuration.tree.DefaultExpressionEngine"
+ propertyDelimiter="/" indexStart="[" indexEnd="]"/>
+ </xml>
+</pre></div>
+
+<p>
+ In this example a configuration source for a properties file and one for
+ an XML document are defined. For the properties source the
+ <tt>throwExceptionOnMissing</tt> property is set to <b>true</b>,
+ which means that it should throw an exception if a requested property is
+ not found. In addition it is assigned a reloading strategy, which is
+ declared and configured in a sub element. The XML configuration source is
+ initialized in a similar way: a simple property is set, and an expression
+ engine is assigned. More information about the format for declaring objects
+ and initializing their properties can be found in the section about
+ <a href="howto_beans.html#Declaring_and_Creating_Beans">bean
+ declarations</a>.
+ </p>
+
+<p>
+ In addition to the attributes that correspond to properties of the
+ configuration object to be created, a configuration declaration can have a
+ set of special attributes that are evaluated by
+ <tt>DefaultConfigurationBuilder</tt> when it creates the objects.
+ These attributes are listed in the following table:
+ </p>
+
+<p>
+ </p>
+<table class="bodyTable" border="1">
+
+<tr class="a">
+
+<th>Attribute</th>
+
+<th>Meaning</th>
+ </tr>
+
+<tr class="b">
+
+<td valign="top"><tt>config-name</tt></td>
+
+<td>Allows a name to be specified for this configuration. This name can
+ be used to obtain a reference to the configuration from the resulting
+ combined configuration (see below).</td>
+ </tr>
+
+<tr class="a">
+
+<td valign="top"><tt>config-at</tt></td>
+
+<td>With this attribute an optional prefix can be specified for the
+ properties of the corresponding configuration.</td>
+ </tr>
+
+<tr class="b">
+
+<td valign="top"><tt>config-optional</tt></td>
+
+<td>Declares a configuration as optional. This means that errors that
+ occur when creating the configuration are silently ignored. The default
+ behavior when an error occurs is that no configuration is added to
+ the resulting combined configuration. This behavior can be used to find
+ out whether an optional configuration could be successfully created or
+ not. If you specify a name for the optional configuration (using the
+ <tt>config-name</tt> attribute), you can later check whether the
+ combined configuration contains a configuration with this name. With the
+ <tt>config-forceCreate</tt> attribute (see below) this default
+ behavior can be changed.</td>
+ </tr>
+
+<tr class="a">
+
+<td valign="top"><tt>config-forceCreate</tt></td>
+
+<td>This boolean attribute is only evaluated for configurations declared as
+ optional. It determines the behavior of the configuration builder when
+ the optional configuration could not be created. If set to <b>true</b>,
+ the builder tries to create an empty, uninitialized configuration of the
+ correct type and add it to the resulting combined configuration. This is
+ especially useful for file-based configurations. Consider a use case
+ where an application wants to store user specific configuration files in
+ the users' home directories. When a user starts this application for the
+ first time, the user configuration does not exist yet. If it is declared
+ as <i>optional</i> and <i>forceCreate</i>, the missing configuration
+ file won't cause an error, but an empty configuration will be created.
+ The application can then obtain this configuration, add properties to it
+ (e.g. user specific settings) and save it. Without the
+ <tt>config-forceCreate</tt> attribute the application would have to
+ check whether the user configuration exists in the combined configuration
+ and eventually create it manually. Note that not all configuration
+ providers support this mechanism. Sometimes it may not be possible to
+ create an empty configuration if the standard initialization fails. In
+ this case no configuration will be added to the combined configuration
+ (with other words: the <tt>config-forceCreate</tt> attribute will not
+ have any effect).</td>
+ </tr>
+ </table>
+
+
+<p>
+ <i>Note:</i> In older versions of Commons Configuration the attributes
+ <tt>config-at</tt> and <tt>config-optional</tt> were named
+ <tt>at</tt> and <tt>optional</tt> respective. They have been
+ renamed in order to avoid possible name clashes with property names for
+ configuration sources. However, for reasons of backwards compatibility,
+ the old attribute names can still be used.
+ </p>
+
+<p>
+ Another useful feature is the built-in support for interpolation (i.e.
+ variable substitution): You can use variables in your configuration
+ definition file that are defined in declared configuration sources. For
+ instance, if the name of a configuration file to be loaded is defined by
+ the system property <tt>CONFIG_FILE</tt>, you can do something like
+ this:
+ </p>
+
+<div class="source">
+<pre>
+<configuration>
+ <!-- Load the system properties -->
+ <system/>
+ <!-- Now load the config file, using a system property as file name -->
+ <properties fileName="${CONFIG_FILE}"/>
+</configuration>
+</pre></div>
+
+<p>
+ Note that you can refer only to properties that have already been loaded.
+ If you change the order of the <tt><system></tt> and the
+ <tt><properties></tt> elements in the example above, an error
+ will occur because the <tt>${CONFIG_FILE}</tt> variable will then be
+ undefined at the moment it is evaluated.
+ </p>
+
+<div class="source">
+<pre>
+<configuration systemProperties="systemProperties.xml">
+ <!-- Load the system properties -->
+ <system/>
+ <!-- Now load the config file, using a system property as file name -->
+ <properties fileName="${CONFIG_FILE}"/>
+</configuration>
+</pre></div>
+
+<p>
+ This example differs from the previous one by the <tt>systemProperties</tt>
+ attribute added to the root element. It causes the specified to be read
+ and all properties defined therein to be added to the system properties.
+ So properties like <i>CONFIG_FILE</i> can be defined in a properties
+ file and are then treated as if they were system properties.
+ </p>
+
+<p>
+ <b>The header section</b>
+ </p>
+
+<p>
+ In the header section properties of the resulting combined configuration
+ object can be set. The main part of this section is a bean declaration
+ that is used for creating the resulting configuration object. Other
+ elements can be used for customizing the
+ <a href="howto_combinedconfiguration.html#Node_combiners">Node combiners</a>
+ used by the override and the union combined configuration. The following
+ example shows a header section that uses all supported properties:
+ </p>
+
+<div class="source">
+<pre>
+ <header>
+ <result delimiterParsingDisabled="true" forceReloadCheck="true">
+ <nodeCombiner config-class="org.apache.commons.configuration.tree.OverrideCombiner"/>
+ <expressionEngine config-class="org.apache.commons.configuration.tree.xpath.XPathExpressionEngine"/>
+ </result>
+ <combiner>
+ <override>
+ <list-nodes>
+ <node>table</node>
+ <node>list</node>
+ </list-nodes>
+ </override>
+ <additional>
+ <list-nodes>
+ <node>table</node>
+ </list-nodes>
+ </additional>
+ </combiner>
+ </header>
+</pre></div>
+
+<p>
+ The <tt>result</tt> element points to the bean declaration for the
+ resulting combined configuration. In this example we set some attributes
+ and initialize the node combiner (which is not necessary because the
+ default override combiner is specified), and the expression engine to be
+ used. Note that the <tt>config-class</tt> attribute makes it
+ possible to inject custom classes for the resulting configuration or the
+ node combiner.
+ </p>
+
+<p>
+ The <tt>combiner</tt> section allows nodes to be defined as list nodes.
+ This can be necessary for certain node combiner implementations to work
+ correctly. More information can be found in the section about
+ <a href="howto_combinedconfiguration.html#Node_combiners">Node combiners</a>.
+ </p>
+
+<p>
+ <i>Note:</i> From time to time the question is raised whether there is a
+ document type definition or a schema defining exactly the structure of a
+ configuration definition file. Frankly, the answer is no. This is due to
+ the fact that the format is extensible. As will be shown below, it is
+ possible to register yout own tags in order to embedd custom configuration
+ sources.
+ </p>
+ </div>
+
+
+<div class="section">
+<h3>An example<a name="An_example"></a></h3>
+
+<p>
+ After all that theory let's go through a more complex example! We start
+ with the configuration definition file that looks like the following:
+ </p>
+
+<div class="source">
+<pre>
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!-- Test configuration definition file that demonstrates complex initialization -->
+<configuration>
+ <header>
+ <result delimiterParsingDisabled="true" forceReloadCheck="true">
+ <expressionEngine config-class="org.apache.commons.configuration.tree.xpath.XPathExpressionEngine"/>
+ </result>
+ <combiner>
+ <additional>
+ <list-nodes>
+ <node>table</node>
+ </list-nodes>
+ </additional>
+ </combiner>
+ </header>
+ <override>
+ <properties fileName="user.properties" throwExceptionOnMissing="true"
+ config-name="properties" config-optional="true">
+ <reloadingStrategy refreshDelay="10000"
+ config-class="org.apache.commons.configuration.reloading.FileChangedReloadingStrategy"/>
+ </properties>
+ <xml fileName="settings.xml" config-name="xml"/>
+ </override>
+ <additional>
+ <xml config-name="tab1" fileName="table1.xml" config-at="database.tables"/>
+ <xml config-name="tab2" fileName="table2.xml" config-at="database.tables"
+ validating="true"/>
+ </additional>
+</configuration>
+</pre></div>
+
+<p>
+ This configuration definition file includes four configuration sources and
+ sets some properties for the resulting <tt>CombinedConfiguration</tt>.
+ Of special interest is the <tt>forceReloadCheck</tt> property, which
+ enables a special check for detecting property changes in the contained
+ configuration sources. If this property is not set, reloading won't work.
+ Because we have configured a reloading strategy for one of the included
+ configuration sources we have to set this flag so that this reloading
+ strategy can function properly. More details about this topic can be
+ found in the Javadocs for
+ <tt><a href="../apidocs/org/apache/commons/configuration/CombinedConfiguration.html">
+ CombinedConfiguration</a></tt>. We also set some properties for the
+ configurations to be loaded; for instance we declare that one of the XML
+ configurations should be validated.
+ </p>
+
+<p>
+ With the following code we can create a <tt>DefaultConfigurationBuilder</tt>
+ and load this file:
+ </p>
+
+<div class="source">
+<pre>
+DefaultConfigurationBuilder builder = new DefaultConfigurationBuilder();
+builder.setFile(new File("configuration.xml"));
+CombinedConfiguration cc = builder.getConfiguration(true);
+</pre></div>
+
+<p>
+ It would have been possible to specify the location of the configuration
+ definition file in multiple other ways, e.g. as a URL. The boolean argument
+ in the call to <tt>getConfiguration()</tt> determines whether the
+ configuration definition file should be loaded. For our simple example we
+ want this to happen, but it would also be possible to load the file
+ manually (by calling the <tt>load()</tt> method), and after that
+ updating the configuration. (Remember that <tt>DefaultConfigurationBuilder</tt>
+ is derived from <tt>XMLConfiguration</tt>, that means you can use all methods
+ provided by this class to alter its data, e.g. to add further configuration
+ sources.) If the configuration's data was manually changed, you should
+ call <tt>getConfiguration()</tt> with the argument <b>false</b>.
+ <tt>XMLConfiguration</tt> also provides the <tt>registerEntityId()</tt>
+ method that can be used to define the location of DTD files (refer to the
+ section <a href="howto_xml.html#Validation_of_XML_configuration_files">
+ Validation of XML configuration files</a> for more details). This method
+ is available for <tt>DefaultConfigurationBuilder</tt>, too. The
+ entities registered here will be passed to the loaded child XML
+ configurations. So you can register the DTDs of all child XML configurations
+ globally at the configuration builder.
+ </p>
+
+<p>
+ In the <tt>header</tt> section we have chosen an XPATH expression
+ engine for the resulting configuration. So we can query our properties
+ using the convenient XPATH syntax. By providing the <tt>config-name</tt>
+ attribute we have given all configuration sources a name. This name can
+ be used to obtain the corresponding sources from the combined
+ configuration. For configurations in the override section this is
+ directly possible:
+ </p>
+
+<div class="source">
+<pre>
+Configuration propertiesConfig = cc.getConfiguration("properties");
+Configuration xmlConfig = cc.getConfiguration("xml");
+</pre></div>
+
+<p>
+ Configurations in the <tt>additional</tt> section are treated a bit
+ differently: they are all packed together in another combined configuration
+ and then added to the resulting combined configuration. So in our example
+ the combined configuration <tt>cc</tt> will contain three configurations:
+ the two configurations from the override section, and the combined
+ configuration with the <tt>additional</tt> configurations. The latter
+ is stored under a name determined by the <tt>ADDITIONAL_NAME</tt>
+ constant of <tt>DefaultConfigurationBuilder</tt>. The following
+ code shows how the configurations of the <tt>additional</tt> section
+ can be accessed:
+ </p>
+
+<div class="source">
+<pre>
+CombinedConfiguration ccAdd = (CombinedConfiguration)
+ cc.getConfiguration(DefaultConfigurationBuilder.ADDITIONAL_NAME);
+Configuration tab1Config = ccAdd.getConfiguration("tab1");
+Configuration tab2Config = ccAdd.getConfiguration("tab2");
+</pre></div>
+ </div>
+
+
+<div class="section">
+<h3>Extending the configuration definition file format<a name="Extending_the_configuration_definition_file_format"></a></h3>
+
+<p>
+ If you have written a custom configuration class, you might want to
+ declare instances of this class in a configuration definition file, too.
+ With <tt>DefaultConfigurationBuilder</tt> this is now possible by
+ registering a <i>ConfigurationProvider</i>.
+ </p>
+
+<p>
+ <tt>ConfigurationProvider</tt> is an inner class defined in
+ <tt>DefaultConfigurationBuilder</tt>. Its task is to create and
+ initialize a configuration object. Whenever <tt>DefaultConfigurationBuilder</tt>
+ encounters a tag in the <tt>override</tt> or the <tt>additional</tt>
+ section it checks whether for this tag a <tt>ConfigurationProvider</tt>
+ was registered. If this is the case, the provider is asked to create a
+ new configuration instance; otherwise an exception will be thrown.
+ </p>
+
+<p>
+ So for adding support for a new configuration class you have to create an
+ instance of <tt>ConfigurationProvider</tt> (or a derived class) and
+ register it at the configuration builder using the
+ <tt>addConfigurationProvider()</tt> method. This method expects the
+ name of the associated tag and the provider instance as arguments.
+ </p>
+
+<p>
+ If your custom configuration class does not need any special initialization,
+ you can use the <tt>ConfigurationProvider</tt> class directly. It is
+ able of creating an instance of a specified class (which must be derived
+ from <tt>AbstractConfiguration</tt>). Let's take a look at an example
+ where we want to add support for a configuration class called
+ <tt>MyConfiguration</tt>. The corresponding tag in the configuration
+ definition file should have the name <tt>myconfig</tt>. The code for
+ registering the new provider and loading the configuration definition file
+ looks as follows:
+ </p>
+
+<div class="source">
+<pre>
+DefaultConfigurationBuilder builder = new DefaultConfigurationBuilder();
+DefaultConfigurationBuilder.ConfigurationProvider provider = new
+ DefaultConfigurationBuilder.ConfigurationProvider(MyConfiguration.class);
+builder.addConfigurationProvider("myconfig", provider);
+
+builder.setFileName("configuration.xml");
+Configuration config = builder.getConfiguration();
+</pre></div>
+
+<p>
+ If your configuration provider is registered this way, your configuration
+ definition file can contain the <tt>myconfig</tt> tag just as any
+ other tag for declaring a configuration source:
+ </p>
+
+<div class="source">
+<pre>
+<configuration>
+ <additional>
+ <xml fileName="settings.xml"/>
+ <myconfig delimiterParsingDisabled="true"/>
+ </additional>
+</configuration>
+</pre></div>
+
+<p>
+ As is demonstrated in this example, it is possible to specify attributes
+ for initializing properties of your configuration object. In this example
+ we set the default <tt>delimiterParsingDisabled</tt> property
+ inherited from <tt>AbstractConfiguration</tt>. Of course you can set
+ custom properties of your configuration class, too.
+ </p>
+
+<p>
+ If your custom configuration class is a file-based configuration, you
+ should use the <tt>FileConfigurationProvider</tt> class instead of
+ <tt>ConfigurationProvider</tt>. <tt>FileConfigurationProvider</tt>
+ is another inner class of <tt>DefaultConfigurationBuilder</tt> that
+ knows how to deal with file-based configurations: it ensures that the
+ correct base path is set and takes care of invoking the <tt>load()</tt>
+ method.
+ </p>
+
+<p>
+ If your custom configuration class requires special initialization, you
+ need to create your own provider class that extends
+ <tt>ConfigurationProvider</tt>. Here you will have to override the
+ <tt>getConfiguration(ConfigurationDeclaration)</tt> method, which is
+ responsible for creating the configuration instance (all information
+ necessary for this purpose can be obtained from the passed in declaration
+ object). It is recommended that you call the inherited method first,
+ which will instantiate and initialize the new configuration object. Then
+ you can perform your specific initialization.
+ </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_events.html
==============================================================================
--- websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_events.html (added)
+++ websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_events.html Wed Sep 24 20:29:01 2014
@@ -0,0 +1,489 @@
+<!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 -
+ Configuration Events Howto</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>Configuration Events<a name="Configuration_Events"></a></h2>
+
+<p>
+ All configuration classes derived from
+ <tt><a href="../apidocs/org/apache/commons/configuration/AbstractConfiguration.html">
+ AbstractConfiguration</a></tt> allow to register event listeners, which
+ are notified whenever the configuration's data is changed. This provides
+ an easy means for tracking updates on a configuration.
+ </p>
+
+
+<div class="section">
+<h3>Configuration listeners<a name="Configuration_listeners"></a></h3>
+
+<p>
+ Objects that are interested in update events triggered by configurations
+ must implement the
+ <tt><a href="../apidocs/org/apache/commons/configuration/event/ConfigurationListener.html">
+ ConfigurationListener</a></tt> interface. This interface defines a
+ single method <tt>configurationChanged()</tt>, which is passed a
+ <tt><a href="../apidocs/org/apache/commons/configuration/event/ConfigurationEvent.html">
+ ConfigurationEvent</a></tt> object. The event object contains all
+ information available about the modification, including:
+ </p>
+<ul>
+
+<li>A source object, which is usually the configuration object that was
+ modified.</li>
+
+<li>The event's type. This is a numeric value that corresponds to
+ constant declarations in concrete configuration classes. It describes
+ what exactly has happended.</li>
+
+<li>If available, the name of the property whose modification caused the
+ event.</li>
+
+<li>If available, the value of the property that caused this event.</li>
+
+<li>A flag whether this event was generated before or after the update
+ of the source configuration. A modification of a configuration typically
+ causes two events: one event before and one event after the modification
+ is performed. This allows event listeners to react at the correct point
+ of time.</li>
+ </ul>
+ Depending on the event type not all of this data may be available.
+
+
+<p>
+ For resolving the numeric event type use constants defined in
+ <tt>AbstractConfiguration</tt> or derived classes. These constants
+ start with the prefix <tt>EVENT_</tt> and have a speaking name. Here
+ is an incomplete list of available event types with the configuration
+ classes, in which they are defined:
+ </p>
+
+<p>
+ </p>
+<dl>
+
+<dt>AbstractConfiguration</dt>
+
+<dd>EVENT_ADD_PROPERTY (a property was added; the name of the affected
+ property and the value that was added can be obtained from the
+ event object), EVENT_SET_PROPERTY (a property's value was changed; the
+ event object stores the name of the affected property and its new value),
+ EVENT_CLEAR_PROPERTY (a property was removed from the configuration;
+ its name is stored in the event object), EVENT_CLEAR (the configuration
+ was cleared)</dd>
+
+<dt>AbstractFileConfiguration</dt>
+
+<dd>EVENT_RELOAD (the configuration was reloaded)</dd>
+
+<dt>HierarchicalConfiguration</dt>
+
+<dd>EVENT_ADD_NODES (the <tt>addNodes()</tt> method was called;
+ the event object contains the key, to which the nodes were added, and
+ a collection with the new nodes as value),
+ EVENT_CLEAR_TREE (the <tt>clearTree()</tt> method was called; the
+ event object stores the key of the removed sub tree),
+ EVENT_SUBNODE_CHANGED (a <tt>SubnodeConfiguration</tt> that was
+ created from this configuration has been changed. The value property
+ of the event object contains the original event object as it was sent by
+ the subnode configuration. <i>Note: At the moment it is not possible
+ to map the property key as it was received from the subnode configuration
+ into the namespace of the parent configuration.)</i></dd>
+ </dl>
+
+ </div>
+
+
+<div class="section">
+<h3>An example<a name="An_example"></a></h3>
+
+<p>
+ Implementing an event listener is quite easy. As an example we are going
+ to define an event listener, which logs all received configuration events
+ to the console. The class could look as follows:
+ </p>
+
+<div class="source">
+<pre>
+import org.apache.commons.configuration.event.ConfigurationEvent;
+import org.apache.commons.configuration.event.ConfigurationListener;
+
+public class ConfigurationLogListener implements ConfigurationListener
+{
+ public void configurationChanged(ConfigurationEvent event)
+ {
+ if (!event.isBeforeUpdate())
+ {
+ // only display events after the modification was done
+ System.out.println("Received event!");
+ System.out.println("Type = " + event.getType());
+ if (event.getPropertyName() != null)
+ {
+ System.out.println("Property name = " + event.getPropertyName());
+ }
+ if (event.getPropertyValue() != null)
+ {
+ System.out.println("Property value = " + event.getPropertyValue());
+ }
+ }
+ }
+}
+</pre></div>
+
+<p>
+ Now an instance of this event listener class has to be registered at a
+ configuration object:
+ </p>
+
+<div class="source">
+<pre>
+AbstractConfiguration config = ... // somehow create the configuration
+ConfigurationListener listener = new ConfigurationLogListener();
+config.addConfigurationListener(listener);
+...
+config.addProperty("newProperty", "newValue"); // will fire an event
+</pre></div>
+ </div>
+
+<div class="section">
+<h3>Error listeners<a name="Error_listeners"></a></h3>
+
+<p>
+ Some implementations of the <tt>Configuration</tt> interface operate
+ on underlying storages that can throw exceptions on each property access.
+ As an example consider <tt>
+ <a href="../apidocs/org/apache/commons/configuration/DatabaseConfiguration.html">
+ DatabaseConfiguration</a></tt>: this configuration class issues an SQL
+ statement for each accessed property, which can potentially cause a
+ <tt>SQLException</tt>.
+ </p>
+
+<p>
+ In earlier versions of <i>Commons Configuration</i> such exceptions
+ were simply logged and then swallowed. So for clients it was impossible
+ to find out if something went wrong. From version 1.4 on there is a new
+ way of dealing with those internal errors: the concept of <i>error
+ listeners</i>.
+ </p>
+
+<p>
+ A configuration error listener is very similar to a regular configuration
+ event listener. Instead of the <tt>ConfigurationListener</tt>
+ interface it has to implement the
+ <tt><a href="../apidocs/org/apache/commons/configuration/event/ConfigurationErrorListener.html">
+ ConfigurationErrorListener</a></tt> interface, which defines a single method
+ <tt>configurationError()</tt>. In case of an internal error this
+ method is invoked, and a
+ <tt><a href="../apidocs/org/apache/commons/configuration/event/ConfigurationErrorEvent.html">
+ ConfigurationErrorEvent</a></tt> with information about that error is
+ passed. By inheriting from <tt>ConfigurationEvent</tt>
+ <tt>ConfigurationErrorEvent</tt> supports all information that is
+ available for normal configuration listeners, too (e.g. the event type or
+ the property that was accessed when the problem occurred; note that the
+ <tt>isBefore()</tt> method does not really make sense for error
+ events because an error can only occur after something was done, so it
+ returns always <b>false</b> is this context). This data can
+ be used to find out when and where the error happened. In addition there
+ is the <tt>getCause()</tt> method that returns the <tt>Throwable</tt>
+ object, which generated this event (i.e. the causing exception).
+ </p>
+
+<p>
+ We can now continue our example from the previous section and make our
+ example configuration listener also capable of tracing error events. To
+ achieve this we let the <tt>ConfigurationLogListener</tt> class also
+ implement the <tt>ConfigurationErrorListener</tt> interface:
+ </p>
+
+<div class="source">
+<pre>
+import org.apache.commons.configuration.event.ConfigurationEvent;
+import org.apache.commons.configuration.event.ConfigurationListener;
+<b>import org.apache.commons.configuration.event.ConfigurationListener;</b>
+
+public class ConfigurationLogListener
+ implements ConfigurationListener, <b>ConfigurationErrorListener</b>
+{
+ public void configurationChanged(ConfigurationEvent event)
+ {
+ // remains unchanged, see above
+ ...
+ }
+
+ <b>public void configurationError(ConfigurationErrorEvent event)
+ {
+ System.out.println("An internal error occurred!");
+ // Log the standard properties of the configuration event
+ configurationChanged(event);
+ // Now log the exception
+ event.getCause().printStackTrace();
+ }</b>
+}
+</pre></div>
+
+<p>
+ Now the listener object has to be registered as an error listener, too.
+ For this purpose <tt>AbstractConfiguration</tt> provides the
+ <tt>addErrorListener()</tt> method. The following example fragment
+ shows the registration of the log listener object:
+ </p>
+
+<div class="source">
+<pre>
+AbstractConfiguration config = ... // somehow create the configuration
+ConfigurationListener listener = new ConfigurationLogListener();
+config.addConfigurationListener(listener);
+<b>config.addErrorListener((ConfigurationErrorListener) listener);</b>
+...
+config.addProperty("newProperty", "newValue"); // will fire an event
+</pre></div>
+
+<p>
+ Note: <tt>AbstractConfiguration</tt> already implements a mechanism
+ for writing internal errors to a logger object: It has the protected
+ <tt>addErrorLogListener()</tt> method that can be called by derived
+ classes to register a listener that will output all occurring internal
+ errors using the default logger. Configuration implementations like
+ <tt>DatabaseConfiguration</tt> that are affected by potential internal
+ errors call this method during their initialization. So the default
+ behavior of <i>Commons Configuration</i> for these classes is not
+ changed: they still catch occurring exceptions and log them. However by
+ registering specific error listeners it is now possible for clients to
+ implement their own handling of such errors.
+ </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>