commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ohe...@apache.org
Subject svn commit: r1527241 - in /commons/proper/configuration/trunk/src/site/xdoc/userguide: howto_filesystems.xml user_guide.xml
Date Sat, 28 Sep 2013 19:43:09 GMT
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>



Mime
View raw message