svn commit: r1234118 - in /commons/proper/configuration/trunk/src: changes/changes.xml main/java/org/apache/commons/configuration/AbstractFileConfiguration.java

[oh...@apache.org]

Author: oheger
Date: Fri Jan 20 20:36:04 2012
New Revision: 1234118

URL: http://svn.apache.org/viewvc?rev=1234118&view=rev
Log:
[CONFIGURATION-463] Javadoc improvements.

Modified:
    commons/proper/configuration/trunk/src/changes/changes.xml
    commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/AbstractFileConfiguration.java

Modified: commons/proper/configuration/trunk/src/changes/changes.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/changes/changes.xml?rev=1234118&r1=1234117&r2=1234118&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/changes/changes.xml (original)
+++ commons/proper/configuration/trunk/src/changes/changes.xml Fri Jan 20 20:36:04 2012
@@ -48,6 +48,10 @@
       <action dev="ebourg" type="add" issue="CONFIGURATION-466">
         Binary literals are now supported (i.e Ob11010001).
       </action>
+      <action dev="oheger" type="update" issue="CONFIGURATION-463">
+        Improved documentation of AbstractFileConfiguration related to load()
+        methods and their impact on the base path.
+      </action>
       <action dev="oheger" type="update" issue="CONFIGURATION-461">
         The project now uses standard Maven directory layout.
       </action>

Modified: commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/AbstractFileConfiguration.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/AbstractFileConfiguration.java?rev=1234118&r1=1234117&r2=1234118&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/AbstractFileConfiguration.java (original)
+++ commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/AbstractFileConfiguration.java Fri Jan 20 20:36:04 2012
@@ -58,6 +58,15 @@ import org.apache.commons.logging.LogFac
  * directory or a URL. It can be set using the {@code setBasePath()}
  * method. The file name, non surprisingly, defines the name of the configuration
  * file.</li></ul></p>
+ * <p>The configuration source to be loaded can be specified using one of the
+ * methods described above. Then the parameterless {@code load()} method can be
+ * called. Alternatively, one of the {@code load()} methods can be used which is
+ * passed the source directly. These methods typically do not change the
+ * internally stored file; however, if the configuration is not yet associated
+ * with a configuration source, the first call to one of the {@code load()}
+ * methods sets the base path and the source URL. This fact has to be taken
+ * into account when calling {@code load()} multiple times with different file
+ * paths.</p>
  * <p>Note that the {@code load()} methods do not wipe out the configuration's
  * content before the new configuration file is loaded. Thus it is very easy to
  * construct a union configuration by simply loading multiple configuration
@@ -231,9 +240,10 @@ implements FileConfiguration, FileSystem
     }
 
     /**
-     * Locate the specified file and load the configuration. This does not
-     * change the source of the configuration (i.e. the internally maintained file name).
-     * Use one of the setter methods for this purpose.
+     * Locate the specified file and load the configuration. If the configuration is
+     * already associated with a source, the current source is not changed.
+     * Otherwise (i.e. this is the first load operation), the source URL and
+     * the base path are set now based on the source to be loaded.
      *
      * @param fileName the name of the file to be loaded
      * @throws ConfigurationException if an error occurs
@@ -261,9 +271,10 @@ implements FileConfiguration, FileSystem
     }
 
     /**
-     * Load the configuration from the specified file. This does not change
-     * the source of the configuration (i.e. the internally maintained file
-     * name). Use one of the setter methods for this purpose.
+     * Load the configuration from the specified file. If the configuration is
+     * already associated with a source, the current source is not changed.
+     * Otherwise (i.e. this is the first load operation), the source URL and
+     * the base path are set now based on the source to be loaded.
      *
      * @param file the file to load
      * @throws ConfigurationException if an error occurs
@@ -285,9 +296,10 @@ implements FileConfiguration, FileSystem
     }
 
     /**
-     * Load the configuration from the specified URL. This does not change the
-     * source of the configuration (i.e. the internally maintained file name).
-     * Use on of the setter methods for this purpose.
+     * Load the configuration from the specified URL. If the configuration is
+     * already associated with a source, the current source is not changed.
+     * Otherwise (i.e. this is the first load operation), the source URL and
+     * the base path are set now based on the source to be loaded.
      *
      * @param url the URL of the file to be loaded
      * @throws ConfigurationException if an error occurs