Added: websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_properties.html ============================================================================== --- websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_properties.html (added) +++ websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_properties.html Wed Sep 24 20:29:01 2014 @@ -0,0 +1,754 @@ +<!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="Emmanuel Bourg" /> + <meta name="author" content="Oliver Heger" /> + <meta name="Date-Revision-yyyymmdd" content="20140924" /> + <meta http-equiv="Content-Language" content="en" /> + <title>Commons Configuration - + Properties files</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>Properties files<a name="Properties_files"></a></h2> + +<p> + Properties files are a popular mean of configuring applications. Of course Commons Configuration + supports this format and enhances significantly the basic <tt>java.util.Properties</tt> class. + This section introduces the features of the + <tt><a href="../apidocs/org/apache/commons/configuration/PropertiesConfiguration.html">PropertiesConfiguration</a></tt> class. + Note that <tt>PropertiesConfiguration</tt> is a very typical example + for an implementation of the <tt>Configuration</tt> interface and + many of the features described in this section (e.g. list handling or + interpolation) are supported by other configuration classes as well. + This is because most configuration implementations that ship with + Commons Configuration are derived from the common base class + <tt><a href="../apidocs/org/apache/commons/configuration/AbstractConfiguration.html">AbstractConfiguration</a></tt>, + which implements these features. + </p> + + +<div class="section"> +<h3>Using PropertiesConfiguration<a name="Using_PropertiesConfiguration"></a></h3> + +<p> + Let's start with a simple properties file named + <tt>usergui.properties</tt> with the following content: + </p> + +<div class="source"> +<pre> +# Properties definining the GUI +colors.background = #FFFFFF +colors.foreground = #000080 + +window.width = 500 +window.height = 300 +</pre></div> + + +<p> + To load this file, you'll write: + </p> + +<div class="source"> +<pre> +Configuration config = new PropertiesConfiguration("usergui.properties"); +</pre></div> + +<p> + If you do not specify an absolute path, the file will be searched automatically + in the following locations: + </p> +<ul> + +<li>in the current directory</li> + +<li>in the user home directory</li> + +<li>in the classpath</li> + </ul> + + +<p> + Instead of using a constructor that takes a file name you can also + invoke one of the <tt>load()</tt> methods. There are several + overloaded variants that allow you to load properties from various + sources. More information about loading properties files (and file-based + configurations in general) can be found in the section about + <a href="howto_filebased.html">File-based Configurations</a>. + </p> + +<p> + After the properties file was loaded you can access its content through + the methods of the <tt>Configuration</tt> interface, e.g. + </p> + +<div class="source"> +<pre> +String backColor = config.getString("colors.background"); +Dimension size = new Dimension(config.getInt("window.width"), + config.getInt("window.height")); +</pre></div> + </div> + + +<div class="section"> +<h3>Includes<a name="Includes"></a></h3> + +<p> + If a property is named "<tt>include</tt>" and the value of that property is the + name of a file on the disk, that file will be included into the configuration. Here is + an example: + </p> + +<div class="source"> +<pre> +# usergui.properties + +include = colors.properties +include = sizes.properties +</pre></div> + + +<div class="source"> +<pre> +# colors.properties + +colors.background = #FFFFFF +</pre></div> + + </div> + + +<div class="section"> +<h3>Lists and arrays<a name="Lists_and_arrays"></a></h3> + +<p> + As was already pointed out in the section + <a href="howto_basicfeatures.html#List_handling">List handling</a> + of <i>Basic features</i>, Commons Configuration has the ability to + return easily a list of values. For example a properties file can + contain a list of comma separated values: + </p> + +<div class="source"> +<pre> +# chart colors +colors.pie = #FF0000, #00FF00, #0000FF +</pre></div> + +<p> + You don't have to split the value manually, you can retrieve an array + or a <tt>java.util.List</tt> directly with: + </p> + +<div class="source"> +<pre> +String[] colors = config.getStringArray("colors.pie"); +List<Object> colorList = config.getList("colors.pie"); +</pre></div> + +<p> + Alternatively, you can specify a list of values in your properties file by using + the same key on several lines: + </p> + +<div class="source"> +<pre> +# chart colors +colors.pie = #FF0000; +colors.pie = #00FF00; +colors.pie = #0000FF; +</pre></div> + +<p> + All of the features related to list handling described for + <tt>AbstractConfiguration</tt> also apply to properties files, + including changing the list delimiter or disabling list handling at + all. + </p> + </div> + + +<div class="section"> +<h3>Saving<a name="Saving"></a></h3> + +<p> + To save your configuration, just call the <tt>save()</tt> method: + </p> + +<div class="source"> +<pre> +PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties"); +config.setProperty("colors.background", "#000000); +config.save(); +</pre></div> + +<p> + You can also save a copy of the configuration to another file: + </p> + +<div class="source"> +<pre> +PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties"); +config.setProperty("colors.background", "#000000); +config.save("usergui.backup.properties); +</pre></div> + +<p> + More information about saving properties files (and file-based + configurations in general) can be found in the section about + <a href="howto_filebased.html">File-based Configurations</a>. + </p> + </div> + + +<div class="section"> +<h3>Special Characters and Escaping<a name="Special_Characters_and_Escaping"></a></h3> + +<p> + If you need a special character in a property like a line feed, a tabulation or + an unicode character, you can specify it with the same escaped notation used for + Java Strings. The list separator ("," by default), can also be escaped: + </p> + +<div class="source"> +<pre> +key = This \n string \t contains \, escaped \\ characters \u0020 +</pre></div> + +<p> + When dealing with lists of elements that contain backslash characters + (e.g. file paths on Windows systems) escaping rules can become pretty + complex. The first thing to keep in mind is that in order to get a + single backslash, you have to write two: + </p> + +<div class="source"> +<pre> +config.dir = C:\\Temp\\ + </pre></div> + +<p> + This issue is not specific to Commons Configuration, but is related to + the standard format for properties files. Refer to the Javadocs of the + <tt>load()</tt> method of <tt>java.util.Properties</tt> for more + information. Now if you want to define a list with file paths, you may + be tempted to write the following: + </p> + +<div class="source"> +<pre> +# Wrong way to define a list of directories +config.dirs = C:\\Temp\\,D:\\data\\ + </pre></div> + +<p> + As the comment indicates, this will not work. The trailing backslash of + the first directory is interpreted as escape character for the list + delimiter. So instead of a list with two elements only a single value + of the property is defined - clearly not what was desired. To get a + correct list the trailing backslash has to be escaped. This is achieved + by duplicating it (yes, in a properties file that means that we now need + 4 backslashes): + </p> + +<div class="source"> +<pre> +# Correct way to define a list of directories +config.dirs = C:\\Temp\\\\,D:\\data\\ + </pre></div> + +<p> + So a sequence of 4 backslashes in the value of a property is interpreted + as an escaped backslash and eventually results in a single backslash. + This creates another problem when a properties file should refer to the + names of network shares. Typically these names start with two + backslashes, so the obvious way to define such a property is as follows: + </p> + +<div class="source"> +<pre> +# Wrong way to define a list of network shares +config.dirs = \\\\share1,\\\\share2 + </pre></div> + +<p> + Unfortunately, this will not work because the shares contain the reserved + sequence of 4 backslashes. So when reading the value of the + <i>config.dirs</i> property a list with two elements is returned + starting only with a single backslash. To fix the problem the sequence + for escaping a backslash has to be duplicated - we are now at 8 + backslashes: + </p> + +<div class="source"> +<pre> +# Correct way to define a list of network shares +config.dirs = \\\\\\\\share1,\\\\\\\\share2 + </pre></div> + +<p> + As becomes obvious, escape sequences can become pretty complex and + unreadable. In such situations it is recommended to use the alternative + way of defining a list: just use the same key multiple times. In this + case no additional escaping of backslashes (beyond the usual duplicating + required by properties files) is needed because there is no list + delimter character involved. Using this syntax the list of network + shares looks like the following: + </p> + +<div class="source"> +<pre> +# Straightforward way to define a list of network shares +config.dirs = \\\\share1 +config.dirs = \\\\share2 + </pre></div> + </div> + + +<div class="section"> +<h3>Layout Objects<a name="Layout_Objects"></a></h3> + +<p> + Each <tt>PropertiesConfiguration</tt> object is associated with a + <i>Layout object</i>, an instance of the class + <tt><a href="../apidocs/org/apache/commons/configuration/PropertiesConfigurationLayout.html"> + PropertiesConfigurationLayout</a></tt>. This layout object is + responsible for preserving most of the structure of loaded configuration + files. This means that things like comments or blank lines in a saved + properties file will closely resemble the original properties file + (the algorithm is not 100 percent perfect, but for most use cases it + should be sufficient). + </p> + +<p> + Normally a developer does not have to deal with these layout objects. + However, there are some methods that might be of interest if enhanced + control over the output of properties files is needed. The following + list describes these methods (note that corresponding get methods are + of course also provided): + </p> +<ul> + +<li><tt>setComment()</tt><br /> + With this method a comment can be set for a specified property. When + storing the configuration the comment is output before the property, + followed by a line break. The comment can span multiple lines; in this + case the newline character "\n" must be used as line + separator.</li> + +<li><tt>setHeaderComment()</tt><br /> + With <tt>setHeaderComment()</tt> a global comment can be set for the + properties file. This comment is written at the very start of the file, + followed by an empty line.</li> + +<li><tt>setBlancLinesBefore()</tt><br /> + This methods allows defining the number of empty lines to be written + before the specified property. It can be used, for instance, to + devide the properties file into multiple logical sections.</li> + +<li><tt>setSingleLine()</tt><br /> + If a property has multiple values, with <tt>setSingleLine()</tt> it + can be specified that all these values should be written into a single + line separated by the default list separator. It is also possible to + write multiple definitions for this property (i.e. multiple lines of the + form <tt>property = value1</tt>, <tt>property = value2</tt> etc.). + This is supported by <tt>PropertiesConfiguration</tt>, but will + probably not work when processing the properties file with other tools. + </li> + +<li><tt>setForceSingleLine()</tt><br /> + This is similar to <tt>setSingleLine()</tt>, but sets a global + single line flag. If set to <b>true</b>, all properties with multiple + values are always written on a single line.</li> + +<li><tt>setGlobalSeparator()</tt><br /> + Sometimes it may be necessary to define the properties separator, i.e. + the string that separates the property key from the value. This can be + done using <tt>setGlobalSeparator()</tt>. Here an arbitrary string + can be specified that will be used as separator. (Note: In order to + produce valid properties files only the characters <tt>=</tt> and + <tt>:</tt> should be used as separators (with or without leading or + trailing whitespace), but the method does not enforce this.</li> + +<li><tt>setSeparator()</tt><br /> + This method is similar to <tt>setGlobalSeparator()</tt>, but + allows setting the property separator for a specific property.</li> + +<li><tt>setLineSeparator()</tt><br /> + Using this method the line separator can be specified. Per default the + platform-specific line separator is used (e.g. <tt>\n</tt> on unix). + </li> + </ul> + The default settings of <tt>PropertiesConfigurationLayout</tt> are + chosen in a way that most of the original layout of a properties file + is retained. With the methods listed above specific layout restrictions + can be enforced. + + </div> + + +<div class="section"> +<h3>Custom properties readers and writers<a name="Custom_properties_readers_and_writers"></a></h3> + +<p> + There are situations when more control over the process of reading and + writing properties file is needed. For instance, an application might + have to deal with some legacy properties file in a specific format, + which is not supported out of the box by + <tt>PropertiesConfiguration</tt>, but must not be modified. In these + cases it is possible to inject a custom reader and writer for + properties files. + </p> + +<p> + Per default properties files are read and written by the nested classes + <tt>PropertiesReader</tt> and <tt>PropertiesWriter</tt> + (defined within <tt>PropertiesConfiguration</tt>). These classes are + regular reader and writer classes (both are derived from typical base + classes of the <tt>java.io</tt> package) that provide some + additional methods making dealing with properties files more + convenient. Custom implementations of properties readers and writers + must extend these base classes. + </p> + +<p> + For installing a custom properties reader or writer + <tt>PropertiesConfiguration</tt> provides the <tt>IOFactory</tt> + interface (which is also defined as a nested class). An object + implementing this interface is stored in each + <tt>PropertiesConfiguration</tt> instance. Whenever a properties + file is to be read or written (i.e. when one of the <tt>load()</tt> + or <tt>save()</tt> methods is called), the <tt>IOFactory</tt> + object is asked for creating the properties reader or writer to be + used. + </p> + +<p> + The <tt>IOFactory</tt> interface is pretty simple; it defines one + method for creating a properties reader and another one for creating a + properties writer. A default implementation called + <tt>DefaultIOFactory</tt> is also available and is used by + <tt>PropertiesConfiguration</tt> when no specific + <tt>IOFactory</tt> is set. To make this discussion more concrete + we provide an example of how to inject a custom properties reader. The + use case is that we have to load a properties file that contains keys + with whitespace, which is not supported by + <tt>PropertiesConfiguration</tt> per default. A fragment from such + a properties file could look as follows: + </p> + +<div class="source"> +<pre> +Background Color = #800080 +Foreground Color = #000080 +</pre></div> + +<p> + The first step is to create a custom properties reader implementation + that can deal with such properties. The class is derived from + <tt>PropertiesConfiguration.PropertiesReader</tt> and overrides the + <tt>parseProperty()</tt> method: + </p> + +<div class="source"> +<pre> +public class WhitespacePropertiesReader extends PropertiesConfiguration.PropertiesReader +{ + public WhitespacePropertiesReader(Reader in, char delimiter) + { + super(in, delimiter); + } + + /** + * Special algorithm for parsing properties keys with whitespace. This + * method is called for each non-comment line read from the properties + * file. + */ + protected void parseProperty(String line) + { + // simply split the line at the first '=' character + // (this should be more robust in production code) + int pos = line.indexOf('='); + String key = line.substring(0, pos).trim(); + String value = line.substring(pos + 1).trim(); + + // now store the key and the value of the property + initPropertyName(key); + initPropertyValue(value); + } +} +</pre></div> + +<p> + Notice the calls to the methods <tt>initPropertyName()</tt> and + <tt>initPropertyValue()</tt>. Here the results of the parsing + operation are stored. The next step is to provide a specialized + implementation of the <tt>IOFactory</tt> interface that returns + the new properties reader class. As we only want to replace the + properties reader (and use the standard writer), we can derive our + implementation from <tt>DefaultIOFactory</tt> and thus only have + to override the <tt>createPropertiesReader()</tt> method. + </p> + +<div class="source"> +<pre> +public class WhitespaceIOFactory extends PropertiesConfiguration.DefaultIOFactory +{ + /** + * Return our special properties reader. + */ + public PropertiesReader createPropertiesReader(Reader in, char delimiter) + { + return new WhitespacePropertiesReader(in, delimiter); + } +} +</pre></div> + +<p> + Finally an instance of our new <tt>IOFactory</tt> implementation + has to be created and passed to the <tt>PropertiesConfiguration</tt> + object. This must be done before the <tt>load()</tt> method is + called. So we cannot use one of the constructors that load the data. + The code for setting up the configuration object could look as follows: + </p> + +<div class="source"> +<pre> +PropertiesConfiguration config = new PropertiesConfiguration(); +config.setIOFactory(new WhitespaceIOFactory()); +config.setFile(...); // set the file to be loaded +config.load(); +</pre></div> + </div> + </div> + + + + </td> + </tr> + </table> + </div> + + <div class="footer"> + <p>Copyright © 2001-2014 + <a href="http://www.apache.org/";>The Apache Software Foundation</a>. + All Rights Reserved.</p> + +<div class="center">Apache Commons, Apache Commons Configuration, Apache, the Apache feather logo, and the Apache Commons project logos are trademarks of The Apache Software Foundation. + All other marks mentioned may be trademarks or registered trademarks of their respective owners.</div> + </div> + </body> + +</html>
Added: websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_utilities.html ============================================================================== --- websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_utilities.html (added) +++ websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_utilities.html Wed Sep 24 20:29:01 2014 @@ -0,0 +1,534 @@ +<!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 - + Utility classes and Tips and Tricks 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>Utility classes and Tips and Tricks<a name="Utility_classes_and_Tips_and_Tricks"></a></h2> + +<p> + In this section some utility classes will be introduced that can be used + to make handling of configuration objects easier. These classes already + provide solutions for some often occurring problems. We will list these + problems in no specific order and show how they can be solved with + classes provided by <i>Commons Configuration</i>. + </p> + + +<div class="section"> +<h3>Copy a configuration<a name="Copy_a_configuration"></a></h3> + +<p> + Often it is required to copy the data of one <tt>Configuration</tt> + object into another one. For this purpose the + <tt><a href="../apidocs/org/apache/commons/configuration/AbstractConfiguration.html"> + AbstractConfiguration</a></tt> class (which serves as the base class for + most of the configuration implementations shipped with this library) + provides two methods implementing a basic copy operation: + </p> +<ul> + +<li><tt>append()</tt> takes the configuration to be copied + as argument and adds all of its properties to the current configuration.</li> + +<li><tt>copy()</tt> is very similar to <tt>append()</tt>. The + difference is that properties that already exist in the target + configuration are replaced by the properties of the source configuration. + </li> + </ul> + + +<p> + These methods work fine if the target configuration is not a hierarchical + configuration. If a hierarchical configuration is to be copied into + another one, the methods are not able to handle the hierarchical + structure; so the resulting configuration will contain all of the + properties of the source configuration, but the specific parent-child + relations will probably be lost. If a hierarchical configuration needs to + be copied, there are the following options: + </p> +<ul> + +<li>The <tt>clone()</tt> method can be used to create a copy of a + hierarchical configuration. This also works for non-hierarchical + configurations. Most of the configuration implementations provided by + <i>Commons Configurations</i> support cloning. The + <tt>cloneConfiguration()</tt> method of + <tt><a href="../apidocs/org/apache/commons/configuration/ConfigurationUtils.html"> + ConfigurationUtils</a></tt> can be used for creating a copy of an + arbitrary <tt>Configuration</tt> object. This method checks whether + the passed in configuration implements the <tt>Cloneable</tt> + interface and, if so, invokes its <tt>clone()</tt> method.</li> + +<li>Most hierarchical configurations have a constructor, which takes + another hierarchical configuration as argument. This constructor + copies the content of the specified configuration into the newly created + object.</li> + </ul> + + </div> + + +<div class="section"> +<h3>Converting a flat configuration into a hierarchical one<a name="Converting_a_flat_configuration_into_a_hierarchical_one"></a></h3> + +<p> + <a href="howto_xml.html">Hierarchical configurations</a> provide some + enhanced features that are not available for "flat" + configurations. For instance they support more sophisticated query + facilities. Because of that it may be sometimes useful to transform an + ordinary configuration into a hierarchical one. The following code + fragment shows how this can be done: + </p> + +<div class="source"> +<pre> +// Create a flat configuration +PropertiesConfiguration flatConfig = new PropertiesConfiguration(); +flatConfig.load(...); +HierarchicalConfiguration hc = + ConfigurationUtils.convertToHierarchical(flatConfig); +</pre></div> + +<p> + The <tt>convertToHierarchical()</tt> method of + <tt><a href="../apidocs/org/apache/commons/configuration/ConfigurationUtils.html"> + ConfigurationUtils</a></tt> checks whether the passed in object + is already a hierarchical configuration. If this is the case, it is + returned unchanged. Otherwise a new <tt>HierarchicalConfiguration</tt> + object is created, and the properties of the source configuration are + copied into it. + </p> + +<p> + Sometimes a flat configuration contains keys with special characters + that are not compatible with the expression engine of a hierarchical + configuration. For instance, a properties configuration could have the + following property: + </p> + +<div class="source"> +<pre> +test(xy)=true +</pre></div> + +<p> + When processing this property during conversion the default expression + engine of the resulting hierarchical configuration will interpret the + brackets as an index marker and try to convert the string between the + brackets into a number. In this example this fails with a + <tt>NumberFormatException</tt>! The cause for this problem is that the + property key contains characters with a special meaning for the default + expression engine. + </p> + +<p> + To solve this problem, it is possible to specify an alternative expression + engine that will be used for the conversion. For instance, if you know that + your property keys can contain brackets, you could use an instance of + <tt>DefaultExpressionEngine</tt> that is configured with a different + index marker. This could look as follows: + </p> + +<div class="source"> +<pre> +DefaultExpressionEngine engineConvert = new DefaultExpressionEngine(); +engineConvert.setIndexStart("["); +engineConvert.setIndexEnd("]"); +HierarchicalConfiguration hc = + ConfigurationUtils.convertToHierarchical(flatConfig, engineConvert); +</pre></div> + +<p> + In this example an expression engine is constructed that uses square + brackets as index markers. Therefore normal brackets do not have a + special meaning and thus are no more problematic during conversion. + </p> + +<p> + <i>Note:</i> When using a <a href="howto_combinedconfiguration.html"> + CombinedConfiguration</a> flat configurations contained in the combined + configuration are also converted into hierarchical configurations using + the methods discussed here. The <tt>CombinedConfiguration</tt> class + defines the method <tt>setConversionExpressionEngine()</tt>, which + can be called to specify an expression engine to be used during this + conversion. The expression engine passed to this method will be + propagated to ConfigurationUtils.convertToHierarchical(). + </p> + </div> + + +<div class="section"> +<h3>Converting between properties and configurations<a name="Converting_between_properties_and_configurations"></a></h3> + +<p> + When working with the JDK the <tt>java.util.Properties</tt> class is + typically used for storing configuration data. If <i>Commons + Configuration</i> is to be integrated in such an application, there may + be the requirement of converting from <tt>Properties</tt> objects to + <tt>Configuration</tt> objects and vice versa. For this purpose an + utility class can be used: + <tt><a href="../apidocs/org/apache/commons/configuration/ConfigurationConverter.html"> + ConfigurationConverter</a></tt>. + </p> + +<p> + Usage of this class is pretty simple. It provides some static utility + methods that perform different conversions. Below you can see some + examples. In this fragment we assume that we have a method + <tt>processConfiguration()</tt> that is called from older parts of an + application that are not aware of the <i>Commons Configuration</i> API. + So they pass in a <tt>Properties</tt> object and expect one as + return value. Inside the method a temporary <tt>Configuration</tt> + object is created and used. + </p> + +<div class="source"> +<pre> +/** + * Does some processing of properties. + * @param props the source properties + * @return the processed properties + */ +Properties processConfiguration(Properties props) +{ + // Create a configuration for the properties for easy access + Configuration config = ConfigurationConverter.getConfiguration(props); + + // Now use the Configuration API for manipulating the configuration data + ... + + // Return a Properties object with the results + return ConfigurationConverter.getProperties(config); +} +</pre></div> + +<p> + Please refer to the Javadocs of + <tt><a href="../apidocs/org/apache/commons/configuration/ConfigurationConverter.html"> + ConfigurationConverter</a></tt> to learn more about the available + conversion methods and their limitations. + </p> + </div> + + +<div class="section"> +<h3>Interpolation of all variables<a name="Interpolation_of_all_variables"></a></h3> + +<p> + Another issue with the integration of <i>Commons Configuration</i> with + native Java applications can be variables: Configuration implementations + are able to detect variables like <tt>${myReference}</tt> or + <tt>${sys:java.version}</tt> in the values of their properties and + substitute them by their current values (see the section + <a href="howto_basicfeatures.html#Variable_Interpolation">Variable + Interpolation</a> for more details). External components probably do not + know how to handle such placeholders when processing configuration files + written by <i>Commons Configuration</i>. + </p> + +<p> + <tt><a href="../apidocs/org/apache/commons/configuration/AbstractConfiguration.html"> + AbstractConfiguration</a></tt> provides the method + <tt>interpolatedConfiguration()</tt>. This method creates a clone of + the current configuration and then performs interpolation on all of its + properties. So the result of this method is a configuration object with + basically the same content as the original configuration, but with all + variables replaced by their actual values (as far as this was possible). + The following code fragment shows how a + <tt><a href="../apidocs/org/apache/commons/configuration/PropertiesConfiguration.html"> + PropertiesConfiguration</a></tt> object can be saved in a way that the + resulting properties file does not contain any variables: + </p> + +<div class="source"> +<pre> +// Load a properties file (which may contain variables) +PropertiesConfiguration config = new PropertiesConfiguration("config.properties"); + +// Perform interpolation on all variables +PropertiesConfiguration extConfig = + (PropertiesConfiguration) config.interpolatedConfiguration(); + +// Save the interpolated configuration (no more variables) +extConfig.save("external_config.properties"); +</pre></div> + </div> + + +<div class="section"> +<h3>Handling of runtime exceptions<a name="Handling_of_runtime_exceptions"></a></h3> + +<p> + Section <a href="howto_events.html#Error_listeners">Error listeners</a> + introduces a way of dealing with runtime exceptions that can occur on + accessing configuration properties by registering an event listener. If + you do not want to provide a special error handler, but only need to + propagate the exception that caused the error event, you can make use of + a convenience method of the + <tt><a href="../apidocs/org/apache/commons/configuration/ConfigurationUtils.html"> + ConfigurationUtils</a></tt> class: <tt>enableRuntimeExceptions()</tt> + registers a special error listener at the passed in configuration that + will throw a + <tt><a href="../apidocs/org/apache/commons/configuration/ConfigurationRuntimeException.html"> + ConfigurationRuntimeException</a></tt> exception for each received + error event. The following code fragment shows an example of using this + method: + </p> + +<div class="source"> +<pre> +JNDIConfiguration config = new JNDIConfiguration(); +ConfigurationUtils.enableRuntimeExceptions(config); + +// This may now throw a ConfigurationRuntimeException +String value = config.getString("myKey"); +</pre></div> + +<p> + <tt>enableRuntimeExceptions()</tt> can be called for all + <tt>Configuration</tt> implementations that are derived from + <tt><a href="../apidocs/org/apache/commons/configuration/event/EventSource.html"> + EventSource</a></tt> (which is the case for almost all configuration + classes provided by this library). Of course the affected implementation + must support the mechanism of error events, otherwise the registered + listener will not be triggered. In + <a href="howto_events.html#Error_listeners">Error listeners</a> more + information can be found. + </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}