Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Jakarta Commons Developers List" <commons-dev@jakarta.apache.org>
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r492234 - in
 /jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration:
 AbstractFileConfiguration.java FileConfiguration.java
Date: Wed, 03 Jan 2007 17:39:40 -0000
To: commons-cvs@jakarta.apache.org
From: oheger@apache.org
Message-Id: <20070103173940.BB8931A981A@eris.apache.org>

Author: oheger
Date: Wed Jan  3 09:39:39 2007
New Revision: 492234

URL: http://svn.apache.org/viewvc?view=rev&rev=492234
Log:
CONFIGURATION-246: Javadoc improvements

Modified:
    jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractFileConfiguration.java
    jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/FileConfiguration.java

Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractFileConfiguration.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractFileConfiguration.java?view=diff&rev=492234&r1=492233&r2=492234
==============================================================================
--- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractFileConfiguration.java (original)
+++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractFileConfiguration.java Wed Jan  3 09:39:39 2007
@@ -41,7 +41,7 @@
  * <p>Partial implementation of the <code>FileConfiguration</code> interface.
  * Developpers of file based configuration may want to extend this class,
  * the two methods left to implement are <code>{@link FileConfiguration#load(Reader)}</code>
- * and <code>{@link FileConfiguration#save(Writer)}.</p>
+ * and <code>{@link FileConfiguration#save(Writer)}</code>.</p>
  * <p>This base class already implements a couple of ways to specify the location
  * of the file this configuration is based on. The following possibilities
  * exist:
@@ -548,6 +548,7 @@
      * Return the base path.
      *
      * @return the base path
+     * @see FileConfiguration#getBasePath()
      */
     public String getBasePath()
     {
@@ -555,8 +556,18 @@
     }
 
     /**
-     * Set the base path. Relative configurations are loaded from this path. The
-     * base path can be either a path to a directory or a URL.
+     * Sets the base path. The base path is typically either a path to a
+     * directory or a URL. Together with the value passed to the
+     * <code>setFileName()</code> method it defines the location of the
+     * configuration file to be loaded. The strategies for locating the file are
+     * quite tolerant. For instance if the file name is already an absolute path
+     * or a fully defined URL, the base path will be ignored. The base path can
+     * also be a URL, in which case the file name is interpreted in this URL's
+     * context. Because the base path is used by some of the derived classes for
+     * resolving relative file names it should contain a meaningful value. If
+     * other methods are used for determining the location of the configuration
+     * file (e.g. <code>setFile()</code> or <code>setURL()</code>), the
+     * base path is automatically set.
      *
      * @param basePath the base path.
      */

Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/FileConfiguration.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/FileConfiguration.java?view=diff&rev=492234&r1=492233&r2=492234
==============================================================================
--- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/FileConfiguration.java (original)
+++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/FileConfiguration.java Wed Jan  3 09:39:39 2007
@@ -178,14 +178,28 @@
     void setFileName(String fileName);
 
     /**
-     * Return the base path.
+     * Returns the base path. One way to specify the location of a configuration
+     * source is by setting its base path and its file name. This method returns
+     * this base path. The concrete value returned by this method depends on the
+     * way the location of the configuration file was set. If methods like
+     * <code>setFile()</code> or <code>setURL()</code> were used, the base
+     * path typically points to the parent directory of the configuration file
+     * (e.g. for the URL <code>file:/temp/test.properties</code> the base path
+     * will be <code>file:/temp/</code>). If the base path was explictly set
+     * using <code>setBasePath()</code>, this method will return the exact
+     * value specified here without further modifications.
      *
      * @return the base path
+     * @see AbstractFileConfiguration#setBasePath(String)
      */
     String getBasePath();
 
     /**
-     * Set the base path. Relative configurations are loaded from this path.
+     * Sets the base path. The methods <code>setBasePath()</code> and
+     * <code>setFileName()</code> can be used together to specify the location
+     * of the configuration file to be loaded. If relative file names are to
+     * be resolved (e.g. for the include files supported by
+     * <code>PropertiesConfiguration</code>), this base path will be used.
      *
      * @param basePath the base path.
      */


---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org