commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ohe...@apache.org
Subject svn commit: r293414 - in /jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration: AbstractConfiguration.java CompositeConfiguration.java Configuration.java ConfigurationConverter.java
Date Mon, 03 Oct 2005 18:13:05 GMT
Author: oheger
Date: Mon Oct  3 11:12:54 2005
New Revision: 293414

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

Modified:
    jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractConfiguration.java
    jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/CompositeConfiguration.java
    jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/Configuration.java
    jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/ConfigurationConverter.java

Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractConfiguration.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractConfiguration.java?rev=293414&r1=293413&r2=293414&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractConfiguration.java
(original)
+++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractConfiguration.java
Mon Oct  3 11:12:54 2005
@@ -32,7 +32,7 @@
  * Abstract configuration class. Provide basic functionality but does not store
  * any data. If you want to write your own Configuration class then you should
  * implement only abstract methods from this class.
- * 
+ *
  * @author <a href="mailto:ksh@scand.com">Konstantin Shaposhnikov </a>
  * @author <a href="mailto:oliver.heger@t-online.de">Oliver Heger </a>
  * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen </a>
@@ -54,12 +54,12 @@
      * Whether the configuration should throw NoSuchElementExceptions or simply
      * return null when a property does not exist. Defaults to return null.
      */
-    private boolean throwExceptionOnMissing = false;
+    private boolean throwExceptionOnMissing;
 
     /**
      * For configurations extending AbstractConfiguration, allow them to change
      * the delimiter from the default comma (",").
-     * 
+     *
      * @param delimiter The new delimiter
      */
     public static void setDelimiter(char delimiter)
@@ -69,7 +69,7 @@
 
     /**
      * Retrieve the current delimiter. By default this is a comma (",").
-     * 
+     *
      * @return The delimiter in use
      */
     public static char getDelimiter()
@@ -78,8 +78,14 @@
     }
 
     /**
-     * If set to false, missing elements return null if possible (for objects).
-     * 
+     * Allows to set the <code>throwExceptionOnMissing</code> flag. This
+     * flag controls the behavior of property getter methods that return
+     * objects if the requested property is missing. If the flag is set to
+     * <b>false</b> (which is the default value), these methods will return
+     * <b>null</b>. If set to <b>true</b>, they will throw a
+     * <code>NoSuchElementException</code> exception. Note that getter methods
+     * for primitive data types are not affected by this flag.
+     *
      * @param throwExceptionOnMissing The new value for the property
      */
     public void setThrowExceptionOnMissing(boolean throwExceptionOnMissing)
@@ -89,7 +95,7 @@
 
     /**
      * Returns true if missing values throw Exceptions.
-     * 
+     *
      * @return true if missing values throw Exceptions
      */
     public boolean isThrowExceptionOnMissing()
@@ -112,7 +118,7 @@
     /**
      * Adds a key/value pair to the Configuration. Override this method to
      * provide write acces to underlying Configuration store.
-     * 
+     *
      * @param key key to use for mapping
      * @param value object to store
      */
@@ -120,9 +126,9 @@
 
     /**
      * interpolate key names to handle ${key} stuff
-     * 
+     *
      * @param base string to interpolate
-     * 
+     *
      * @return returns the key name with the ${key} substituted
      */
     protected String interpolate(String base)
@@ -151,15 +157,15 @@
 
     /**
      * Recursive handler for multple levels of interpolation.
-     * 
+     *
      * When called the first time, priorVariables should be null.
-     * 
+     *
      * @param base string with the ${key} variables
      * @param priorVariables serves two purposes: to allow checking for loops,
      * and creating a meaningful exception message should a loop occur. It's
      * 0'th element will be set to the value of base from the first call. All
      * subsequent interpolated variables are added afterward.
-     * 
+     *
      * @return the string with the interpolation taken care of
      */
     protected String interpolateHelper(String base, List priorVariables)
@@ -320,16 +326,16 @@
 
     /**
      * Get a list of properties associated with the given configuration key.
-     * 
+     *
      * @param key The configuration key.
      * @param defaults Any default values for the returned
      * <code>Properties</code> object. Ignored if <code>null</code>.
-     * 
+     *
      * @return The associated properties if key is found.
-     * 
+     *
      * @throws ConversionException is thrown if the key maps to an object that
      * is not a String/List of Strings.
-     * 
+     *
      * @throws IllegalArgumentException if one of the tokens is malformed (does
      * not contain an equals sign).
      */
