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 2013/09/28 21:43:09 UTC
svn commit: r1527241 - in
/commons/proper/configuration/trunk/src/site/xdoc/userguide:
howto_filesystems.xml user_guide.xml
Author: oheger
Date: Sat Sep 28 19:43:09 2013
New Revision: 1527241
URL: http://svn.apache.org/r1527241
Log:
Updated the user's guide regarding file access.
The section about file systems was renamed to "Access to Files". It now also
covers information about file location strategies.
Modified:
commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_filesystems.xml
commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml
Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_filesystems.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_filesystems.xml?rev=1527241&r1=1527240&r2=1527241&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_filesystems.xml (original)
+++ commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_filesystems.xml Sat Sep 28 19:43:09 2013
@@ -19,113 +19,302 @@
<document>
<properties>
- <title>File Systems</title>
+ <title>Access to Files</title>
<author email="rgoers@apache.org">Ralph Goers</author>
</properties>
<body>
- <section name="File Systems">
+ <section name="Access to Files">
+ <p>
+ When working with file-based configurations application code has multiple
+ ways to specify the location of the file to be loaded (refer to
+ <a href="howto_filebased.html">File-based Configurations</a>). If a URL
+ is provided, the source file to be loaded is defined in a pretty
+ unambiguous way. If relative file names or paths are used, situation is less
+ obvious.
+ </p>
+ <p>
+ <em>Commons Configuration</em> provides two mechanisms to customize the
+ way configuration files are accessed:
+ <ul>
+ <li>File systems</li>
+ <li>File location strategies</li>
+ </ul>
+ They are described in the remaining part of this document. But before we
+ dive into details, some background information about fundamental classes
+ involved in file access has to be provided.
+ </p>
+
+ <subsection name="FileHandler and FileLocator">
<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 <code>FileSystem</code> interface so accessing files
- using other mechanisms is possible.
+ Every builder for a file-based configuration is associated with an
+ object of the <a href="../apidocs/org/apache/commons/configuration/io/FileHandler.html">
+ <code>FileHandler</code></a> class. A <code>FileHandler</code> combines
+ information about a file (its location plus some meta data like the
+ encoding) with an object that can actually read or write the file. This
+ is typically a configuration object. <code>FileHandler</code> defines
+ methods for setting and querying properties related to the referenced
+ file. For instance, the location can be set in various ways, e.g. as a
+ URL, as a <code>java.io.File</code> object, as a file path, etc. In
+ addition, there are methods for loading and saving the referenced file.
+ These methods evaluate the stored location information and open a stream
+ to the underlying file. Then they delegate to the associated
+ configuration object to actually perform the IO operation.
</p>
<p>
- Commons Configuration also provides a second FileSystem which allows retrieval using
- <a href="http://commons.apache.org/vfs">Apache Commons VFS</a>. As of this writing
- Commons VFS supports 18 protocols for manipulating files.
+ A <code>FileHandler</code> object is also used under the hood by the
+ parameters object of a file-based configuration builder (see
+ <a href="../apidocs/org/apache/commons/configuration/builder/FileBasedBuilderProperties.html">
+ <code>FileBasedBuilderProperties</code></a>). So an
+ application defining the configuration file to be loaded actually
+ populates the properties of a <code>FileHandler</code> instance. The
+ <code>FileHandler</code> also supports properties which influence the
+ way the file is loaded; the already mentioned <code>FileSystem</code>
+ and <code>FileLocationStrategy</code> properties can be set as well.
+ This is also the most straight-forward way of hooking into the
+ mechanism of accessing a configuration file - by passing customized
+ <code>FileHandler</code> or <code>FileLocationStrategy</code> objects
+ to a parameters object for a file-based configuration builder.
</p>
- <subsection name="Configuration">
<p>
- The FileSystem used by Commons Configuration can be set in one of several ways:
- <ol>
- <li>A system property named "org.apache.commons.configuration.filesystem" can be defined
- with the full class name of the desired <code>FileSystem</code> implementation to set the
- default <code>FileSystem</code>.</li>
- <li><code>FileSystem.setDefaultFilesystem()</code> can be called to directly set the
- default <code>FileSystem</code> implementation.</li>
- <li><code>DefaultConfigurationBuilder.setFileSystem()</code> can be called to set the
- FileSystem implementation. <code>DefaultConfiguratonBuilder</code> will use this for each
- configuration it creates</li>
- <li><code>DefaultConfigurationBuilder</code> can be configured with the <code>FileSystem</code>
- to be used when creating each of the configurations.</li>
- <li>Each Configuration referenced in <code>DefaultConfigurationBuilder's</code>
- configuration can be configured with the <code>FileSystem</code> to use for that
- configuration.</li>
- <li>Call setFileSystem() directly on any Configuration that implements <code>FileSystemBased.</code>
- Both <code>AbstractFileConfiguration</code> and <code>AbstractHierarchicalFileConfiguration</code>
- implement <code>FileSystemBased</code></li>
- </ol>
+ Another important class related to file access is
+ <a href="../apidocs/org/apache/commons/configuration/io/FileLocator.html">
+ <code>FileLocator</code></a>. An instance stores all information
+ required for resolving a file to be accessed. <code>FileHandler</code>
+ uses a <code>FileLocator</code> instance to maintain this part of
+ file-related information. If you need to customize the access to
+ configuration files, you sometimes have to deal with
+ <code>FileLocator</code> objects because the files to be operated on are
+ described in terms of such objects.
+ </p>
+ </subsection>
+
+ <subsection name="File Systems">
+ <p>
+ In its default mode of operation <em>Commons Configuration</em> supports retrieving and storing
+ configuration files either on a local file system or via http. However, <em>Commons
+ Configuration</em> provides support for allowing other File System adapters. All file
+ access is accomplished through the <a href="../apidocs/org/apache/commons/configuration/io/FileSystem.html">
+ <code>FileSystem</code></a> class so accessing files using other mechanisms is possible.
+ </p>
+ <p>
+ <em>Commons Configuration</em> also provides a second <code>FileSystem</code> implementation which allows retrieval using
+ <a href="http://commons.apache.org/vfs">Apache Commons VFS</a>. As of this writing
+ Commons VFS supports 18 protocols for manipulating files.
</p>
<p>
- The example that follows shows how to add <code>FileSystem</code> configuration to
- <code>DefaultConfigurationBuilder</code>.
+ As was already mentioned in the previous section, the
+ <code>FileSystem</code> used by <em>Commons Configuration</em> can be set in
+ the builder's parameter object, together with other properties defining
+ the file to be loaded. When working with
+ <a href="../apidocs/org/apache/commons/configuration/builder/combined/CombinedConfigurationBuilder.html">
+ <code>CombinedConfigurationBuilder</code></a> it is also possible to
+ define the file system in the configuration definition file to be
+ processed by the builder - in both a global way and for each referenced
+ sub configuration. The following listing shows a configuration definition
+ file for a combined builder making use of this functionality. Per
+ default, the <a href="../apidocs/org/apache/commons/configuration/io/VFSFileSystem.html">
+ <code>VFSFileSystem</code></a> is used, but the included XML
+ configuration is loaded via a
+ <a href="../apidocs/org/apache/commons/configuration/io/DefaultFileSystem.html">
+ <code>DefaultFileSystem</code></a> instance:
</p>
<source><![CDATA[
<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"/>
+ <fileSystem config-class="org.apache.commons.configuration.io.VFSFileSystem"/>
</header>
<override>
<xml fileName="settings.xml" config-name="xml">
- <fileSystem config-class="org.apache.commons.configuration.DefaultFileSystem"/>
+ <fileSystem config-class="org.apache.commons.configuration.io.DefaultFileSystem"/>
</xml>
+
+ <!-- Other sources omitted -->
</override>
</configuration>
]]></source>
+ <p>
+ Commons VFS allows options to the underlying file systems being used. <em>Commons Configuration</em>
+ allows applications to provide these by implementing the
+ <a href="../apidocs/org/apache/commons/configuration/io/FileOptionsProvider.html">
+ <code>FileOptionsProvider</code></a> interface
+ and registering the provider with the <code>FileSystem</code>. <code>FileOptionsProvider</code>
+ has a single method that must be implemented, <code>getOptions()</code>, which returns a Map
+ containing the keys and values that the <code>FileSystem</code> might use. The <code>getOptions()</code>
+ method is called as each configuration uses VFS to create a <code>FileOjbect</code> 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 <code>currentUser</code> 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>
</subsection>
- <subsection name="File Options Provider">
- <p>
- Commons VFS allows options to the underlying file systems being used. Commons Configuration
- allows applications to provide these by implementing the <code>FileOptionsProvider</code> interface
- and registering the provider with the <code>FileSystem</code>. <code>FileOptionsProvider</code>
- has a single method that must be implemented, <code>getOptions</code>, which returns a Map
- containing the keys and values that the <code>FileSystem</code> might use. The getOptions
- method is called as each configuration uses VFS to create a <code>FileOjbect</code> 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 <code>currentUser</code> 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>
- </subsection>
- <subsection name="File Reloading Strategy">
- <p>
- The <code><a href="../apidocs/org/apache/commons/configuration/reloading/VFSFileChangedReloadingStrategy.html">VFSFileChangedReloadingStrategy</a></code>
- can be used to cause Configurations accessed via the <code>VFSFileSystem</code> to be
- monitored and reloaded when the files are modified. The example below shows how
- <code>DefaultConfigurationBuilder</code> can be configured to use
- <code>VFSFilChangedReloadingStrategy</code>.
- In the example below both test.properties and settings.xml would be checked for changes
- once per minute.
- </p>
- <source><![CDATA[
-<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>
+
+ <subsection name="File Location Strategies">
+ <p>
+ Before a file can be accessed it has to be located first. In the 1.x
+ versions of <em>Commons Configuration</em>, there was a hard-coded
+ algorithm for looking up configuration files defined by a file name
+ and an optional base path in various places. Starting with version 2.0,
+ it is now possible to adapt this algorithm. The key to this is the
+ <a href="../apidocs/org/apache/commons/configuration/io/FileLocationStrategy.html">
+ <code>FileLocationStrategy</code></a> interface. The interface defines
+ a single method:
+ </p>
+ <source><![CDATA[
+URL locate(FileSystem fileSystem, FileLocator locator);
]]></source>
+ <p>
+ The purpose of this method is to resolve a file described by the passed
+ in <a href="../apidocs/org/apache/commons/configuration/io/FileLocator.html">
+ <code>FileLocator</code></a> object and return a URL for it. If
+ required, the provided <code>FileSystem</code> can be used. The URL
+ yielded by a successful locate operation is directly used to access
+ the affected file. If the file could not be resolved, a
+ <code>FileLocationStrategy</code> implementation should not throw an
+ exception, but return <b>null</b> instead. This allows multiple
+ strategies to be chained so that different locations can be searched for
+ the file one after the other.
+ </p>
+ <p>
+ <em>Commons Configuration</em> ships with a set of standard
+ <code>FileLocationStrategy</code> implementations. They are pretty
+ specialized, meaning that a single implementation focuses on a very
+ specific search algorithm. The true power lies in combining these
+ strategies in a way suitable for an application or use case. The
+ following table describes the available <code>FileLocationStrategy</code>
+ implementations:
+ </p>
+ <p>
+ <table>
+ <tr>
+ <th>Location Strategy class</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td valign="top">
+ <a href="../apidocs/org/apache/commons/configuration/io/ProvidedURLLocationStrategy.html">
+ <code>ProvidedURLLocationStrategy</code></a>
+ </td>
+ <td>
+ Directly returns the URL stored in the passed in
+ <code>FileLocator</code>. Unless an application needs some
+ special URL transformation, a file locator's URL - if defined -
+ can typically be used directly to access a file. So it makes
+ sense to use this strategy at the very beginning of your chain
+ of strategies.
+ </td>
+ </tr>
+ <tr>
+ <td valign="top">
+ <a href="../apidocs/org/apache/commons/configuration/io/FileSystemLocationStrategy.html">
+ <code>FileSystemLocationStrategy</code></a>
+ </td>
+ <td>
+ Passes the base path and the file name stored in the passed in
+ <code>FileLocator</code> to the <code>locateFromURL()</code>
+ method of the current <code>FileSystem</code>. This gives the file
+ system the opportunity to perform a special resolution.
+ </td>
+ </tr>
+ <tr>
+ <td valign="top">
+ <a href="../apidocs/org/apache/commons/configuration/io/AbsoluteNameLocationStrategy.html">
+ <code>AbsoluteNameLocationStrategy</code></a>
+ </td>
+ <td>
+ Checks whether the file name stored in the passed in
+ <code>FileLocator</code> is actually an absolute path name
+ pointing to an existing file. If this is the case, the URL to
+ this file is returned.
+ </td>
+ </tr>
+ <tr>
+ <td valign="top">
+ <a href="../apidocs/org/apache/commons/configuration/io/BasePathLocationStrategy.html">
+ <code>BasePathLocationStrategy</code></a>
+ </td>
+ <td>
+ This strategy creates a concatenation of the base path and file
+ name stored in the passed in <code>FileLocator</code> (of course,
+ only if both are defined). If this results in a path pointing to
+ an existing file, this file's URL is returned.
+ </td>
+ </tr>
+ <tr>
+ <td valign="top">
+ <a href="../apidocs/org/apache/commons/configuration/io/HomeDirectoryLocationStrategy.html">
+ <code>HomeDirectoryLocationStrategy</code></a>
+ </td>
+ <td>
+ Searches for the referenced file in the current system user's home
+ directory. It is also possible to specify a different directory
+ in which the strategy should search; the path to the target
+ directory can be passed to the constructor.
+ </td>
+ </tr>
+ <tr>
+ <td valign="top">
+ <a href="../apidocs/org/apache/commons/configuration/io/ClasspathLocationStrategy.html">
+ <code>ClasspathLocationStrategy</code></a>
+ </td>
+ <td>
+ Interprets the file name stored in the passed in
+ <code>FileLocator</code> as a resource name and tries to look it
+ up on the current classpath.
+ </td>
+ </tr>
+ <tr>
+ <td valign="top">
+ <a href="../apidocs/org/apache/commons/configuration/io/CombinedLocationStrategy.html">
+ <code>CombinedLocationStrategy</code></a>
+ </td>
+ <td>
+ This is a kind of meta strategy which allows combining an arbitrary
+ number of other <code>FileLocationStrategy</code> objects. At
+ construction time a collection with sub strategies has to be
+ passed in. In its implementation of the <code>locate()</code>
+ method, the strategy iterates over all its sub strategies (in the
+ order they were passed to the constructor) until one returns a
+ non <b>null</b> URL. This URL is returned.
+ </td>
+ </tr>
+ </table>
+ </p>
+ <p>
+ As an example, consider that an application wants configuration files
+ to be looked up (in this order)
+ <ul>
+ <li>by their URL</li>
+ <li>by the file system (which will evaluate base path and file name)</li>
+ <li>on the classpath</li>
+ </ul>
+ Then a concrete location strategy could be constructed as follows:
+ </p>
+ <source><![CDATA[
+List<FileLocationStrategy> subs = Arrays.asList(
+ new ProvidedURLLocationStrategy(),
+ new FileSystemLocationStrategy(),
+ new ClasspathLocationStrategy());
+FileLocationStrategy strategy = new CombinedLocationStrategy(subs);
+]]></source>
+ <p>
+ This strategy can now be passed to a file-based configuration builder.
+ If no strategy is passed to a builder, a default one is used. This
+ default strategy is almost identical to the hard-coded search algorithm
+ that was used in earlier versions of <em>Commons Configuration</em>.
+ In fact, the pre-defined basic <code>FileLocationStrategy</code>
+ implementations were extracted from this algorithm.
+ </p>
+ <p>
+ Because the <code>FileLocationStrategy</code> interface is very simple
+ it should be easy to create a custom implementation. The specific
+ search algorithm just has to be coded into the <code>locate()</code>
+ method. Then this custom strategy implementation can be combined with
+ other standard strategies by making use of a
+ <code>CombinedLocationStrategy</code>.
+ </p>
</subsection>
</section>
-
</body>
</document>
Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml?rev=1527241&r1=1527240&r2=1527241&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml (original)
+++ commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml Sat Sep 28 19:43:09 2013
@@ -138,11 +138,11 @@
<li><a href="howto_utilities.html#Interpolation_of_all_variables">Interpolation of all variables</a></li>
<li><a href="howto_utilities.html#Handling_of_runtime_exceptions">Handling of runtime exceptions</a></li>
</ul>
- <li><a href="howto_filesystems.html#File_Systems">File Systems</a></li>
+ <li><a href="howto_filesystems.html">Access to Files</a></li>
<ul>
- <li><a href="howto_filesystems.html#File_Systems#Configuration">Configuration</a></li>
- <li><a href="howto_filesystems.html#File_Systems#File_Options_Provider">File Options Provider</a></li>
- <li><a href="howto_filesystems.html#File_Systems#File_Reloading_Strategy">File Reloading Strategy</a></li>
+ <li><a href="howto_filesystems.html#File_Systems#FileHandler_and_FileLocator">FileHandler and FileLocator</a></li>
+ <li><a href="howto_filesystems.html#File_Systems#File_Systems">File Systems</a></li>
+ <li><a href="howto_filesystems.html#File_Systems#File_Location_Strategies">File Location Strategies</a></li>
</ul>
<li><a href="howto_concurrency.html">Configurations and Concurrent Access</a></li>
<ul>