commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ohe...@apache.org
Subject svn commit: r312488 - /jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/
Date Sun, 09 Oct 2005 18:27:30 GMT
Author: oheger
Date: Sun Oct  9 11:27:12 2005
New Revision: 312488

URL: http://svn.apache.org/viewcvs?rev=312488&view=rev
Log:
Javadoc and Checkstyle

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/ConfigurationMap.java
    jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/DataConfiguration.java
    jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/FileConfiguration.java
    jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/MapConfiguration.java
    jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertiesConfiguration.java
    jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertyConverter.java
    jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLConfiguration.java
    jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLPropertiesConfiguration.java

Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractFileConfiguration.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractFileConfiguration.java?rev=312488&r1=312487&r2=312488&view=diff
==============================================================================
--- 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 Sun Oct  9 11:27:12 2005
@@ -76,20 +76,27 @@
  */
 public abstract class AbstractFileConfiguration extends BaseConfiguration implements FileConfiguration
 {
+    /** Stores the file name.*/
     protected String fileName;
 
+    /** Stores the base path.*/
     protected String basePath;
 
+    /** The auto save flag.*/
     protected boolean autoSave;
 
+    /** Holds a reference to the reloading strategy.*/
     protected ReloadingStrategy strategy;
 
+    /** A lock object for protecting reload operations.*/
     private Object reloadLock = new Object();
 
+    /** Stores the encoding of the configuration file.*/
     private String encoding;
-    
-    private URL sourceURL = null;
-    
+
+    /** Stores the URL from which the configuration file was loaded.*/
+    private URL sourceURL;
+
     /** A counter that prohibits reloading.*/
     private int noReload;
 
@@ -192,7 +199,7 @@
         try
         {
             URL url = ConfigurationUtils.locate(basePath, fileName);
-            
+
             if (url == null)
             {
                 throw new ConfigurationException("Cannot locate configuration source " + fileName);
@@ -298,7 +305,7 @@
      *
      * @param in the input stream
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the load operation
      */
     public void load(InputStream in) throws ConfigurationException
     {
@@ -312,7 +319,7 @@
      * @param in the input stream
      * @param encoding the encoding used. <code>null</code> to use the default encoding
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the load operation
      */
     public void load(InputStream in, String encoding) throws ConfigurationException
     {
@@ -352,7 +359,7 @@
         {
             throw new ConfigurationException("No file name has been set!");
         }
-        
+
         if (sourceURL != null)
         {
             save(sourceURL);
@@ -368,9 +375,9 @@
      * Save the configuration to the specified file. This doesn't change the
      * source of the configuration, use setFileName() if you need it.
      *
-     * @param fileName
+     * @param fileName the file name
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the save operation
      */
     public void save(String fileName) throws ConfigurationException
     {
@@ -398,9 +405,9 @@
      * This doesn't change the source of the configuration, use setURL()
      * if you need it.
      *
-     * @param url
+     * @param url the URL
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the save operation
      */
     public void save(URL url) throws ConfigurationException
     {
@@ -420,9 +427,9 @@
      * automatically if it doesn't exist. This doesn't change the source
      * of the configuration, use {@link #setFile} if you need it.
      *
-     * @param file
+     * @param file the target file
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the save operation
      */
     public void save(File file) throws ConfigurationException
     {
@@ -460,9 +467,9 @@
      * Save the configuration to the specified stream, using the encoding
      * returned by {@link #getEncoding()}.
      *
-     * @param out
+     * @param out the output stream
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the save operation
      */
     public void save(OutputStream out) throws ConfigurationException
     {
@@ -473,9 +480,9 @@
      * Save the configuration to the specified stream, using the specified
      * encoding. If the encoding is null the default encoding is used.
      *
-     * @param out
-     * @param encoding
-     * @throws ConfigurationException
+     * @param out the output stream
+     * @param encoding the encoding to use
+     * @throws ConfigurationException if an error occurs during the save operation
      */
     public void save(OutputStream out, String encoding) throws ConfigurationException
     {
@@ -504,6 +511,8 @@
 
     /**
      * Return the name of the file.
+     *
+     * @return the file name
      */
     public String getFileName()
     {
@@ -525,6 +534,8 @@
 
     /**
      * Return the base path.
+     *
+     * @return the base path
      */
     public String getBasePath()
     {
@@ -534,7 +545,7 @@
     /**
      * 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.
-     * 
+     *
      * @param basePath the base path.
      */
     public void setBasePath(String basePath)
@@ -547,7 +558,7 @@
      * Return the file where the configuration is stored. If the base path is a
      * URL with a protocol different than &quot;file&quot;, the return value
      * will not point to a valid file object.
-     * 
+     *
      * @return the file where the configuration is stored; this can be <b>null</b>
      */
     public File getFile()
@@ -573,7 +584,7 @@
      * Set the file where the configuration is stored. The passed in file is
      * made absolute if it is not yet. Then the file's path component becomes
      * the base path and its name component becomes the file name.
-     * 
+     *
      * @param file the file where the configuration is stored
      */
     public void setFile(File file)
@@ -588,7 +599,7 @@
      * Returns the full path to the file this configuration is based on. The
      * return value is valid only if this configuration is based on a file on
      * the local disk.
-     * 
+     *
      * @return the full path to the configuration file
      */
     public String getPath()
@@ -599,7 +610,7 @@
     /**
      * Sets the location of this configuration as a full path name. The passed
      * in path should represent a valid file name.
-     * 
+     *
      * @param path the full path name of the configuration file
      */
     public void setPath(String path)
@@ -609,13 +620,13 @@
 
     /**
      * Return the URL where the configuration is stored.
-     * 
+     *
      * @return the configuration's location as URL
      */
     public URL getURL()
     {
-        return (sourceURL != null) ? sourceURL :
-            ConfigurationUtils.locate(getBasePath(), getFileName());
+        return (sourceURL != null) ? sourceURL
+                : ConfigurationUtils.locate(getBasePath(), getFileName());
     }
 
     /**
@@ -707,7 +718,7 @@
             }
         }
     }
-    
+
     /**
      * Enters the &quot;No reloading mode&quot;. As long as this mode is active
      * no reloading will be performed. This is necessary for some
@@ -728,7 +739,7 @@
 
     /**
      * Leaves the &quot;No reloading mode&quot;.
-     * 
+     *
      * @see #enterNoReload()
      */
     protected void exitNoReload()
@@ -768,6 +779,8 @@
 
     /**
      * Create the path to the specified file.
+     *
+     * @param file the target file
      */
     private void createPath(File file)
     {
@@ -794,4 +807,4 @@
     {
         this.encoding = encoding;
     }
-}
\ No newline at end of file
+}

Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/ConfigurationMap.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/ConfigurationMap.java?rev=312488&r1=312487&r2=312488&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/ConfigurationMap.java (original)
+++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/ConfigurationMap.java Sun Oct  9 11:27:12 2005
@@ -1,5 +1,5 @@
 /*
- * Copyright 2004 The Apache Software Foundation.
+ * Copyright 2004-2005 The Apache Software Foundation.
  *
  * Licensed under the Apache License, Version 2.0 (the "License")
  * you may not use this file except in compliance with the License.
@@ -28,7 +28,7 @@
  * {@link org.apache.commons.configuration.Configuration}
  * instance to provide a <code>Map</code> interface.</p>
  *
- * @todo This implementation is incomplete. 
+ * @todo This implementation is incomplete.
  *
  * @author <a href="mailto:ricardo.gladwell@btinternet.com">Ricardo Gladwell</a>
  * @version $Revision$, $Date$
@@ -39,7 +39,7 @@
     /**
      * The <code>Configuration</code> wrapped by this class.
      */
-    Configuration configuration = null;
+    Configuration configuration;
 
     /**
      * Creates a new instance of a <code>ConfigurationMap</code>
@@ -82,22 +82,22 @@
 
     static class ConfigurationSet extends AbstractSet
     {
-        private Configuration configuration = null;
+        private Configuration configuration;
 
         private class Entry implements Map.Entry
         {
-            private Object key = null;
-            
+            private Object key;
+
             private Entry(Object key)
             {
                 this.key = key;
             }
-            
+
             public Object getKey()
             {
                 return key;
             }
-            
+
             public Object getValue()
             {
                 return configuration.getProperty((String) key);
@@ -150,7 +150,7 @@
         {
             // Ouch. Now _that_ one is expensive...
             int count = 0;
-            for (Iterator iterator = configuration.getKeys(); iterator.hasNext(); )
+            for (Iterator iterator = configuration.getKeys(); iterator.hasNext();)
             {
                 iterator.next();
                 count++;

Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/DataConfiguration.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/DataConfiguration.java?rev=312488&r1=312487&r2=312488&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/DataConfiguration.java (original)
+++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/DataConfiguration.java Sun Oct  9 11:27:12 2005
@@ -1,5 +1,5 @@
 /*
- * Copyright 2004 The Apache Software Foundation.
+ * Copyright 2004-2005 The Apache Software Foundation.
  *
  * Licensed under the Apache License, Version 2.0 (the "License")
  * you may not use this file except in compliance with the License.
@@ -54,8 +54,15 @@
     /** The default format for dates. */
     public static final String DEFAULT_DATE_FORMAT = "yyyy-MM-dd HH:mm:ss";
 
+    /** Stores the wrapped configuration.*/
     protected Configuration configuration;
 
+    /**
+     * Creates a new instance of <code>DataConfiguration</code> and sets the
+     * wrapped configuration.
+     *
+     * @param configuration the wrapped configuration
+     */
     public DataConfiguration(Configuration configuration)
     {
         this.configuration = configuration;
@@ -63,6 +70,8 @@
 
     /**
      * Return the configuration decorated by this DataConfiguration.
+     *
+     * @return the wrapped configuration
      */
     public Configuration getConfiguration()
     {
@@ -347,6 +356,7 @@
      * an empty array is returned.
      *
      * @param key The configuration key.
+     * @param defaultValue the default value, which will be returned if the property is not found
      * @return The associated byte array if the key is found.
      *
      * @throws ConversionException is thrown if the key maps to an
@@ -496,6 +506,7 @@
      * an empty array is returned.
      *
      * @param key The configuration key.
+     * @param defaultValue the default value, which will be returned if the property is not found
      * @return The associated short array if the key is found.
      *
      * @throws ConversionException is thrown if the key maps to an
@@ -646,6 +657,7 @@
      * an empty array is returned.
      *
      * @param key The configuration key.
+     * @param defaultValue the default value, which will be returned if the property is not found
      * @return The associated int array if the key is found.
      *
      * @throws ConversionException is thrown if the key maps to an
@@ -795,6 +807,7 @@
      * an empty array is returned.
      *
      * @param key The configuration key.
+     * @param defaultValue the default value, which will be returned if the property is not found
      * @return The associated long array if the key is found.
      *
      * @throws ConversionException is thrown if the key maps to an
@@ -944,6 +957,7 @@
      * an empty array is returned.
      *
      * @param key The configuration key.
+     * @param defaultValue the default value, which will be returned if the property is not found
      * @return The associated float array if the key is found.
      *
      * @throws ConversionException is thrown if the key maps to an
@@ -1094,6 +1108,7 @@
      * an empty array is returned.
      *
      * @param key The configuration key.
+     * @param defaultValue the default value, which will be returned if the property is not found
      * @return The associated double array if the key is found.
      *
      * @throws ConversionException is thrown if the key maps to an
@@ -1238,6 +1253,7 @@
      * an empty array is returned.
      *
      * @param key The configuration key.
+     * @param defaultValue the default value, which will be returned if the property is not found
      * @return The associated BigInteger array if the key is found.
      *
      * @throws ConversionException is thrown if the key maps to an
@@ -1348,6 +1364,7 @@
      * an empty array is returned.
      *
      * @param key The configuration key.
+     * @param defaultValue the default value, which will be returned if the property is not found
      * @return The associated BigDecimal array if the key is found.
      *
      * @throws ConversionException is thrown if the key maps to an
@@ -1503,6 +1520,7 @@
      * If the key doesn't map to an existing object an empty array is returned.
      *
      * @param key The configuration key.
+     * @param defaultValue the default value, which will be returned if the property is not found
      * @return The associated URL array if the key is found.
      *
      * @throws ConversionException is thrown if the key maps to an
@@ -1775,6 +1793,7 @@
      * If the key doesn't map to an existing object an empty array is returned.
      *
      * @param key The configuration key.
+     * @param defaultValue the default value, which will be returned if the property is not found
      * @return The associated Date array if the key is found.
      *
      * @throws ConversionException is thrown if the key maps to an
@@ -2069,6 +2088,7 @@
      * If the key doesn't map to an existing object an empty array is returned.
      *
      * @param key The configuration key.
+     * @param defaultValue the default value, which will be returned if the property is not found
      * @return The associated Calendar array if the key is found.
      *
      * @throws ConversionException is thrown if the key maps to an
@@ -2109,6 +2129,8 @@
     /**
      * Returns the date format specified by the user in the DATE_FORMAT_KEY
      * property, or the default format otherwise.
+     *
+     * @return the default date format
      */
     private String getDefaultDateFormat()
     {
@@ -2254,6 +2276,7 @@
      * an empty array is returned.
      *
      * @param key The configuration key.
+     * @param defaultValue the default value, which will be returned if the property is not found
      * @return The associated Locale array if the key is found.
      *
      * @throws ConversionException is thrown if the key maps to an
@@ -2411,6 +2434,7 @@
      * an empty array is returned.
      *
      * @param key The configuration key.
+     * @param defaultValue the default value, which will be returned if the property is not found
      * @return The associated Color array if the key is found.
      *
      * @throws ConversionException is thrown if the key maps to an

Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/FileConfiguration.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/FileConfiguration.java?rev=312488&r1=312487&r2=312488&view=diff
==============================================================================
--- 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 Sun Oct  9 11:27:12 2005
@@ -1,5 +1,5 @@
 /*
- * Copyright 2004 The Apache Software Foundation.
+ * Copyright 2004-2005 The Apache Software Foundation.
  *
  * Licensed under the Apache License, Version 2.0 (the "License")
  * you may not use this file except in compliance with the License.
@@ -38,7 +38,7 @@
      * Load the configuration from the underlying URL. If the URL is not
      * specified, it attempts to locate the specified file name.
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the load operation
      */
     void load() throws ConfigurationException;
 
@@ -47,7 +47,7 @@
      *
      * @param fileName the name of the file loaded
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the load operation
      */
     void load(String fileName) throws ConfigurationException;
 
@@ -56,7 +56,7 @@
      *
      * @param file the loaded file
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the load operation
      */
     void load(File file) throws ConfigurationException;
 
@@ -65,7 +65,7 @@
      *
      * @param url the URL of the file loaded
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the load operation
      */
     void load(URL url) throws ConfigurationException;
 
@@ -75,7 +75,7 @@
      *
      * @param in the input stream
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the load operation
      */
     void load(InputStream in) throws ConfigurationException;
 
@@ -86,7 +86,7 @@
      * @param in the input stream
      * @param encoding the encoding used. <code>null</code> to use the default encoding
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the load operation
      */
     void load(InputStream in, String encoding) throws ConfigurationException;
 
@@ -95,41 +95,41 @@
      *
      * @param in the reader
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the load operation
      */
     void load(Reader in) throws ConfigurationException;
 
     /**
      * Save the configuration.
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the save operation
      */
     void save() throws ConfigurationException;
 
     /**
      * Save the configuration to the specified file.
      *
-     * @param fileName
+     * @param fileName the name of the file to be saved
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the save operation
      */
     void save(String fileName) throws ConfigurationException;
 
     /**
      * Save the configuration to the specified file.
      *
-     * @param file
+     * @param file specifies the file to be saved
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the save operation
      */
     void save(File file) throws ConfigurationException;
 
     /**
      * Save the configuration to the specified URL if it's a file URL.
      *
-     * @param url
+     * @param url the URL
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the save operation
      */
     void save(URL url) throws ConfigurationException;
 
@@ -137,9 +137,9 @@
      * Save the configuration to the specified stream, using the encoding
      * returned by {@link #getEncoding()}.
      *
-     * @param out
+     * @param out the output stream
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the save operation
      */
     void save(OutputStream out) throws ConfigurationException;
 
@@ -147,9 +147,9 @@
      * Save the configuration to the specified stream, using the specified
      * encoding. If the encoding is null the default encoding is used.
      *
-     * @param out
-     * @param encoding
-     * @throws ConfigurationException
+     * @param out the output stream
+     * @param encoding the encoding to be used
+     * @throws ConfigurationException if an error occurs during the save operation
      */
     void save(OutputStream out, String encoding) throws ConfigurationException;
 
@@ -158,12 +158,14 @@
      *
      * @param out the writer
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs during the save operation
      */
     void save(Writer out) throws ConfigurationException;
 
     /**
      * Return the name of the file.
+     *
+     * @return the file name
      */
     String getFileName();
 
@@ -176,6 +178,8 @@
 
     /**
      * Return the base path.
+     *
+     * @return the base path
      */
     String getBasePath();
 
@@ -188,30 +192,34 @@
 
     /**
      * Return the file where the configuration is stored.
+     *
+     * @return the configuration file
      */
     File getFile();
 
     /**
      * Set the file where the configuration is stored.
      *
-     * @param file
+     * @param file the file
      */
     void setFile(File file);
 
     /**
      * Return the URL where the configuration is stored.
+     *
+     * @return the URL of the configuration
      */
     URL getURL();
 
     /**
      * The URL where the configuration is stored.
      *
-     * @param url
+     * @param url the URL
      */
     void setURL(URL url);
 
     /**
-     * Enable of disable the automatical saving of modified properties to the disk.
+     * Enable or disable the automatical saving of modified properties to the disk.
      *
      * @param autoSave <code>true</code> to enable, <code>false</code> to disable
      * @since 1.1
@@ -229,6 +237,7 @@
     /**
      * Return the reloading strategy.
      *
+     * @return the reloading strategy currently used
      * @since 1.1
      */
     ReloadingStrategy getReloadingStrategy();
@@ -236,6 +245,7 @@
     /**
      * Set the reloading strategy.
      *
+     * @param strategy the reloading strategy to use
      * @since 1.1
      */
     void setReloadingStrategy(ReloadingStrategy strategy);
@@ -251,6 +261,7 @@
      * Return the encoding used to store the configuration file. If the value
      * is null the default encoding is used.
      *
+     * @return the current encoding
      * @since 1.1
      */
     String getEncoding();
@@ -259,6 +270,7 @@
      * Set the encoding used to store the configuration file. Set the encoding
      * to null to use the default encoding.
      *
+     * @param encoding the encoding to use
      * @since 1.1
      */
     void setEncoding(String encoding);

Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/MapConfiguration.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/MapConfiguration.java?rev=312488&r1=312487&r2=312488&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/MapConfiguration.java (original)
+++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/MapConfiguration.java Sun Oct  9 11:27:12 2005
@@ -38,7 +38,7 @@
      * used to store the configuration properties, any change will also affect
      * the Map.
      *
-     * @param map
+     * @param map the map
      */
     public MapConfiguration(Map map)
     {
@@ -47,6 +47,8 @@
 
     /**
      * Return the Map decorated by this configuration.
+     *
+     * @return the map this configuration is based onto
      */
     public Map getMap()
     {

Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertiesConfiguration.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertiesConfiguration.java?rev=312488&r1=312487&r2=312488&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertiesConfiguration.java (original)
+++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertiesConfiguration.java Sun Oct  9 11:27:12 2005
@@ -154,6 +154,18 @@
     private static final char[] WHITE_SPACE = new char[] { ' ', '\t', '\f' };
 
     /**
+     * The default encoding (ISO-8859-1 as specified by
+     * http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html)
+     */
+    private static final String DEFAULT_ENCODING = "ISO-8859-1";
+
+    /** Constant for the radix of hex numbers.*/
+    private static final int HEX_RADIX = 16;
+
+    /** Constant for the length of a unicode literal.*/
+    private static final int UNICODE_LEN = 4;
+
+    /**
      * This is the name of the property that can point to other
      * properties file for including other properties files.
      */
@@ -165,11 +177,6 @@
     /** Comment header of the .properties file */
     private String header;
 
-    /**
-     * The default encoding (ISO-8859-1 as specified by http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html)
-     */
-    private static final String DEFAULT_ENCODING = "ISO-8859-1";
-
     // initialization block to set the encoding before loading the file in the constructors
     {
         setEncoding(DEFAULT_ENCODING);
@@ -271,6 +278,7 @@
     /**
      * Return the comment header.
      *
+     * @return the comment header
      * @since 1.1
      */
     public String getHeader()
@@ -281,6 +289,7 @@
     /**
      * Set the comment header.
      *
+     * @param header the header to use
      * @since 1.1
      */
     public void setHeader(String header)
@@ -296,7 +305,7 @@
      *
      * @param in An InputStream.
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs
      */
     public synchronized void load(Reader in) throws ConfigurationException
     {
@@ -357,6 +366,7 @@
      * Save the configuration to the specified stream.
      *
      * @param writer the output stream used to save the configuration
+     * @throws ConfigurationException if an error occurs
      */
     public void save(Writer writer) throws ConfigurationException
     {
@@ -445,7 +455,7 @@
          *
          * @return A string containing a property value or null
          *
-         * @throws IOException
+         * @throws IOException in case of an I/O error
          */
         public String readProperty() throws IOException
         {
@@ -481,19 +491,22 @@
             }
             return buffer.toString();
         }
-        
+
         /**
          * Checks if the passed in line should be combined with the following.
          * This is true, if the line ends with an odd number of backslashes.
-         * 
+         *
          * @param line the line
          * @return a flag if the lines should be combined
          */
         private static boolean checkCombineLines(String line)
         {
             int bsCount = 0;
-            for (int idx = line.length()-1; idx >= 0 && line.charAt(idx) == '\\'; idx--, bsCount++)
-                ;
+            for (int idx = line.length() - 1; idx >= 0 && line.charAt(idx) == '\\'; idx--)
+            {
+                bsCount++;
+            }
+
             return bsCount % 2 == 1;
         }
     } // class PropertiesReader
@@ -503,12 +516,14 @@
      */
     public static class PropertiesWriter extends FilterWriter
     {
+        /** The delimiter for multi-valued properties.*/
         private char delimiter;
 
         /**
          * Constructor.
          *
          * @param writer a Writer object providing the underlying stream
+         * @param delimiter the delimiter character for multi-valued properties
          */
         public PropertiesWriter(Writer writer, char delimiter)
         {
@@ -519,9 +534,9 @@
         /**
          * Write a property.
          *
-         * @param key
-         * @param value
-         * @throws IOException
+         * @param key the key of the property
+         * @param value the value of the property
+         * @throws IOException if an I/O error occurs
          */
         public void writeProperty(String key, Object value) throws IOException
         {
@@ -554,8 +569,8 @@
         /**
          * Write a comment.
          *
-         * @param comment
-         * @throws IOException
+         * @param comment the comment to write
+         * @throws IOException if an I/O error occurs
          */
         public void writeComment(String comment) throws IOException
         {
@@ -565,6 +580,8 @@
         /**
          * Escape the separators in the key.
          *
+         * @param key the key
+         * @return the escaped key
          * @since 1.2
          */
         private String escapeKey(String key)
@@ -599,7 +616,8 @@
      * drop escaped separators (i.e '\,').
      *
      * @param str  the <code>String</code> to unescape, may be null
-     *
+     * @param delimiter the delimiter for multi-valued properties
+     * @return the processed string
      * @throws IllegalArgumentException if the Writer is <code>null</code>
      */
     protected static String unescapeJava(String str, char delimiter)
@@ -610,7 +628,7 @@
         }
         int sz = str.length();
         StringBuffer out = new StringBuffer(sz);
-        StringBuffer unicode = new StringBuffer(4);
+        StringBuffer unicode = new StringBuffer(UNICODE_LEN);
         boolean hadSlash = false;
         boolean inUnicode = false;
         for (int i = 0; i < sz; i++)
@@ -621,13 +639,13 @@
                 // if in unicode, then we're reading unicode
                 // values in somehow
                 unicode.append(ch);
-                if (unicode.length() == 4)
+                if (unicode.length() == UNICODE_LEN)
                 {
                     // unicode now contains the four hex digits
                     // which represents our unicode character
                     try
                     {
-                        int value = Integer.parseInt(unicode.toString(), 16);
+                        int value = Integer.parseInt(unicode.toString(), HEX_RADIX);
                         out.append((char) value);
                         unicode.setLength(0);
                         inUnicode = false;
@@ -646,39 +664,50 @@
                 // handle an escaped value
                 hadSlash = false;
 
-                if (ch=='\\'){
+                if (ch == '\\')
+                {
                     out.append('\\');
                 }
-                else if (ch=='\''){
+                else if (ch == '\'')
+                {
                     out.append('\'');
                 }
-                else if (ch=='\"'){
+                else if (ch == '\"')
+                {
                     out.append('"');
                 }
-                else if (ch=='r'){
+                else if (ch == 'r')
+                {
                     out.append('\r');
                 }
-                else if (ch=='f'){
+                else if (ch == 'f')
+                {
                     out.append('\f');
                 }
-                else if (ch=='t'){
+                else if (ch == 't')
+                {
                     out.append('\t');
                 }
-                else if (ch=='n'){
+                else if (ch == 'n')
+                {
                     out.append('\n');
                 }
-                else if (ch=='b'){
+                else if (ch == 'b')
+                {
                     out.append('\b');
                 }
-                else if (ch==delimiter){
+                else if (ch == delimiter)
+                {
                     out.append('\\');
                     out.append(delimiter);
                 }
-                else if (ch=='u'){
-                    //                  uh-oh, we're in unicode country....
+                else if (ch == 'u')
+                {
+                    // uh-oh, we're in unicode country....
                     inUnicode = true;
                 }
-                else {
+                else
+                {
                     out.append(ch);
                 }
 
@@ -705,6 +734,8 @@
     /**
      * Parse a property line and return the key and the value in an array.
      *
+     * @param line the line to parse
+     * @return an array with the property's key and value
      * @since 1.2
      */
     private String[] parseProperty(String line)
@@ -808,7 +839,7 @@
      * is encountered. It tries to resolve relative file names based on the
      * current base path. If this fails, a resolution based on the location of
      * this properties file is tried.
-     * 
+     *
      * @param fileName the name of the file to load
      * @throws ConfigurationException if loading fails
      */

Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertyConverter.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertyConverter.java?rev=312488&r1=312487&r2=312488&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertyConverter.java (original)
+++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertyConverter.java Sun Oct  9 11:27:12 2005
@@ -1,5 +1,5 @@
 /*
- * Copyright 2004 The Apache Software Foundation.
+ * Copyright 2004-2005 The Apache Software Foundation.
  *
  * Licensed under the Apache License, Version 2.0 (the "License")
  * you may not use this file except in compliance with the License.
@@ -48,11 +48,18 @@
 {
     /** Constant for the list delimiter escaping character.*/
     static final String LIST_ESCAPE = "\\";
-    
+
+    /** Constant for the prefix of hex numbers.*/
+    private static final String HEX_PREFIX = "0x";
+
+    /** Constant for the radix of hex numbers.*/
+    private static final int HEX_RADIX = 16;
+
     /**
      * Convert the specified object into a Boolean.
      *
      * @param value the value to convert
+     * @return the converted value
      * @throws ConversionException thrown if the value cannot be converted to a boolean
      */
     public static Boolean toBoolean(Object value) throws ConversionException
@@ -80,6 +87,7 @@
      * Convert the specified object into a Byte.
      *
      * @param value the value to convert
+     * @return the converted value
      * @throws ConversionException thrown if the value cannot be converted to a byte
      */
     public static Byte toByte(Object value) throws ConversionException
@@ -93,9 +101,9 @@
             try
             {
                 String string = (String) value;
-                if (string.startsWith("0x"))
+                if (string.startsWith(HEX_PREFIX))
                 {
-                    return new Byte((byte) Integer.parseInt(string.substring(2), 16));
+                    return new Byte((byte) Integer.parseInt(string.substring(2), HEX_RADIX));
                 }
                 else
                 {
@@ -117,6 +125,7 @@
      * Convert the specified object into a Short.
      *
      * @param value the value to convert
+     * @return the converted value
      * @throws ConversionException thrown if the value cannot be converted to a short
      */
     public static Short toShort(Object value) throws ConversionException
@@ -130,9 +139,9 @@
             try
             {
                 String string = (String) value;
-                if (string.startsWith("0x"))
+                if (string.startsWith(HEX_PREFIX))
                 {
-                    return new Short((short) Integer.parseInt(string.substring(2), 16));
+                    return new Short((short) Integer.parseInt(string.substring(2), HEX_RADIX));
                 }
                 else
                 {
@@ -155,6 +164,7 @@
      * Convert the specified object into an Integer.
      *
      * @param value the value to convert
+     * @return the converted value
      * @throws ConversionException thrown if the value cannot be converted to an integer
      */
     public static Integer toInteger(Object value) throws ConversionException
@@ -168,9 +178,9 @@
             try
             {
                 String string = (String) value;
-                if (string.startsWith("0x"))
+                if (string.startsWith(HEX_PREFIX))
                 {
-                    return new Integer((int) Long.parseLong(string.substring(2), 16));
+                    return new Integer((int) Long.parseLong(string.substring(2), HEX_RADIX));
                 }
                 else
                 {
@@ -192,6 +202,7 @@
      * Convert the specified object into a Long.
      *
      * @param value the value to convert
+     * @return the converted value
      * @throws ConversionException thrown if the value cannot be converted to a Long
      */
     public static Long toLong(Object value) throws ConversionException
@@ -205,9 +216,9 @@
             try
             {
                 String string = (String) value;
-                if (string.startsWith("0x"))
+                if (string.startsWith(HEX_PREFIX))
                 {
-                    return new Long(new BigInteger(string.substring(2), 16).longValue());
+                    return new Long(new BigInteger(string.substring(2), HEX_RADIX).longValue());
                 }
                 else
                 {
@@ -229,6 +240,7 @@
      * Convert the specified object into a Float.
      *
      * @param value the value to convert
+     * @return the converted value
      * @throws ConversionException thrown if the value cannot be converted to a Float
      */
     public static Float toFloat(Object value) throws ConversionException
@@ -258,6 +270,7 @@
      * Convert the specified object into a Double.
      *
      * @param value the value to convert
+     * @return the converted value
      * @throws ConversionException thrown if the value cannot be converted to a Double
      */
     public static Double toDouble(Object value) throws ConversionException
@@ -287,6 +300,7 @@
      * Convert the specified object into a BigInteger.
      *
      * @param value the value to convert
+     * @return the converted value
      * @throws ConversionException thrown if the value cannot be converted to a BigInteger
      */
     public static BigInteger toBigInteger(Object value) throws ConversionException
@@ -300,9 +314,9 @@
             try
             {
                 String string = (String) value;
-                if (string.startsWith("0x"))
+                if (string.startsWith(HEX_PREFIX))
                 {
-                    return new BigInteger(string.substring(2), 16);
+                    return new BigInteger(string.substring(2), HEX_RADIX);
                 }
                 else
                 {
@@ -324,6 +338,7 @@
      * Convert the specified object into a BigDecimal.
      *
      * @param value the value to convert
+     * @return the converted value
      * @throws ConversionException thrown if the value cannot be converted to a BigDecimal
      */
     public static BigDecimal toBigDecimal(Object value) throws ConversionException
@@ -353,6 +368,7 @@
      * Convert the specified object into an URL.
      *
      * @param value the value to convert
+     * @return the converted value
      * @throws ConversionException thrown if the value cannot be converted to an URL
      */
     public static URL toURL(Object value) throws ConversionException
@@ -382,6 +398,7 @@
      * Convert the specified object into a Locale.
      *
      * @param value the value to convert
+     * @return the converted value
      * @throws ConversionException thrown if the value cannot be converted to a Locale
      */
     public static Locale toLocale(Object value) throws ConversionException
@@ -422,6 +439,7 @@
      *
      * @param s          the string to split
      * @param delimiter  the delimiter
+     * @return a list with the single tokens
      */
     public static List split(String s, char delimiter)
     {
@@ -470,14 +488,14 @@
 
         return list;
     }
-    
+
     /**
      * Escapes the delimiters that might be contained in the given string. This
      * method ensures that list delimiter characters that are part of a
      * property's value are correctly escaped when a configuration is saved to a
      * file. Otherwise when loaded again the property will be treated as a list
      * property.
-     * 
+     *
      * @param s the string with the value
      * @param delimiter the list delimiter to use
      * @return the correctly esaped string
@@ -499,6 +517,7 @@
      * </ul>
      *
      * @param value the value to convert
+     * @return the converted value
      * @throws ConversionException thrown if the value cannot be converted to a Color
      */
     public static Color toColor(Object value) throws ConversionException
@@ -544,10 +563,11 @@
     }
 
     /**
-     * Convert the specified object into a Calendar.
+     * Convert the specified object into a Date.
      *
      * @param value  the value to convert
      * @param format the DateFormat pattern to parse String values
+     * @return the converted value
      * @throws ConversionException thrown if the value cannot be converted to a Calendar
      */
     public static Date toDate(Object value, String format) throws ConversionException
@@ -582,6 +602,7 @@
      *
      * @param value  the value to convert
      * @param format the DateFormat pattern to parse String values
+     * @return the converted value
      * @throws ConversionException thrown if the value cannot be converted to a Calendar
      */
     public static Calendar toCalendar(Object value, String format) throws ConversionException
@@ -628,6 +649,7 @@
      *
      * @param value     the value to "split"
      * @param delimiter the delimiter for String values
+     * @return an iterator for accessing the single values
      */
     public static Iterator toIterator(Object value, char delimiter)
     {
@@ -670,5 +692,4 @@
             return new SingletonIterator(value);
         }
     }
-
 }

Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLConfiguration.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLConfiguration.java?rev=312488&r1=312487&r2=312488&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLConfiguration.java (original)
+++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLConfiguration.java Sun Oct  9 11:27:12 2005
@@ -56,21 +56,21 @@
 /**
  * <p>A specialized hierarchical configuration class that is able to parse XML
  * documents.</p>
- * 
+ *
  * <p>The parsed document will be stored keeping its structure. The class also
  * tries to preserve as much information from the loaded XML document as
  * possible, including comments and processing instructions. These will be
  * contained in documents created by the <code>save()</code> methods, too.</p>
- * 
+ *
  * <p>Like other file based configuration classes this class maintains the name
  * and path to the loaded configuration file. These properties can be altered
  * using several setter methods, but they are not modified by <code>save()</code>
  * and <code>load()</code> methods. If XML documents contain relative paths to
  * other documents (e.g. to a DTD), these references are resolved based on the
  * path set for this configuration.</p>
- * 
+ *
  * @since commons-configuration 1.0
- * 
+ *
  * @author J&ouml;rg Schaible
  * @author <a href="mailto:oliver.heger@t-online.de">Oliver Heger </a>
  * @version $Revision$, $Date$
@@ -80,6 +80,7 @@
     /** Constant for the default root element name. */
     private static final String DEFAULT_ROOT_NAME = "configuration";
 
+    /** A helper object for implementing the file configuration interface. */
     private FileConfigurationDelegate delegate = new FileConfigurationDelegate();
 
     /** The document from this configuration's data source. */
@@ -87,13 +88,13 @@
 
     /** Stores the name of the root element. */
     private String rootElementName;
-    
+
     /** Stores the document builder that should be used for loading.*/
     private DocumentBuilder documentBuilder;
-    
+
     /** Stores a flag whether DTD validation should be performed.*/
     private boolean validating;
-    
+
     /**
      * Creates a new instance of <code>XMLConfiguration</code>.
      */
@@ -105,7 +106,7 @@
     /**
      * Creates a new instance of <code>XMLConfiguration</code>.
      * The configuration is loaded from the specified file
-     * 
+     *
      * @param fileName the name of the file to load
      * @throws ConfigurationException if the file cannot be loaded
      */
@@ -119,7 +120,7 @@
     /**
      * Creates a new instance of <code>XMLConfiguration</code>.
      * The configuration is loaded from the specified file.
-     * 
+     *
      * @param file the file
      * @throws ConfigurationException if an error occurs while loading the file
      */
@@ -136,7 +137,7 @@
     /**
      * Creates a new instance of <code>XMLConfiguration</code>.
      * The configuration is loaded from the specified URL.
-     * 
+     *
      * @param url the URL
      * @throws ConfigurationException if loading causes an error
      */
@@ -152,7 +153,7 @@
      * from a XML document, the name of this document's root element is
      * returned. Otherwise it is possible to set a name for the root element
      * that will be used when this configuration is stored.
-     * 
+     *
      * @return the name of the root element
      */
     public String getRootElementName()
@@ -176,7 +177,7 @@
      * exception is thrown. Whether this configuration has been loaded from an
      * XML document or not can be found out using the <code>getDocument()</code>
      * method.
-     * 
+     *
      * @param name the name of the root element
      */
     public void setRootElementName(String name)
@@ -193,7 +194,7 @@
      * Returns the <code>DocumentBuilder</code> object that is used for
      * loading documents. If no specific builder has been set, this method
      * returns <b>null</b>.
-     * 
+     *
      * @return the <code>DocumentBuilder</code> for loading new documents
      * @since 1.2
      */
@@ -207,7 +208,7 @@
      * documents. This method makes it possible to specify the exact document
      * builder. So an application can create a builder, configure it for its
      * special needs, and then pass it to this method.
-     * 
+     *
      * @param documentBuilder the document builder to be used; if undefined, a
      * default builder will be used
      * @since 1.2
@@ -219,6 +220,7 @@
 
     /**
      * Returns the value of the validating flag.
+     *
      * @return the validating flag
      * @since 1.2
      */
@@ -231,7 +233,9 @@
      * Sets the value of the validating flag. This flag determines whether
      * DTD validation should be performed when loading XML documents. This
      * flag is evaluated only if no custom <code>DocumentBuilder</code> was set.
+     *
      * @param validating the validating flag
+     * @since 1.2
      */
     public void setValidating(boolean validating)
     {
@@ -242,7 +246,7 @@
      * Returns the XML document this configuration was loaded from. The return
      * value is <b>null</b> if this configuration was not loaded from a XML
      * document.
-     * 
+     *
      * @return the XML document this configuration was loaded from
      */
     public Document getDocument()
@@ -251,7 +255,10 @@
     }
 
     /**
-     * @inheritDoc
+     * Adds a property to this configuration.
+     *
+     * @param key the key of the property
+     * @param obj the property's value
      */
     protected void addPropertyDirect(String key, Object obj)
     {
@@ -260,7 +267,9 @@
     }
 
     /**
-     * @inheritDoc
+     * Removes the property with the given key.
+     *
+     * @param key the key of the property to remove
      */
     public void clearProperty(String key)
     {
@@ -269,14 +278,16 @@
     }
 
     /**
-     * @inheritDoc
+     * Removes all properties in the specified sub tree.
+     *
+     * @param key the key of the properties to be removed
      */
     public void clearTree(String key)
     {
         super.clearTree(key);
         delegate.possiblySave();
     }
-    
+
     /**
      * Removes all properties from this configuration. If this configuration
      * was loaded from a file, the associated DOM document is also cleared.
@@ -286,9 +297,12 @@
         super.clear();
         document = null;
     }
-    
+
     /**
-     * @inheritDoc
+     * Sets the value of the specified property.
+     *
+     * @param key the key of the property
+     * @param value the new value
      */
     public void setProperty(String key, Object value)
     {
@@ -298,7 +312,7 @@
 
     /**
      * Initializes this configuration from an XML document.
-     * 
+     *
      * @param document the document to be parsed
      * @param elemRefs a flag whether references to the XML elements should be set
      */
@@ -310,7 +324,7 @@
     /**
      * Helper method for building the internal storage hierarchy. The XML
      * elements are transformed into node objects.
-     * 
+     *
      * @param node the actual node
      * @param element the actual XML element
      * @param elemRefs a flag whether references to the XML elements should be set
@@ -326,8 +340,8 @@
             if (w3cNode instanceof Element)
             {
                 Element child = (Element) w3cNode;
-                Node childNode = new XMLNode(child.getTagName(), 
-                        (elemRefs) ? child : null);
+                Node childNode = new XMLNode(child.getTagName(),
+                        elemRefs ? child : null);
                 constructHierarchy(childNode, child, elemRefs);
                 node.addChild(childNode);
                 handleDelimiters(node, childNode);
@@ -348,7 +362,7 @@
     /**
      * Helper method for constructing node objects for the attributes of the
      * given XML element.
-     * 
+     *
      * @param node the actual node
      * @param element the actual XML element
      * @param elemRefs a flag whether references to the XML elements should be set
@@ -365,18 +379,18 @@
                 for (Iterator it = PropertyConverter.split(attr.getValue(), getDelimiter()).iterator(); it.hasNext();)
                 {
                     Node child = new XMLNode(ConfigurationKey.constructAttributeKey(attr.getName()),
-                            (elemRefs) ? element : null);
+                            elemRefs ? element : null);
                     child.setValue(it.next());
                     node.addChild(child);
                 }
             }
         }
     }
-    
+
     /**
      * Deals with elements whose value is a list. In this case multiple child
      * elements must be added.
-     * 
+     *
      * @param parent the parent element
      * @param child the child element
      */
@@ -406,7 +420,7 @@
             }
         }
     }
-    
+
     /**
      * Creates the <code>DocumentBuilder</code> to be used for loading files.
      * This implementation checks whether a specific
@@ -414,7 +428,7 @@
      * one is used. Otherwise a default builder is created. Depending on the
      * value of the validating flag this builder will be a validating or a non
      * validating <code>DocumentBuilder</code>.
-     * 
+     *
      * @return the <code>DocumentBuilder</code> for loading configuration
      * files
      * @throws ParserConfigurationException if an error occurs
@@ -451,7 +465,7 @@
 
     /**
      * Creates a DOM document from the internal tree of configuration nodes.
-     * 
+     *
      * @return the new document
      * @throws ConfigurationException if an error occurs
      */
@@ -485,7 +499,7 @@
     /**
      * Creates a new node object. This implementation returns an instance of the
      * <code>XMLNode</code> class.
-     * 
+     *
      * @param name the node's name
      * @return the new node
      */
@@ -494,6 +508,10 @@
         return new XMLNode(name, null);
     }
 
+    /**
+     * Loads this configuration.
+     * @throws ConfigurationException if an error occurs
+     */
     public void load() throws ConfigurationException
     {
         delegate.load();
@@ -532,13 +550,13 @@
      *
      * @param in An InputStream.
      *
-     * @throws ConfigurationException
+     * @throws ConfigurationException if an error occurs
      */
     public void load(Reader in) throws ConfigurationException
     {
         load(new InputSource(in));
     }
-    
+
     /**
      * Loads a configuration file from the specified input source.
      * @param source the input source
@@ -553,7 +571,7 @@
             {
                 source.setSystemId(sourceURL.toString());
             }
-            
+
             DocumentBuilder builder = createDocumentBuilder();
             Document newDocument = builder.parse(source);
             Document oldDocument = document;
@@ -599,7 +617,7 @@
 
     /**
      * Saves the configuration to the specified writer.
-     * 
+     *
      * @param writer the writer used to save the configuration
      * @throws ConfigurationException if an error occurs
      */
@@ -619,13 +637,13 @@
             throw new ConfigurationException(e.getMessage(), e);
         }
     }
-    
+
     /**
      * Creates a copy of this object. The new configuration object will contain
      * the same properties as the original, but it will lose any connection to a
      * source document (if one exists). This is to avoid race conditions if both
      * the original and the copy are modified and then saved.
-     * 
+     *
      * @return the copy
      */
     public Object clone()
@@ -721,7 +739,7 @@
     {
         delegate.setEncoding(encoding);
     }
-    
+
     public boolean containsKey(String key)
     {
         reload();
@@ -755,7 +773,7 @@
         /**
          * Creates a new instance of <code>XMLNode</code> and initializes it
          * with a name and the corresponding XML element.
-         * 
+         *
          * @param name the node's name
          * @param elem the XML element
          */
@@ -768,7 +786,7 @@
         /**
          * Sets the value of this node. If this node is associated with an XML
          * element, this element will be updated, too.
-         * 
+         *
          * @param value the node's new value
          */
         public void setValue(Object value)
@@ -813,7 +831,7 @@
 
         /**
          * Updates the node's value if it represents an element node.
-         * 
+         *
          * @param value the new value
          */
         private void updateElement(Object value)
@@ -854,7 +872,7 @@
 
         /**
          * Updates the node's value if it represents an attribute.
-         *  
+         *
          */
         private void updateAttribute()
         {
@@ -866,7 +884,7 @@
          * called when the element's text changes. Then all text nodes except
          * for the first are removed. A reference to the first is returned or
          * <b>null </b> if there is no text node at all.
-         * 
+         *
          * @return the first and only text node
          */
         private Text findTextNodeForUpdate()
@@ -919,7 +937,7 @@
 
         /**
          * Creates a new instance of <code>XMLBuilderVisitor</code>
-         * 
+         *
          * @param doc the document to be created
          */
         public XMLBuilderVisitor(Document doc)
@@ -929,7 +947,7 @@
 
         /**
          * Processes the node hierarchy and adds new nodes to the document.
-         * 
+         *
          * @param rootNode the root node
          */
         public void processDocument(Node rootNode)
@@ -938,7 +956,13 @@
         }
 
         /**
-         * @inheritDoc
+         * Inserts a new node. This implementation ensures that the correct
+         * XML element is created and inserted between the given siblings.
+         *
+         * @param newNode the node to insert
+         * @param parent the parent node
+         * @param sibling1 the first sibling
+         * @param sibling2 the second sibling
          */
         protected Object insert(Node newNode, Node parent, Node sibling1, Node sibling2)
         {
@@ -953,7 +977,8 @@
                 Element elem = document.createElement(newNode.getName());
                 if (newNode.getValue() != null)
                 {
-                    elem.appendChild(document.createTextNode(PropertyConverter.escapeDelimiters(newNode.getValue().toString(), getDelimiter())));
+                    elem.appendChild(document.createTextNode(
+                            PropertyConverter.escapeDelimiters(newNode.getValue().toString(), getDelimiter())));
                 }
                 if (sibling2 == null)
                 {
@@ -974,7 +999,7 @@
         /**
          * Helper method for updating the value of the specified node's
          * attribute with the given name.
-         * 
+         *
          * @param node the affected node
          * @param elem the element that is associated with this node
          * @param name the name of the affected attribute
@@ -1017,7 +1042,7 @@
          * Updates the value of the specified attribute of the given node.
          * Because there can be multiple child nodes representing this attribute
          * the new value is determined by iterating over all those child nodes.
-         * 
+         *
          * @param node the affected node
          * @param name the name of the attribute
          */
@@ -1031,7 +1056,7 @@
 
         /**
          * Helper method for accessing the element of the specified node.
-         * 
+         *
          * @param node the node
          * @return the element of this node
          */
@@ -1042,6 +1067,11 @@
         }
     }
 
+    /**
+     * A special implementation of the <code>FileConfiguration</code> interface that is
+     * used internally to implement the <code>FileConfiguration</code> methods
+     * for <code>XMLConfiguration</code>, too.
+     */
     private class FileConfigurationDelegate extends AbstractFileConfiguration
     {
         public void load(InputStream in) throws ConfigurationException
@@ -1058,10 +1088,10 @@
         {
             XMLConfiguration.this.save(out);
         }
-        
+
         public void clear()
         {
             XMLConfiguration.this.clear();
         }
     }
-}
\ No newline at end of file
+}

Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLPropertiesConfiguration.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLPropertiesConfiguration.java?rev=312488&r1=312487&r2=312488&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLPropertiesConfiguration.java (original)
+++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLPropertiesConfiguration.java Sun Oct  9 11:27:12 2005
@@ -50,7 +50,7 @@
  *   &lt;entry key="key3">value3&lt;/entry>
  * &lt;/properties>
  * </pre>
- * 
+ *
  * The Java 5.0 runtime is not required to use this class. The default encoding
  * for this configuration format is UTF-8. Note that unlike
  * <code>PropertiesConfiguration</code>, <code>XMLPropertiesConfiguration</code>
@@ -189,6 +189,10 @@
 
     /**
      * Write a property.
+     *
+     * @param out the output stream
+     * @param key the key of the property
+     * @param value the value of the property
      */
     private void writeProperty(PrintWriter out, String key, Object value)
     {
@@ -211,6 +215,10 @@
 
     /**
      * Write a list property.
+     *
+     * @param out the output stream
+     * @param key the key of the property
+     * @param values a list with all property values
      */
     private void writeProperty(PrintWriter out, String key, List values)
     {
@@ -283,4 +291,4 @@
             value.append(chars, start, length);
         }
     }
-}
\ No newline at end of file
+}



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


Mime
View raw message