@@ -925,9 +931,9 @@
     /**
      * Returns an object from the store described by the key. If the value is a
      * List object, replace it with the first object in the list.
-     * 
+     *
      * @param key The property key.
-     * 
+     *
      * @return value Value, transparently resolving a possible List dependency.
      */
     protected Object resolveContainerStore(String key)

Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/CompositeConfiguration.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/CompositeConfiguration.java?rev=293414&r1=293413&r2=293414&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/CompositeConfiguration.java
(original)
+++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/CompositeConfiguration.java
Mon Oct  3 11:12:54 2005
@@ -1,5 +1,5 @@
 /*
- * Copyright 2001-2004 The Apache Software Foundation.
+ * Copyright 2001-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.
@@ -311,6 +311,7 @@
      * Return the configuration at the specified index.
      *
      * @param index The index of the configuration to retrieve
+     * @return the configuration at this index
      */
     public Configuration getConfiguration(int index)
     {

Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/Configuration.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/Configuration.java?rev=293414&r1=293413&r2=293414&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/Configuration.java
(original)
+++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/Configuration.java
Mon Oct  3 11:12:54 2005
@@ -1,5 +1,5 @@
 /*
- * Copyright 2001-2004 The Apache Software Foundation.
+ * Copyright 2001-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.
@@ -23,8 +23,34 @@
 import java.util.Properties;
 
 /**
- * Configuration interface.
+ * <p>The main Configuration interface.</p>
+ * <p>This interface allows accessing and manipulating a configuration object.
+ * The major part of the methods defined in this interface deals with accessing
+ * properties of various data types. There is a generic <code>getProperty()</code>
+ * method, which returns the value of the queried property in its raw data
+ * type. Other getter methods try to convert this raw data type into a specific
+ * data type. If this fails, a <code>ConversionException</code> will be thrown.</p>
+ * <p>For most of the property getter methods an overloaded version exists that
+ * allows to specify a default value, which will be returned if the queried
+ * property cannot be found in the configuration. The behavior of the methods
+ * that do not take a default value in case of a missing property is not defined
+ * by this interface and depends on a concrete implementation. E.g. the
+ * <code>{@link AbstractConfiguration}</code> class, which is the base class
+ * of most configuration implementations provided by this package, per default
+ * returns <b>null</b> if a property is not found, but provides the
+ * <code>{@link org.apache.commons.configuration.AbstractConfiguration#setThrowExceptionOnMissing(boolean)
+ * setThrowExceptionOnMissing()}</code>
+ * method, with which it can be configured to throw a <code>NoSuchElementException</code>
+ * exception in that case. (Note that getter methods for primitive types in
+ * <code>AbstractConfiguration</code> always throw an exception for missing
+ * properties because there is no way of overloading the return value.)</p>
+ * <p>With the <code>addProperty()</code> and <code>setProperty()</code>
methods
+ * new properties can be added to a configuration or the values of properties
+ * can be changed. With <code>clearProperty()</code> a property can be removed.
+ * Other methods allow to iterate over the contained properties or to create
+ * a subset configuration.</p>
  *
+ * @author Commons Configuration team
  * @version $Id$
  */
 public interface Configuration
@@ -56,6 +82,7 @@
      * Configuration, and reciprocally.
      *
      * @param prefix The prefix used to select the properties.
+     * @return a subset configuration
      *
      * @see SubsetConfiguration
      */
@@ -149,7 +176,7 @@
      * <code>{@link #clearProperty(String)}</code> for this property. So it is
      * highly recommended to avoid using the iterator's <code>remove()</code>
      * method.
-     * 
+     *
      * @return An Iterator.
      */
     Iterator getKeys();
@@ -179,9 +206,6 @@
      * @param key The configuration key.
      * @return The associated boolean.
      *
-     * @throws NoSuchElementException is thrown if the key doesn't
-     *         map to an existing object.
-     *
      * @throws ConversionException is thrown if the key maps to an
      *         object that is not a Boolean.
      */
@@ -212,7 +236,7 @@
      * @throws ConversionException is thrown if the key maps to an
      *         object that is not a Boolean.
      */
-    Boolean getBoolean(String key, Boolean defaultValue) throws NoClassDefFoundError;
+    Boolean getBoolean(String key, Boolean defaultValue);
 
     /**
      * Get a byte associated with the given configuration key.
@@ -220,9 +244,6 @@
      * @param key The configuration key.
      * @return The associated byte.
      *
-     * @throws NoSuchElementException is thrown if the key doesn't
-     *         map to an existing object.
-     *
      * @throws ConversionException is thrown if the key maps to an
      *         object that is not a Byte.
      */
@@ -261,9 +282,6 @@
      * @param key The configuration key.
      * @return The associated double.
      *
-     * @throws NoSuchElementException is thrown if the key doesn't
-     *         map to an existing object.
-     *
      * @throws ConversionException is thrown if the key maps to an
      *         object that is not a Double.
      */
@@ -301,9 +319,6 @@
      *
      * @param key The configuration key.
      * @return The associated float.
-     * @throws NoSuchElementException is thrown if the key doesn't
-     *         map to an existing object.
-     *
      * @throws ConversionException is thrown if the key maps to an
      *         object that is not a Float.
      */
@@ -344,9 +359,6 @@
      * @param key The configuration key.
      * @return The associated int.
      *
-     * @throws NoSuchElementException is thrown if the key doesn't
-     *         map to an existing object.
-     *
      * @throws ConversionException is thrown if the key maps to an
      *         object that is not a Integer.
      */
@@ -387,9 +399,6 @@
      * @param key The configuration key.
      * @return The associated long.
      *
-     * @throws NoSuchElementException is thrown if the key doesn't
-     *         map to an existing object.
-     *
      * @throws ConversionException is thrown if the key maps to an
      *         object that is not a Long.
      */
@@ -430,9 +439,6 @@
      * @param key The configuration key.
      * @return The associated short.
      *
-     * @throws NoSuchElementException is thrown if the key doesn't
-     *         map to an existing object.
-     *
      * @throws ConversionException is thrown if the key maps to an
      *         object that is not a Short.
      */
@@ -462,9 +468,6 @@
      *
      * @throws ConversionException is thrown if the key maps to an
      *         object that is not a Short.
-     *
-     * @throws NoSuchElementException is thrown if the key doesn't
-     *         map to an existing object.
      */
     Short getShort(String key, Short defaultValue);
 
@@ -473,9 +476,6 @@
      *
      * @param key The configuration key.
      * @return The associated BigDecimal if key is found and has valid format
-     *
-     * @throws NoSuchElementException is thrown if the key doesn't
-     *         map to an existing object.
      */
     BigDecimal getBigDecimal(String key);
 
@@ -498,9 +498,6 @@
      * @param key The configuration key.
      *
      * @return The associated BigInteger if key is found and has valid format
-     *
-     * @throws NoSuchElementException is thrown if the key doesn't
-     *         map to an existing object.
      */
     BigInteger getBigInteger(String key);
 
@@ -525,9 +522,6 @@
      *
      * @throws ConversionException is thrown if the key maps to an object that
      *         is not a String.
-     *
-     * @throws NoSuchElementException is thrown if the key doesn't
-     *         map to an existing object.
      */
     String getString(String key);
 

Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/ConfigurationConverter.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/ConfigurationConverter.java?rev=293414&r1=293413&r2=293414&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/ConfigurationConverter.java
(original)
+++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/ConfigurationConverter.java
Mon Oct  3 11:12:54 2005
@@ -34,6 +34,9 @@
  */
 public final class ConfigurationConverter
 {
+    /**
+     * Private constructor prevents instances from being created.
+     */
     private ConfigurationConverter()
     {
         // to prevent instanciation...
@@ -102,7 +105,8 @@
     {
         Properties props = new Properties();
 
-        char delimiter = (config instanceof AbstractConfiguration) ? ((AbstractConfiguration)
config).getDelimiter() : ',';
+        char delimiter = (config instanceof AbstractConfiguration)
+            ? ((AbstractConfiguration) config).getDelimiter() : ',';
 
         Iterator keys = config.getKeys();
         while (keys.hasNext())



---------------------------------------------------------------------
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