You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by oh...@apache.org on 2005/10/03 20:13:05 UTC
svn commit: r293414 - in
/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration:
AbstractConfiguration.java CompositeConfiguration.java Configuration.java
ConfigurationConverter.java
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