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>
![http://www.apache.org/events/current-event-125x125.png"](http://www.apache.org/events/current-event-125x125.png"){kind=link}
![http://maven.apache.org/images/logos/maven-feather.png"](http://maven.apache.org/images/logos/maven-feather.png"){kind=link}