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>
![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}