You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by rg...@apache.org on 2008/11/20 19:33:06 UTC
svn commit: r719319 [2/2] - in /commons/proper/configuration/trunk: ./ conf/
src/java/org/apache/commons/configuration/
src/test/org/apache/commons/configuration/ xdocs/ xdocs/userguide/
Copied: commons/proper/configuration/trunk/xdocs/userguide/howto_multitenant.xml (from r713226, commons/proper/configuration/trunk/xdocs/userguide/howto_filebased.xml)
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/xdocs/userguide/howto_multitenant.xml?p2=commons/proper/configuration/trunk/xdocs/userguide/howto_multitenant.xml&p1=commons/proper/configuration/trunk/xdocs/userguide/howto_filebased.xml&r1=713226&r2=719319&rev=719319&view=diff
==============================================================================
--- commons/proper/configuration/trunk/xdocs/userguide/howto_filebased.xml (original)
+++ commons/proper/configuration/trunk/xdocs/userguide/howto_multitenant.xml Thu Nov 20 10:33:04 2008
@@ -18,227 +18,131 @@
<document>
- <properties>
- <title>File-based Configurations</title>
- <author email="oheger@apache.org">Oliver Heger</author>
- </properties>
-
-<body>
- <section name="File-based Configurations">
- <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 <code>java.io.File</code> objects,
- relative or absolute path names, or URLs.
- </p>
- <p>
- To provide a consistent way of dealing with configuration files in
- Commons Configuration the <code><a href="apidocs/org/apache/commons/configuration/FileConfiguration.html">FileConfiguration</a></code>
- interface exists. <code>FileConfiguration</code> defines a standard
- API for accessing files and is implemented by many configuration
- implementations, including <code>PropertiesConfiguration</code> and
- <code>XMLConfiguration</code>.
- </p>
- <p>
- In the following sections we take a closer look at the methods of the
- <code>FileConfiguration</code> interface and how they are used.
- </p>
-
- <subsection name="Specifying the file">
- <p>
- The <code>FileConfiguration</code> interface contains several
- methods for specifying the file to be loaded. The following variants
- are supported:
- <ul>
- <li>With the <code>setFile()</code> method the data file can be
- specified as a <code>java.io.File</code> object.</li>
- <li>The <code>setURL()</code> takes a <code>java.net.URL</code>
- as argument; the file will be loaded from this URL.</li>
- <li>The methods <code>setFileName()</code> and <code>setBasePath()</code>
- 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>
- <p>
- While a <code>File</code> 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):
- <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 <code>ConfigurationException</code> will
- be thrown.
- </p>
- </subsection>
-
- <subsection name="Loading">
- <p>
- After the file name has been defined using one of the methods mentioned
- above, the <code>load()</code> method can be called. This method tries
- to locate the file and open it. If this fails, a <code>ConfigurationException</code>
- is thrown.
- </p>
- <p>
- The <code>FileConfiguration</code> interface defines multiple overloaded
- <code>load()</code> 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 <code>java.io.File</code>, <code>java.net.URL</code>, string
- (containing either an absolute or relative path), input stream, or
- reader. When using these variants of the <code>load()</code> method
- be aware of two things:
- <ol>
- <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 <code>load()</code> methods do not empty the
- configuration before new data is loaded. This makes it easy to
- construct union configurations by simply calling <code>load()</code>
- multiple times. But if you want to reuse a <code>Configuration</code>
- object and load a different file, remember to call the
- <code>clear()</code> method first to ensure that old properties are
- wiped out.</li>
- </ol>
- </p>
- <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 <code>load()</code>
- method. So creating a file-based configuration object and loading its
- content can be done in a single step.
- </p>
- </subsection>
-
- <subsection name="Saving">
- <p>
- Saving is implemented analogously to loading: There is a no argument
- <code>save()</code> method that will use the internal file name. Then
- for each <code>load()</code> method a corresponding <code>save()</code>
- 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"><code>PropertiesConfiguration</code></a>)
- could look as follows:
- </p>
-<source>
-PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
-config.setProperty("colors.background", "#000000);
-config.save();
-</source>
- <p>
- You can also save a copy of the configuration to another file:
- </p>
-<source>
-PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
-config.setProperty("colors.background", "#000000);
-config.save("usergui.backup.properties);
-</source>
- </subsection>
-
- <subsection name="Automatic Saving">
- <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 <code>setAutoSave()</code>
- method as shown in the following example:
- </p>
-<source>
-PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
-config.setAutoSave(true);
-config.setProperty("colors.background", "#000000); // the configuration is saved after this call
-</source>
- <p>
- Be careful with this mode when you have many updates on your
- configuration. This will lead to many I/O operations, too.
- </p>
- </subsection>
-
- <subsection name="Automatic Reloading">
- <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 <em>reloading strategies</em> 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 <code><a href="apidocs/org/apache/commons/configuration/reloading/FileChangedReloadingStrategy.html">FileChangedReloadingStrategy</a></code>.
- It can be set on a file-based configuration as follows:
- </p>
-<source>
-PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
-config.setReloadingStrategy(new FileChangedReloadingStrategy());
-</source>
- <p>
- <code>FileChangedReloadingStrategy</code> works as follows: On every
- property access the configuration checks its associated reloading
- strategy. <code>FileChangedReloadingStrategy</code> 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 <em>refresh delay</em> 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>
- </subsection>
-
- <subsection name="Managed Reloading">
- <p>
- <code>ManagedReloadingStrategy</code> is an alternative to automatic
- reloading. It allows to hot-reload properties on a running application
- but only when requested by admin. The <code>refresh()</code> 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 :
-<source>
-<![CDATA[
-<!-- 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>
+ <properties>
+ <title>Mutli-tenant Configurations</title>
+ <author email="rgoers@apache.org">Ralph Goers</author>
+ </properties>
+
+ <body>
+ <section name="Multi-tenant Configurations">
+ <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>
+
+ <subsection name="MultiFileHierarchicalConfiguration">
+ <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>
+ </subsection>
+ <subsection name="DynamicCombinedConfiguration">
+ <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>
+ </subsection>
+ <subsection name="Sample Configuration">
+ <p>
+ This sample configuration illustrates how to use DynamicCombinedConfiguration
+ in combination with MultiFileHierarchicalConfiguration to create a multi-tenant
+ configuration.
+ </p>
+ <source><![CDATA[
+<?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>
+]]></source>
+ </subsection>
+ <subsection name="PatternSubtreeConfigurationWrapper">
+ <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>
+ <source><![CDATA[
+ <bean id="configurationBuilder"
+ class="org.apache.commons.configuration.DefaultConfigurationBuilder">
+ <property name="fileName">
+ <value>configuration.xml</value>
</property>
-</bean>
-]]>
-</source>
- With this configuration, the JMX console will expose the
- "myApp:bean=configuration" MBean and it's refresh operation.
+ </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>
+]]></source>
</p>
- </subsection>
+ </subsection>
</section>
-</body>
+ </body>
</document>
Propchange: commons/proper/configuration/trunk/xdocs/userguide/howto_multitenant.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: commons/proper/configuration/trunk/xdocs/userguide/howto_multitenant.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: commons/proper/configuration/trunk/xdocs/userguide/howto_multitenant.xml
------------------------------------------------------------------------------
svn:mergeinfo =
Propchange: commons/proper/configuration/trunk/xdocs/userguide/howto_multitenant.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Modified: commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml?rev=719319&r1=719318&r2=719319&view=diff
==============================================================================
--- commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml (original)
+++ commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml Thu Nov 20 10:33:04 2008
@@ -132,6 +132,13 @@
<li><a href="howto_configurationbuilder.html#An_example">An example</a></li>
<li><a href="howto_configurationbuilder.html#Extending_the_configuration_definition_file_format">Extending the configuration definition file format</a></li>
</ul>
+ <li><a href="howto_multitenant.html#Multi-tenant Configurations">Multi-tenant Configurations</a></li>
+ <ul>
+ <li><a href="howto_multitenant.html#MultiFileHierarchicalConfiguration">MultiFileHierarchicalConfiguration</a></li>
+ <li><a href="howto_multitenant.html#DynamicCombinedConfiguration">DynamicCombinedConfiguration</a></li>
+ <li><a href="howto_multitenant.html#Sample Configuration">Sample Configuration</a></li>
+ <li><a href="howto_multitenant.html#PatternSubtreeConfigurationWrapper">PatternSubtreeConfigurationWrapper</a></li>
+ </ul>
<li><a href="howto_events.html#Configuration_Events">Configuration Events</a></li>
<ul>
<li><a href="howto_events.html#Configuration_listeners">Configuration listeners</a></li>