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="rgo...@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>