You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by oh...@apache.org on 2014/09/24 22:29:02 UTC
svn commit: r923442 [4/7] -
/websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/
Added: websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_filebased.html
==============================================================================
--- websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_filebased.html (added)
+++ websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_filebased.html Wed Sep 24 20:29:01 2014
@@ -0,0 +1,506 @@
+<!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 -
+ File-based Configurations</title>
+
+ <link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css" />
+ <link rel="stylesheet" href="../css/site.css" type="text/css" />
+ <link rel="stylesheet" href="../css/print.css" media="print" />
+
+ <script type="text/javascript" src="../js/jquery.min.js"></script>
+ <script type="text/javascript" src="../js/bootstrap.min.js"></script>
+ <script type="text/javascript" src="../js/prettify.min.js"></script>
+ <script type="text/javascript" src="../js/site.js"></script>
+
+
+<link rel="stylesheet" type="text/css" media="all" href="../css/prettify.css"/>
+<script src="../js/prettify.js" type="text/javascript"></script>
+<script type="text/javascript">window.onload=function() {
+ prettyPrint();
+ }</script>
+ </head>
+
+ <body class="composite">
+ <a href="http://commons.apache.org/" id="bannerLeft" title="Apache Commons logo">
+ <img class="logo-left" src="../images/commons-logo.png" alt="Apache Commons logo"/>
+ </a>
+ <a href="../index.html" id="bannerRight">
+ <img class="logo-right" src="../images/logo.png" alt="Commons Configuration"/>
+ </a>
+ <div class="clear"></div>
+
+ <div class="navbar">
+ <div class="navbar-inner">
+ <div class="container-fluid">
+ <a class="brand" href="http://commons.apache.org/proper/commons-configuration/">Apache Commons Configuration ™</a>
+ <ul class="nav">
+
+ <li id="publishDate">Last Published: 24 September 2014</li>
+ <li class="divider">|</li> <li id="projectVersion">Version: 1.10</li>
+ </ul>
+ <div class="pull-right"> <ul class="nav">
+ <li>
+ <a href="http://www.apachecon.com/" class="externalLink" title="ApacheCon">
+ ApacheCon</a>
+ </li>
+ <li>
+ <a href="http://www.apache.org" class="externalLink" title="Apache">
+ Apache</a>
+ </li>
+ <li>
+ <a href="../../../" title="Commons">
+ Commons</a>
+ </li>
+ </ul>
+</div>
+ </div>
+ </div>
+ </div>
+
+ <div class="container-fluid">
+ <table class="layout-table">
+ <tr>
+ <td class="sidebar">
+ <div class="well sidebar-nav">
+ <ul class="nav nav-list">
+ <li class="nav-header">Configuration</li>
+ <li class="none">
+ <a href="../index.html" title="Home">
+ Home</a>
+ </li>
+ <li class="none">
+ <a href="../../../configuration/download_configuration.cgi" title="Download">
+ Download</a>
+ </li>
+ <li class="none">
+ <a href="../changes-report.html" title="Release History">
+ Release History</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/user_guide.html" title="User's Guide">
+ User's Guide</a>
+ </li>
+ <li class="none">
+ <a href="../dependencies.html" title="Runtime Dependencies">
+ Runtime Dependencies</a>
+ </li>
+ <li class="none">
+ <a href="../apidocs/index.html" title="Javadoc">
+ Javadoc</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+ <li class="nav-header"><i class="icon-cog"></i>Development</li>
+ <li class="none">
+ <a href="../building.html" title="Building">
+ Building</a>
+ </li>
+ <li class="none">
+ <a href="../issue-tracking.html" title="Issue Tracking">
+ Issue Tracking</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+ <li class="nav-header"><i class="icon-info-sign"></i>Project Documentation</li>
+ <li class="collapsed">
+ <a href="../project-info.html" title="Project Information">
+ Project Information</a>
+ </li>
+ <li class="collapsed">
+ <a href="../project-reports.html" title="Project Reports">
+ Project Reports</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+ <li class="nav-header">Commons</li>
+ <li class="none">
+ <a href="../../../" title="Home">
+ Home</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/licenses/" class="externalLink" title="License">
+ License</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../../components.html" title="Components">
+ Components</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../../sandbox/index.html" title="Sandbox">
+ Sandbox</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../../dormant/index.html" title="Dormant">
+ Dormant</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+ <li class="nav-header">General Information</li>
+ <li class="none">
+ <a href="../../../volunteering.html" title="Volunteering">
+ Volunteering</a>
+ </li>
+ <li class="none">
+ <a href="../../../patches.html" title="Contributing Patches">
+ Contributing Patches</a>
+ </li>
+ <li class="none">
+ <a href="../../../building.html" title="Building Components">
+ Building Components</a>
+ </li>
+ <li class="none">
+ <a href="../../../releases/index.html" title="Releasing Components">
+ Releasing Components</a>
+ </li>
+ <li class="none">
+ <a href="http://wiki.apache.org/commons/FrontPage" class="externalLink" title="Wiki">
+ Wiki</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+ <li class="nav-header">ASF</li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink" title="How the ASF works">
+ How the ASF works</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/getinvolved.html" class="externalLink" title="Get Involved">
+ Get Involved</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/dev/" class="externalLink" title="Developer Resources">
+ Developer Resources</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship">
+ Sponsorship</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks">
+ Thanks</a>
+ </li>
+ </ul>
+ </div>
+ <div id="poweredBy">
+ <a href="http://www.apache.org/events/current-event.html" title="ApacheCon" class="builtBy">
+ <img class="builtBy" alt="ApacheCon" src="http://www.apache.org/events/current-event-125x125.png" />
+ </a>
+ <a href="http://maven.apache.org/" title="Maven" class="builtBy">
+ <img class="builtBy" alt="Maven" src="http://maven.apache.org/images/logos/maven-feather.png" />
+ </a>
+ </div>
+ </td>
+ <td class="content">
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License. -->
+
+
+ <div class="section">
+<h2>File-based Configurations<a name="File-based_Configurations"></a></h2>
+
+<p>
+ Often configuration properties are stored in files on the user's hard
+ disk, e.g. in .properties files or as XML documents. Configuration
+ classes that deal with such properties need to provide typical operations
+ like loading or saving files. The files to be processed can be specified
+ in several different flavors like <tt>java.io.File</tt> objects,
+ relative or absolute path names, or URLs.
+ </p>
+
+<p>
+ To provide a consistent way of dealing with configuration files in
+ Commons Configuration the <tt><a href="../apidocs/org/apache/commons/configuration/FileConfiguration.html">FileConfiguration</a></tt>
+ interface exists. <tt>FileConfiguration</tt> defines a standard
+ API for accessing files and is implemented by many configuration
+ implementations, including <tt>PropertiesConfiguration</tt> and
+ <tt>XMLConfiguration</tt>.
+ </p>
+
+<p>
+ In the following sections we take a closer look at the methods of the
+ <tt>FileConfiguration</tt> interface and how they are used.
+ </p>
+
+
+<div class="section">
+<h3>Specifying the file<a name="Specifying_the_file"></a></h3>
+
+<p>
+ The <tt>FileConfiguration</tt> interface contains several
+ methods for specifying the file to be loaded. The following variants
+ are supported:
+ </p>
+<ul>
+
+<li>With the <tt>setFile()</tt> method the data file can be
+ specified as a <tt>java.io.File</tt> object.</li>
+
+<li>The <tt>setURL()</tt> takes a <tt>java.net.URL</tt>
+ as argument; the file will be loaded from this URL.</li>
+
+<li>The methods <tt>setFileName()</tt> and <tt>setBasePath()</tt>
+ allows to specify the path of the data file. The base path is
+ important if relative paths are to be resolved based on this file.</li>
+ </ul>
+
+
+<p>
+ While a <tt>File</tt> or a URL uniquely identify a file, the
+ situation is a bit ambigous when only a base path and a file name are
+ set. These can be arbitrary strings (even full URLs) whose exact
+ meaning must be detected when the file is loaded. For this purpose
+ file-based configurations perform the following checks (in this
+ order):
+ </p>
+<ul>
+
+<li>If the combination from base path and file name is a full URL
+ that points to an existing file, this URL will be used to load
+ the file.</li>
+
+<li>If the combination from base path and file name is an absolute
+ file name and this file exists, it will be loaded.</li>
+
+<li>If the combination from base path and file name is a relative
+ file path that points to an existing file, this file will be loaded.</li>
+
+<li>If a file with the specified name exists in the user's home
+ directory, this file will be loaded.</li>
+
+<li>Otherwise the file name is interpreted as a resource name, and
+ it is checked whether the data file can be loaded from the classpath.</li>
+ </ul>
+ If all these checks fail, a <tt>ConfigurationException</tt> will
+ be thrown.
+
+ </div>
+
+
+<div class="section">
+<h3>Loading<a name="Loading"></a></h3>
+
+<p>
+ After the file name has been defined using one of the methods mentioned
+ above, the <tt>load()</tt> method can be called. This method tries
+ to locate the file and open it. If this fails, a <tt>ConfigurationException</tt>
+ is thrown.
+ </p>
+
+<p>
+ The <tt>FileConfiguration</tt> interface defines multiple overloaded
+ <tt>load()</tt> methods. The one that takes no argument will
+ always operate on the file name that has been set earlier. All
+ other methods allow to specify the source to be loaded. This can be
+ done as <tt>java.io.File</tt>, <tt>java.net.URL</tt>, string
+ (containing either an absolute or relative path), input stream, or
+ reader. When using these variants of the <tt>load()</tt> method
+ be aware of two things:
+ </p>
+<ol style="list-style-type: decimal">
+
+<li>They do not change the configuration's file name. To do this
+ you have to explicitely call one of the setter methods.</li>
+
+<li>The <tt>load()</tt> methods do not empty the
+ configuration before new data is loaded. This makes it easy to
+ construct union configurations by simply calling <tt>load()</tt>
+ multiple times. But if you want to reuse a <tt>Configuration</tt>
+ object and load a different file, remember to call the
+ <tt>clear()</tt> method first to ensure that old properties are
+ wiped out.</li>
+ </ol>
+
+
+<p>
+ File-based configurations typically define a set of constructors that
+ correspond to the various setter methods for defining the data file.
+ These constructors will set the file and then invoke the <tt>load()</tt>
+ method. So creating a file-based configuration object and loading its
+ content can be done in a single step.
+ </p>
+ </div>
+
+
+<div class="section">
+<h3>Saving<a name="Saving"></a></h3>
+
+<p>
+ Saving is implemented analogously to loading: There is a no argument
+ <tt>save()</tt> method that will use the internal file name. Then
+ for each <tt>load()</tt> method a corresponding <tt>save()</tt>
+ method exists that will write the data contained in the configuration
+ to different targets.
+ </p>
+
+<p>
+ An example for loading, manipulating, and saving a configuration
+ (based on a <a href="howto_properties.html"><tt>PropertiesConfiguration</tt></a>)
+ could look as follows:
+ </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>
+ </div>
+
+
+<div class="section">
+<h3>Automatic Saving<a name="Automatic_Saving"></a></h3>
+
+<p>
+ If you want to ensure that every modification of a configuration
+ object is immideately written to disk, you can enable the automatic
+ saving mode. This is done through the <tt>setAutoSave()</tt>
+ method as shown in the following example:
+ </p>
+
+<div class="source">
+<pre>
+PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
+config.setAutoSave(true);
+config.setProperty("colors.background", "#000000"); // the configuration is saved after this call
+</pre></div>
+
+<p>
+ Be careful with this mode when you have many updates on your
+ configuration. This will lead to many I/O operations, too.
+ </p>
+ </div>
+
+
+<div class="section">
+<h3>Automatic Reloading<a name="Automatic_Reloading"></a></h3>
+
+<p>
+ A common issue with file-based configurations is to handle the
+ reloading of the data file when it changes. This is especially important
+ if you have long running applications and do not want to restart them
+ when a configuration file was updated. Commons Configuration has the
+ concept of so called <i>reloading strategies</i> that can be
+ associated with a file-based configuration. Such a strategy monitors
+ a configuration file and is able to detect changes. A default reloading
+ strategy is <tt><a href="../apidocs/org/apache/commons/configuration/reloading/FileChangedReloadingStrategy.html">FileChangedReloadingStrategy</a></tt>.
+ It can be set on a file-based configuration as follows:
+ </p>
+
+<div class="source">
+<pre>
+PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
+config.setReloadingStrategy(new FileChangedReloadingStrategy());
+</pre></div>
+
+<p>
+ <tt>FileChangedReloadingStrategy</tt> works as follows: On every
+ property access the configuration checks its associated reloading
+ strategy. <tt>FileChangedReloadingStrategy</tt> will then obtain
+ the last modification date of the configuration file and check whether
+ it has changed since the last access. If this is the case, a reload is
+ triggered. To avoid often disk access when multiple properties are
+ queried from the configuration, a <i>refresh delay</i> can be set on
+ the reloading strategy. This is a time in milli seconds with the meaning
+ that the reloading strategy will only once check the file's last
+ modification time in the period specified here.
+ </p>
+ </div>
+
+
+<div class="section">
+<h3>Managed Reloading<a name="Managed_Reloading"></a></h3>
+
+<p>
+ <tt>ManagedReloadingStrategy</tt> is an alternative to automatic
+ reloading. It allows to hot-reload properties on a running application
+ but only when requested by admin. The <tt>refresh()</tt> method
+ will force a reload of the configuration source.
+ </p>
+
+<p>
+ A typical use of this feature is to setup ManagedReloadingStrategy as
+ a JMX MBean. The following code sample uses Springframework
+ MBeanExporter to expose the ManagedReloadingStrategy to the JMX
+ console :
+</p>
+<div class="source">
+<pre>
+
+<!-- A file based configuration bean -->
+<bean id="configuration" class="(...).PropertiesConfiguration">
+ <constructor-arg type="java.net.URL" value="file:${user.home}/custom.properties"/>
+ <property name="reloadingStrategy" ref="reloadingStrategy"/>
+</bean>
+
+<!-- The managed reloading strategy for the configuration bean -->
+<bean id="reloadingStrategy" class="...ManagedReloadingStrategy"/>
+
+<!-- The MBeanExporter that exposes reloadingStrategy to the JMX console -->
+<bean id="mbeanMetadataExporter" class="org.springframework.jmx.export.MBeanExporter">
+ <property name="server" ref="mbeanServer"/>
+ <property name="beans">
+ <map>
+ <entry key="myApp:bean=configuration" value-ref="reloadingStrategy"/>
+ </map>
+ </property>
+</bean>
+
+</pre></div>
+ With this configuration, the JMX console will expose the
+ "myApp:bean=configuration" MBean and it's refresh operation.
+
+ </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_filesystems.html
==============================================================================
--- websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_filesystems.html (added)
+++ websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_filesystems.html Wed Sep 24 20:29:01 2014
@@ -0,0 +1,364 @@
+<!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="Ralph Goers" />
+ <meta name="Date-Revision-yyyymmdd" content="20140924" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>Commons Configuration -
+ File Systems</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>File Systems<a name="File_Systems"></a></h2>
+
+<p>
+ In its default mode of operation Commons Configuration supports retrieving and storing
+ configuration files either on a local file system or via http. However, Commons
+ Configuration provides support for allowing other File System adapters. All file
+ access is accomplished through the <tt>FileSystem</tt> interface so accessing files
+ using other mechanisms is possible.
+ </p>
+
+<p>
+ Commons Configuration also provides a second FileSystem which allows retrieval using
+ <a class="externalLink" href="http://commons.apache.org/vfs">Apache Commons VFS</a>. As of this writing
+ Commons VFS supports 18 protocols for manipulating files.
+ </p>
+
+<div class="section">
+<h3>Configuration<a name="Configuration"></a></h3>
+
+<p>
+ The FileSystem used by Commons Configuration can be set in one of several ways:
+ </p>
+<ol style="list-style-type: decimal">
+
+<li>A system property named "org.apache.commons.configuration.filesystem" can be defined
+ with the full class name of the desired <tt>FileSystem</tt> implementation to set the
+ default <tt>FileSystem</tt>.</li>
+
+<li><tt>FileSystem.setDefaultFilesystem()</tt> can be called to directly set the
+ default <tt>FileSystem</tt> implementation.</li>
+
+<li><tt>DefaultConfigurationBuilder.setFileSystem()</tt> can be called to set the
+ FileSystem implementation. <tt>DefaultConfiguratonBuilder</tt> will use this for each
+ configuration it creates</li>
+
+<li><tt>DefaultConfigurationBuilder</tt> can be configured with the <tt>FileSystem</tt>
+ to be used when creating each of the configurations.</li>
+
+<li>Each Configuration referenced in <tt>DefaultConfigurationBuilder's</tt>
+ configuration can be configured with the <tt>FileSystem</tt> to use for that
+ configuration.</li>
+
+<li>Call setFileSystem() directly on any Configuration that implements <tt>FileSystemBased.</tt>
+ Both <tt>AbstractFileConfiguration</tt> and <tt>AbstractHierarchicalFileConfiguration</tt>
+ implement <tt>FileSystemBased</tt></li>
+ </ol>
+
+
+<p>
+ The example that follows shows how to add <tt>FileSystem</tt> configuration to
+ <tt>DefaultConfigurationBuilder</tt>.
+ </p>
+
+<div class="source">
+<pre>
+<configuration>
+ <header>
+ <result delimiterParsingDisabled="true" forceReloadCheck="true">
+ <expressionEngine config-class="org.apache.commons.configuration.tree.xpath.XPathExpressionEngine"/>
+ </result>
+ <fileSystem config-class="org.apache.commons.configuration.VFSFileSystem"/>
+ </header>
+ <override>
+ <xml fileName="settings.xml" config-name="xml">
+ <fileSystem config-class="org.apache.commons.configuration.DefaultFileSystem"/>
+ </xml>
+ </override>
+</configuration>
+</pre></div>
+ </div>
+
+<div class="section">
+<h3>File Options Provider<a name="File_Options_Provider"></a></h3>
+
+<p>
+ Commons VFS allows options to the underlying file systems being used. Commons Configuration
+ allows applications to provide these by implementing the <tt>FileOptionsProvider</tt> interface
+ and registering the provider with the <tt>FileSystem</tt>. <tt>FileOptionsProvider</tt>
+ has a single method that must be implemented, <tt>getOptions</tt>, which returns a Map
+ containing the keys and values that the <tt>FileSystem</tt> might use. The getOptions
+ method is called as each configuration uses VFS to create a <tt>FileOjbect</tt> to
+ access the file. The map returned does not have to contain the same keys and/or values
+ each time it is called. For example, the value of the <tt>currentUser</tt> key can be
+ set to the id of the currently logged in user to allow a WebDAV save to record the userid
+ as a file attribute.
+ </p>
+ </div>
+
+<div class="section">
+<h3>File Reloading Strategy<a name="File_Reloading_Strategy"></a></h3>
+
+<p>
+ The <tt><a href="../apidocs/org/apache/commons/configuration/reloading/VFSFileChangedReloadingStrategy.html">VFSFileChangedReloadingStrategy</a></tt>
+ can be used to cause Configurations accessed via the <tt>VFSFileSystem</tt> to be
+ monitored and reloaded when the files are modified. The example below shows how
+ <tt>DefaultConfigurationBuilder</tt> can be configured to use
+ <tt>VFSFilChangedReloadingStrategy</tt>.
+ In the example below both test.properties and settings.xml would be checked for changes
+ once per minute.
+ </p>
+
+<div class="source">
+<pre>
+<configuration>
+ <header>
+ <result delimiterParsingDisabled="true" forceReloadCheck="true">
+ <expressionEngine config-class="org.apache.commons.configuration.tree.xpath.XPathExpressionEngine"/>
+ </result>
+ <fileSystem config-class="org.apache.commons.configuration.VFSFileSystem"/>
+ </header>
+ <override>
+ <properties fileName="test.properties" throwExceptionOnMissing="true">
+ <reloadingStrategy refreshDelay="60000"
+ config-class="org.apache.commons.configuration.reloading.VFSFileChangedReloadingStrategy"/>
+ </properties>
+ <xml fileName="settings.xml" config-name="xml">
+ <reloadingStrategy refreshDelay="60000"
+ config-class="org.apache.commons.configuration.reloading.VFSFileChangedReloadingStrategy"/>
+ </xml>
+ </override>
+</configuration>
+</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_multitenant.html
==============================================================================
--- websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_multitenant.html (added)
+++ websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_multitenant.html Wed Sep 24 20:29:01 2014
@@ -0,0 +1,403 @@
+<!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="Ralph Goers" />
+ <meta name="Date-Revision-yyyymmdd" content="20140924" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>Commons Configuration -
+ Mutli-tenant Configurations</title>
+
+ <link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css" />
+ <link rel="stylesheet" href="../css/site.css" type="text/css" />
+ <link rel="stylesheet" href="../css/print.css" media="print" />
+
+ <script type="text/javascript" src="../js/jquery.min.js"></script>
+ <script type="text/javascript" src="../js/bootstrap.min.js"></script>
+ <script type="text/javascript" src="../js/prettify.min.js"></script>
+ <script type="text/javascript" src="../js/site.js"></script>
+
+
+<link rel="stylesheet" type="text/css" media="all" href="../css/prettify.css"/>
+<script src="../js/prettify.js" type="text/javascript"></script>
+<script type="text/javascript">window.onload=function() {
+ prettyPrint();
+ }</script>
+ </head>
+
+ <body class="composite">
+ <a href="http://commons.apache.org/" id="bannerLeft" title="Apache Commons logo">
+ <img class="logo-left" src="../images/commons-logo.png" alt="Apache Commons logo"/>
+ </a>
+ <a href="../index.html" id="bannerRight">
+ <img class="logo-right" src="../images/logo.png" alt="Commons Configuration"/>
+ </a>
+ <div class="clear"></div>
+
+ <div class="navbar">
+ <div class="navbar-inner">
+ <div class="container-fluid">
+ <a class="brand" href="http://commons.apache.org/proper/commons-configuration/">Apache Commons Configuration ™</a>
+ <ul class="nav">
+
+ <li id="publishDate">Last Published: 24 September 2014</li>
+ <li class="divider">|</li> <li id="projectVersion">Version: 1.10</li>
+ </ul>
+ <div class="pull-right"> <ul class="nav">
+ <li>
+ <a href="http://www.apachecon.com/" class="externalLink" title="ApacheCon">
+ ApacheCon</a>
+ </li>
+ <li>
+ <a href="http://www.apache.org" class="externalLink" title="Apache">
+ Apache</a>
+ </li>
+ <li>
+ <a href="../../../" title="Commons">
+ Commons</a>
+ </li>
+ </ul>
+</div>
+ </div>
+ </div>
+ </div>
+
+ <div class="container-fluid">
+ <table class="layout-table">
+ <tr>
+ <td class="sidebar">
+ <div class="well sidebar-nav">
+ <ul class="nav nav-list">
+ <li class="nav-header">Configuration</li>
+ <li class="none">
+ <a href="../index.html" title="Home">
+ Home</a>
+ </li>
+ <li class="none">
+ <a href="../../../configuration/download_configuration.cgi" title="Download">
+ Download</a>
+ </li>
+ <li class="none">
+ <a href="../changes-report.html" title="Release History">
+ Release History</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/user_guide.html" title="User's Guide">
+ User's Guide</a>
+ </li>
+ <li class="none">
+ <a href="../dependencies.html" title="Runtime Dependencies">
+ Runtime Dependencies</a>
+ </li>
+ <li class="none">
+ <a href="../apidocs/index.html" title="Javadoc">
+ Javadoc</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+ <li class="nav-header"><i class="icon-cog"></i>Development</li>
+ <li class="none">
+ <a href="../building.html" title="Building">
+ Building</a>
+ </li>
+ <li class="none">
+ <a href="../issue-tracking.html" title="Issue Tracking">
+ Issue Tracking</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+ <li class="nav-header"><i class="icon-info-sign"></i>Project Documentation</li>
+ <li class="collapsed">
+ <a href="../project-info.html" title="Project Information">
+ Project Information</a>
+ </li>
+ <li class="collapsed">
+ <a href="../project-reports.html" title="Project Reports">
+ Project Reports</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+ <li class="nav-header">Commons</li>
+ <li class="none">
+ <a href="../../../" title="Home">
+ Home</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/licenses/" class="externalLink" title="License">
+ License</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../../components.html" title="Components">
+ Components</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../../sandbox/index.html" title="Sandbox">
+ Sandbox</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../../dormant/index.html" title="Dormant">
+ Dormant</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+ <li class="nav-header">General Information</li>
+ <li class="none">
+ <a href="../../../volunteering.html" title="Volunteering">
+ Volunteering</a>
+ </li>
+ <li class="none">
+ <a href="../../../patches.html" title="Contributing Patches">
+ Contributing Patches</a>
+ </li>
+ <li class="none">
+ <a href="../../../building.html" title="Building Components">
+ Building Components</a>
+ </li>
+ <li class="none">
+ <a href="../../../releases/index.html" title="Releasing Components">
+ Releasing Components</a>
+ </li>
+ <li class="none">
+ <a href="http://wiki.apache.org/commons/FrontPage" class="externalLink" title="Wiki">
+ Wiki</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+ <li class="nav-header">ASF</li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink" title="How the ASF works">
+ How the ASF works</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/getinvolved.html" class="externalLink" title="Get Involved">
+ Get Involved</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/dev/" class="externalLink" title="Developer Resources">
+ Developer Resources</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship">
+ Sponsorship</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks">
+ Thanks</a>
+ </li>
+ </ul>
+ </div>
+ <div id="poweredBy">
+ <a href="http://www.apache.org/events/current-event.html" title="ApacheCon" class="builtBy">
+ <img class="builtBy" alt="ApacheCon" src="http://www.apache.org/events/current-event-125x125.png" />
+ </a>
+ <a href="http://maven.apache.org/" title="Maven" class="builtBy">
+ <img class="builtBy" alt="Maven" src="http://maven.apache.org/images/logos/maven-feather.png" />
+ </a>
+ </div>
+ </td>
+ <td class="content">
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License. -->
+
+
+ <div class="section">
+<h2>Multi-tenant Configurations<a name="Multi-tenant_Configurations"></a></h2>
+
+<p>
+ In a multi-tenant environment a single instance of the application
+ while run on behalf of many clients. Typically, this will require
+ that each client have its own unique configuration. The simplest
+ approach to enable an application to be multi-tenant is for it
+ to not really be aware of it at all. This requires that the
+ configuration framework take on some of the responsility for
+ making the application work correctly.
+ </p>
+
+<p>
+ One approach to enable this support in a web application might be
+ to use a Servlet Filter and then use the Log4j or SLF4J MDC to
+ save the attributes needed to identify the client. These attributes
+ can then be used to identify the specific client configuration to
+ be used. The classes described below use this technique to allow
+ configurations to transparently provide the configuration appropriate
+ for the clients.
+ </p>
+
+
+<div class="section">
+<h3>MultiFileHierarchicalConfiguration<a name="MultiFileHierarchicalConfiguration"></a></h3>
+
+<p>
+ The constructor for this class accepts a pattern. The pattern can
+ contain keys that will be resolved using the ConfigurationInterpolator
+ on each call to a method in the class. The configuration file will then
+ be located using the resolved pattern and a new XMLConfiguration
+ will be created and cached for subsequent requests. The ExpressionEngine,
+ ReloadingStrategy and listeners will be propogated to each of the
+ created configurations.
+ </p>
+
+<p>
+ When used in a combined configuration it is often acceptable for a file
+ matching a particular pattern to be missing so, by default, most exceptions
+ encountered when loading files are ignored. To change this behavior
+ call setIgnoreException(false) or configure the attribute to false in
+ DefaultConfigurationBuilder's configuration file. If schema validation
+ is enabled validation exceptions will always cause a failure.
+ </p>
+ </div>
+
+<div class="section">
+<h3>DynamicCombinedConfiguration<a name="DynamicCombinedConfiguration"></a></h3>
+
+<p>
+ The CombinedConfiguration class allows multiple configuration files to be
+ merged together. However, it will not merge a MultiFileHierarchicalConfiguration
+ properly since the underlying configuration file will be different depending
+ on the resolution of the location pattern. DynamicCombinedConfiguration
+ solves this by creating a new CombinedConfiguration for each pattern.
+ </p>
+ </div>
+
+<div class="section">
+<h3>Sample Configuration<a name="Sample_Configuration"></a></h3>
+
+<p>
+ This sample configuration illustrates how to use DynamicCombinedConfiguration
+ in combination with MultiFileHierarchicalConfiguration to create a multi-tenant
+ configuration.
+ </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"
+ config-class="org.apache.commons.configuration.DynamicCombinedConfiguration"
+ keyPattern="$${sys:Id}">
+ <expressionEngine
+ config-class="org.apache.commons.configuration.tree.xpath.XPathExpressionEngine"/>
+ </result>
+ <providers>
+ <provider config-tag="multifile"
+ config-class="org.apache.commons.configuration.DefaultConfigurationBuilder$FileConfigurationProvider"
+ configurationClass="org.apache.commons.configuration.MultiFileHierarchicalConfiguration"/>
+ </providers>
+ </header>
+ <override>
+ <multifile filePattern="/opt/configs/$$${sys:Id}/config.xml" config-name="clientConfig"/>
+ <xml fileName="/opt/configs/default/config.xml" config-name="defaultConfig"/>
+ </override>
+</configuration>
+</pre></div>
+
+<p>
+ Note how the variables have multiple '$'. This is how variables are escaped and
+ is necessary because the variables will be interpolated multiple times. Each
+ attempt will remove the leading '$'. When there is only a single '$' in front
+ of the '{' the interpolator will then resolve the variable. The first extra '$'
+ is necessary because DefaultConfigurationBuilder will interpolate any variables
+ in the configuration. In the case of the multifile configuration item two
+ leading '$' characters are necessary before the variable because it will be
+ interpolated by both DefaultConfigurationBuilder and DynamicCombinedConfiguration
+ before MultiFileHierarchicalConfiguration gets the chance to evaluate it.
+ Although in this example one would not expect system properties to change
+ at runtime, other types of lookups such as the MDCStrLookup provided with
+ SLF4J require that the variables be evaluated as the configuration is being
+ accessed instead of when the configuration file is processed to behave as desired.
+ </p>
+ </div>
+
+<div class="section">
+<h3>PatternSubtreeConfigurationWrapper<a name="PatternSubtreeConfigurationWrapper"></a></h3>
+
+<p>
+ Applications are often composed of many components each of which need their
+ own configuration. This can be accomodated by having a configuration file
+ per component, but this can make things hard to manage when there are many
+ clients and many components. A second approach is to combine them into
+ a single configuration file. However, this either means the subcomponent
+ has to be aware of the surrounding configuration and navigate past it or the
+ application must be provided just the portion of the configuration it
+ can process. PatternSubtreeConfigurationWrapper can be used for this purpose.
+ </p>
+
+<p>
+ Normal practice when using dependency injection frameworks is to have the
+ attributes needed to make components work correctly injected into them.
+ When working with Commons Configuration this works very well. Components
+ simply need to have a HierarchicalConfiguration attribute along with
+ a corresponding setter and getter. The injection framework can then be
+ used to provide the component with the correct configuration using
+ PatternSubtreeConfigurationWrapper as shown in the next example.
+ </p>
+
+<p>
+ </p>
+<div class="source">
+<pre>
+ <bean id="configurationBuilder"
+ class="org.apache.commons.configuration.DefaultConfigurationBuilder">
+ <property name="fileName">
+ <value>configuration.xml</value>
+ </property>
+ </bean>
+ <bean id="applicationConfig" factory-bean="configurationBuilder"
+ factory-method="getConfiguration">
+ </bean>
+ <bean id="subcomponentConfig"
+ class="org.apache.commons.configuration.PatternSubtreeConfigurationWrapper"
+ autowire='autodetect'>
+ <constructor-arg index="0">
+ <ref bean="applicationConfig"/>
+ </constructor-arg>
+ <constructor-arg index="1" value="/Components/MyComponent"
+ </bean>
+ <bean id='MyComponent' class='org.test.MyComponent' autowire='autodetect'>
+ <property name="configuration">
+ <ref bean="subcomponentConfig"/>
+ </property>
+ </bean>
+</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>