avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dona...@apache.org
Subject cvs commit: jakarta-avalon/src/java/org/apache/avalon/framework/service DefaultServiceManager.java DefaultServiceSelector.java ServiceManager.java ServiceSelector.java Serviceable.java
Date Thu, 21 Mar 2002 14:51:14 GMT
donaldp     02/03/21 06:51:14

  Modified:    src/java/org/apache/avalon/framework CascadingThrowable.java
                        Enum.java ExceptionUtil.java Version.java
               src/java/org/apache/avalon/framework/component
                        ComponentManager.java ComponentSelector.java
                        Composable.java DefaultComponentManager.java
                        DefaultComponentSelector.java Recomposable.java
               src/java/org/apache/avalon/framework/configuration
                        Configurable.java Configuration.java
                        DefaultConfiguration.java
                        DefaultConfigurationBuilder.java
                        DefaultConfigurationSerializer.java
                        NamespacedSAXConfigurationHandler.java
                        Reconfigurable.java SAXConfigurationHandler.java
               src/java/org/apache/avalon/framework/context Resolvable.java
               src/java/org/apache/avalon/framework/logger
                        AvalonFormatter.java ConsoleLogger.java
                        Jdk14Logger.java Log4JLogger.java LogKitLogger.java
                        Logger.java NullLogger.java
               src/java/org/apache/avalon/framework/parameters
                        Parameters.java
               src/java/org/apache/avalon/framework/service
                        DefaultServiceManager.java
                        DefaultServiceSelector.java ServiceManager.java
                        ServiceSelector.java Serviceable.java
  Log:
  A shedload of style/Javadoc patches. Due to initial run of checkstyle.
  
  Submitted By: Ryan Shaw <ryan@silveregg.co.jp>
  
  Revision  Changes    Path
  1.4       +6 -0      jakarta-avalon/src/java/org/apache/avalon/framework/CascadingThrowable.java
  
  Index: CascadingThrowable.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/CascadingThrowable.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- CascadingThrowable.java	11 Dec 2001 09:00:44 -0000	1.3
  +++ CascadingThrowable.java	21 Mar 2002 14:51:12 -0000	1.4
  @@ -12,8 +12,14 @@
    * Allows recording of nested exceptions.
    *
    * @author <a href="mailto:peter@apache.org">Peter Donald</a>
  + * @version 1.0
    */
   public interface CascadingThrowable
   {
  +    /**
  +     * Returns the root cause of this <code>Throwable</code>.
  +     *
  +     * @return a <code>Throwable</code>
  +     */
       Throwable getCause();
   }
  
  
  
  1.7       +2 -0      jakarta-avalon/src/java/org/apache/avalon/framework/Enum.java
  
  Index: Enum.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/Enum.java,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- Enum.java	11 Dec 2001 09:00:44 -0000	1.6
  +++ Enum.java	21 Mar 2002 14:51:12 -0000	1.7
  @@ -60,6 +60,7 @@
    *
    * @author <a href="mailto:peter@apache.org">Peter Donald</a>
    * @author <a href="mailto:jefft@apache.org">Jeff Turner</a>
  + * @version 1.0
    */
   public abstract class Enum
   {
  @@ -101,6 +102,7 @@
   
       /**
        * Retrieve the name of this Enum item, set in the constructor.
  +     * @return the name <code>String</code> of this Enum item
        */
       public final String getName()
       {
  
  
  
  1.10      +26 -3     jakarta-avalon/src/java/org/apache/avalon/framework/ExceptionUtil.java
  
  Index: ExceptionUtil.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/ExceptionUtil.java,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- ExceptionUtil.java	2 Mar 2002 02:50:52 -0000	1.9
  +++ ExceptionUtil.java	21 Mar 2002 14:51:12 -0000	1.10
  @@ -9,7 +9,6 @@
   
   import java.io.PrintWriter;
   import java.io.StringWriter;
  -import java.lang.reflect.InvocationTargetException;
   import java.lang.reflect.Method;
   import java.util.StringTokenizer;
   
  @@ -20,6 +19,7 @@
    *
    * @author <a href="mailto:peter@apache.org">Peter Donald</a>
    * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
  + * @version 1.0
    */
   public final class ExceptionUtil
   {
  @@ -37,6 +37,8 @@
       /**
        * Generate string for specified exception and the cause of
        * this exception (if any).
  +     * @param throwable a <code>Throwable</code>
  +     * @return the stack trace as a <code>String</code>
        */
       public static String printStackTrace( final Throwable throwable )
       {
  @@ -46,6 +48,9 @@
       /**
        * Generate string for specified exception and if printCascading
        * is true will print all cascading exceptions.
  +     * @param throwable a <code>Throwable</code>
  +     * @param printCascading if <code>true</code> will print all cascading exceptions
  +     * @return the stack trace as a <code>String</code>
        */
       public static String printStackTrace( final Throwable throwable,
                                             final boolean printCascading )
  @@ -58,6 +63,9 @@
        * Restrict the number of frames printed out to the specified depth.
        * If the depth specified is <code>0</code> then all the frames are
        * converted into a string.
  +     * @param throwable a <code>Throwable</code>
  +     * @param depth number of stack trace frames to show
  +     * @return the stack trace as a <code>String</code>
        */
       public static String printStackTrace( final Throwable throwable, final int depth )
       {
  @@ -83,6 +91,10 @@
       /**
        * Generate exception string for specified exception to specified depth
        * and all Cascading exceptions if printCascading is true.
  +     * @param throwable a <code>Throwable</code>
  +     * @param depth number of stack trace frames to show
  +     * @param printCascading if <code>true</code> will print all cascading exceptions
  +     * @return the stack trace as a <code>String</code>
        */
       public static String printStackTrace( final Throwable throwable,
                                             final int depth,
  @@ -97,6 +109,12 @@
        * is true then the method will also attempt to use reflection to find a
        * method with signature <code>Throwable getCause()</code>. This makes
        * it compatible with JDK1.4 mechanisms for nesting exceptions.
  +     * @param throwable a <code>Throwable</code>
  +     * @param depth number of stack trace frames to show
  +     * @param printCascading if <code>true</code> will print all cascading exceptions
  +     * @param useReflection if <code>true</code> will use reflection to handle JDK1.4 
  +     *                      nested exceptions
  +     * @return the stack trace as a <code>String</code>
        */
       public static String printStackTrace( final Throwable throwable,
                                             final int depth,
  @@ -131,6 +149,10 @@
   
       /**
        * Utility method to get cause of exception.
  +     * @param throwable a <code>Throwable</code>
  +     * @param useReflection if <code>true</code> will use reflection to handle JDK1.4 
  +     *                      nested exceptions
  +     * @return cause of specified exception
        */
       public static Throwable getCause( final Throwable throwable,
                                         final boolean useReflection )
  @@ -162,6 +184,7 @@
       /**
        * Captures the stack trace associated with this exception.
        *
  +     * @param throwable a <code>Throwable</code>
        * @return an array of Strings describing stack frames.
        */
       public static String[] captureStackTrace( final Throwable throwable )
  @@ -174,8 +197,8 @@
       /**
        * Splits the string on every token into an array of stack frames.
        *
  -     * @param string the string
  -     * @param onToken the token
  +     * @param string the string to split
  +     * @param onToken the token to split on
        * @return the resultant array
        * @deprecated This is an internal utility method that should not be used
        */
  
  
  
  1.12      +19 -3     jakarta-avalon/src/java/org/apache/avalon/framework/Version.java
  
  Index: Version.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/Version.java,v
  retrieving revision 1.11
  retrieving revision 1.12
  diff -u -r1.11 -r1.12
  --- Version.java	11 Dec 2001 09:00:44 -0000	1.11
  +++ Version.java	21 Mar 2002 14:51:12 -0000	1.12
  @@ -71,10 +71,16 @@
           final int major = Integer.parseInt( levels[ 0 ] );
   
           int minor = 0;       
  -        if( 1 < levels.length ) minor = Integer.parseInt( levels[ 1 ] );
  +        if( 1 < levels.length ) 
  +        { 
  +            minor = Integer.parseInt( levels[ 1 ] ); 
  +        }
   
           int micro = 0;
  -        if( 2 < levels.length ) micro = Integer.parseInt( levels[ 2 ] );
  +        if( 2 < levels.length ) 
  +        { 
  +            micro = Integer.parseInt( levels[ 2 ] ); 
  +        }
   
           return new Version( major, minor, micro );
       }
  @@ -85,7 +91,7 @@
        *
        * @param major This <code>Version</code> major number.
        * @param minor This <code>Version</code> minor number.
  -     * @param rev This <code>Version</code> micro number.
  +     * @param micro This <code>Version</code> micro number.
        */
       public Version( final int major, final int minor, final int micro )
       {
  @@ -132,6 +138,7 @@
        *
        * @param other The other <code>Version</code> object to be compared with this
        *          for equality.
  +     * @return <b>true</b> if this <code>Version</code> is compatible with the specified one
        */
       public boolean equals( final Version other )
       {
  @@ -153,6 +160,14 @@
           }
       }
   
  +    /**
  +     * Indicates whether some other object is "equal to" this <code>Version</code>.
  +     * Returns <b>true</b> if the other object is an instance of <code>Version</code>
  +     * and has the same major, minor, and micro components.
  +     *
  +     * @param other an <code>Object</code> value
  +     * @return <b>true</b> if the other object is equal to this <code>Version</code>
  +     */
       public boolean equals( final Object other )
       {
           if ( other instanceof Version )
  @@ -192,6 +207,7 @@
        *
        * @param other The other <code>Version</code> object to be compared with this
        *              for compliancy (compatibility).
  +     * @return <b>true</b> if this <code>Version</code> is compatible with the specified one
        */
       public boolean complies( final Version other )
       {
  
  
  
  1.5       +2 -1      jakarta-avalon/src/java/org/apache/avalon/framework/component/ComponentManager.java
  
  Index: ComponentManager.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/component/ComponentManager.java,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- ComponentManager.java	11 Dec 2001 09:00:44 -0000	1.4
  +++ ComponentManager.java	21 Mar 2002 14:51:13 -0000	1.5
  @@ -60,7 +60,8 @@
        * }
        * </pre>
        *
  -     * @param name The role name of the <code>Component</code> to retrieve.
  +     * @param role The role name of the <code>Component</code> to retrieve.
  +     * @return the desired component
        * @exception ComponentException if an error occurs
        */
       Component lookup( String role )
  
  
  
  1.5       +7 -7      jakarta-avalon/src/java/org/apache/avalon/framework/component/ComponentSelector.java
  
  Index: ComponentSelector.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/component/ComponentSelector.java,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- ComponentSelector.java	11 Dec 2001 09:00:44 -0000	1.4
  +++ ComponentSelector.java	21 Mar 2002 14:51:13 -0000	1.5
  @@ -56,12 +56,12 @@
        * }
        * </pre>
        *
  -     * @param name A hint to retrieve the correct <code>Component</code>.
  -     *
  -     * @exception ComponentNotFoundException If the given role is not associated
  -     *                                       with a <code>Component</code>.
  -     * @exception ComponentNotAccessibleException If a <code>Component</code>
  -     *                                            instance cannot be created.
  +     * @param hint A hint to retrieve the correct <code>Component</code>.
  +     * @return the desired component
  +     * @exception ComponentException If the given role is not associated
  +     *                               with a <code>Component</code>, or a 
  +     *                               <code>Component</code> instance cannot 
  +     *                               be created.
        */
       Component select( Object hint )
           throws ComponentException;
  @@ -69,7 +69,7 @@
       /**
        * Check to see if a <code>Component</code> exists for a hint.
        *
  -     * @param role  a string identifying the role to check.
  +     * @param hint  a string identifying the role to check.
        * @return True if the component exists, False if it does not.
        */
       boolean hasComponent( Object hint );
  
  
  
  1.4       +2 -1      jakarta-avalon/src/java/org/apache/avalon/framework/component/Composable.java
  
  Index: Composable.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/component/Composable.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- Composable.java	11 Dec 2001 09:00:44 -0000	1.3
  +++ Composable.java	21 Mar 2002 14:51:13 -0000	1.4
  @@ -33,8 +33,9 @@
        * <code>ComponentManager</code> to acquire the components it needs for
        * execution.
        *
  -     * @param manager The <code>ComponentManager</code> which this
  +     * @param componentManager The <code>ComponentManager</code> which this
        *                <code>Composable</code> uses.
  +     * @exception ComponentException if an error occurs
        */
       void compose( ComponentManager componentManager )
           throws ComponentException;
  
  
  
  1.9       +20 -2     jakarta-avalon/src/java/org/apache/avalon/framework/component/DefaultComponentManager.java
  
  Index: DefaultComponentManager.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/component/DefaultComponentManager.java,v
  retrieving revision 1.8
  retrieving revision 1.9
  diff -u -r1.8 -r1.9
  --- DefaultComponentManager.java	11 Dec 2001 09:00:44 -0000	1.8
  +++ DefaultComponentManager.java	21 Mar 2002 14:51:13 -0000	1.9
  @@ -18,6 +18,7 @@
    *
    * @author <a href="mailto:fede@apache.org">Federico Barbieri</a>
    * @author <a href="mailto:peter@apache.org">Peter Donald</a>
  + * @version 1.0
    */
   public class DefaultComponentManager
       implements ComponentManager
  @@ -71,7 +72,15 @@
           }
       }
   
  -    public boolean hasComponent( final String role ) {
  +    /**
  +     * Returns <code>true</code> if the component manager is managing a component
  +     * with the specified role, <code>false</code> otherwise.
  +     *
  +     * @param role role of the component you are lokking for
  +     * @return <code>true</code> if the component manager has a component with that role
  +     */
  +    public boolean hasComponent( final String role ) 
  +    {
           boolean componentExists = false;
   
           try
  @@ -151,17 +160,26 @@
           return m_components;
       }
   
  +    /**
  +     * Make this component manager read only.
  +     */
       public void makeReadOnly()
       {
           m_readOnly = true;
       }
   
  +    /**
  +     * Check if this component manager is writeable.
  +     *
  +     * @exception IllegalStateException if this component manager is read-only
  +     */
       protected final void checkWriteable()
           throws IllegalStateException
       {
           if( m_readOnly )
           {
  -            throw new IllegalStateException( "ComponentManager is read only and can not be modified" );
  +            throw new IllegalStateException
  +                ( "ComponentManager is read only and can not be modified" );
           }
       }
   }
  
  
  
  1.7       +17 -2     jakarta-avalon/src/java/org/apache/avalon/framework/component/DefaultComponentSelector.java
  
  Index: DefaultComponentSelector.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/component/DefaultComponentSelector.java,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- DefaultComponentSelector.java	11 Dec 2001 09:00:44 -0000	1.6
  +++ DefaultComponentSelector.java	21 Mar 2002 14:51:13 -0000	1.7
  @@ -14,6 +14,7 @@
    * This is the default implementation of the ComponentSelector
    *
    * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
  + * @version 1.0
    */
   public class DefaultComponentSelector
       implements ComponentSelector
  @@ -47,8 +48,11 @@
   
       /**
        * Returns whether a Component exists or not
  +     * @param hint the hint to retrieve Component
  +     * @return <code>true</code> if the Component exists
        */
  -    public boolean hasComponent( final Object hint ) {
  +    public boolean hasComponent( final Object hint ) 
  +    {
           boolean componentExists = false;
   
           try
  @@ -77,6 +81,8 @@
   
       /**
        * Populate the ComponentSelector.
  +     * @param hint the hint to retrieve Component
  +     * @param component the component to add
        */
       public void put( final Object hint, final Component component )
       {
  @@ -94,17 +100,26 @@
           return m_components;
       }
   
  +    /**
  +     * Make this component selector read-only.
  +     */
       public void makeReadOnly()
       {
           m_readOnly = true;
       }
   
  +    /**
  +     * Check if this component manager is writeable.
  +     *
  +     * @exception IllegalStateException if this component manager is read-only
  +     */
       protected final void checkWriteable()
           throws IllegalStateException
       {
           if( m_readOnly )
           {
  -            throw new IllegalStateException( "ComponentManager is read only and can not be modified" );
  +            throw new IllegalStateException
  +                ( "ComponentManager is read only and can not be modified" );
           }
       }
   }
  
  
  
  1.5       +3 -1      jakarta-avalon/src/java/org/apache/avalon/framework/component/Recomposable.java
  
  Index: Recomposable.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/component/Recomposable.java,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- Recomposable.java	11 Dec 2001 09:00:44 -0000	1.4
  +++ Recomposable.java	21 Mar 2002 14:51:13 -0000	1.5
  @@ -11,6 +11,7 @@
    * Extends composer to allow recomposing.
    *
    * @author <a href="mailto:peter@apache.org">Peter Donald</a>
  + * @version 1.0
    */
   public interface Recomposable
       extends Composable
  @@ -22,8 +23,9 @@
        * execution. It should also drop references to any components it 
        * retrieved from old ComponentManager.
        *
  -     * @param manager The <code>ComponentManager</code> which this
  +     * @param componentManager The <code>ComponentManager</code> which this
        *                <code>Composable</code> uses.
  +     * @exception ComponentException if an error occurs
        */
       void recompose( ComponentManager componentManager )
           throws ComponentException;
  
  
  
  1.5       +2 -0      jakarta-avalon/src/java/org/apache/avalon/framework/configuration/Configurable.java
  
  Index: Configurable.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/configuration/Configurable.java,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- Configurable.java	11 Dec 2001 09:00:45 -0000	1.4
  +++ Configurable.java	21 Mar 2002 14:51:13 -0000	1.5
  @@ -25,6 +25,7 @@
    * @author <a href="mailto:stefano@apache.org">Stefano Mazzocchi</a>
    * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
    * @author <a href="mailto:peter@apache.org">Peter Donald</a>
  + * @version 1.0
    */
   public interface Configurable
   {
  @@ -34,6 +35,7 @@
        * and before any other method.
        *
        * @param configuration the class configurations.
  +     * @exception ConfigurationException if an error occurs
        */
       void configure( Configuration configuration )
           throws ConfigurationException;
  
  
  
  1.15      +122 -77   jakarta-avalon/src/java/org/apache/avalon/framework/configuration/Configuration.java
  
  Index: Configuration.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/configuration/Configuration.java,v
  retrieving revision 1.14
  retrieving revision 1.15
  diff -u -r1.14 -r1.15
  --- Configuration.java	21 Mar 2002 04:41:51 -0000	1.14
  +++ Configuration.java	21 Mar 2002 14:51:13 -0000	1.15
  @@ -62,18 +62,42 @@
    * </p>
    * <table border="1">
    * <tr align="center"><th>Code</th><th>No namespaces</th><th>With namespaces</th></tr>
  - * <tr align="center"><td align="left"><code>conf.{@link #getName getName}()</code></td><td colspan="2">my-system</td></tr>
  - * <tr align="center"><td align="left"><code>conf.{@link #getAttributeNames getAttributeNames}().length</code></td><td>2</td><td>1</td></tr>
  - * <tr align="center"><td align="left"><code>conf.{@link #getChildren getChildren}().length</code></td><td colspan="2">2</td></tr>
  - * <tr align="center"><td align="left"><code>conf.{@link #getAttributeAsFloat getAttributeAsFloat}("version")</code></td><td colspan="2">1.3</td></tr>
  - * <tr align="center"><td align="left"><code>conf.{@link #getChild getChild}("widget").{@link #getAttribute getAttribute}("name")</code></td><td colspan="2">fooWidget</td></tr>
  - * <tr align="center"><td align="left"><code>conf.{@link #getChild getChild}("widget").{@link #getAttributeAsBoolean getAttributeAsBoolean}("threadsafe")</code></td><td colspan="2"><code>true</code></td></tr>
  - * <tr align="center"><td align="left"><code>conf.{@link #getChild getChild}("widget").{@link #getLocation getLocation}()</code></td><td colspan="2">file:///home/jeff/tmp/java/avalon/src/java/new.xconf:4:60</td></tr>
  - * <tr align="center"><td align="left"><code>conf.{@link #getChild getChild}("desc").{@link #getName getName}()</code></td><td>desc (see {@link #getChild(String)})</td><td>desc</td></tr>
  - * <tr align="center"><td align="left"><code>conf.{@link #getChild getChild}("doc:desc").{@link #getName getName}()</code></td><td>doc:desc</td><td>doc:desc (see {@link #getChild(String)})</td></tr>
  - * <tr align="center"><td align="left"><code>conf.{@link #getChild getChild}("desc").{@link #getValue getValue}()</code></td><td>{@link ConfigurationException}</td><td>This is a highly fictitious config file</td></tr>
  - * <tr align="center"><td align="left"><code>conf.{@link #getChild getChild}("doc:desc").{@link #getValue getValue}()</code></td><td>This is a highly fictitious config file</td><td>{@link ConfigurationException}</td></tr>
  - * <tr align="center"><td align="left"><code>conf.{@link #getChild getChild}("desc").{@link #getNamespace getNamespace}()</code></td><td>&nbsp;</td><td>http://myco.com/documentation"</td></tr>
  + * <tr align="center"><td align="left">
  + * <code>conf.{@link #getName getName}()</code></td><td colspan="2">my-system</td></tr>
  + * <tr align="center"><td align="left">
  + * <code>conf.{@link #getAttributeNames getAttributeNames}().length</code>
  + * </td><td>2</td><td>1</td></tr>
  + * <tr align="center"><td align="left">
  + * <code>conf.{@link #getChildren getChildren}().length</code>
  + * </td><td colspan="2">2</td></tr>
  + * <tr align="center"><td align="left">
  + * <code>conf.{@link #getAttributeAsFloat getAttributeAsFloat}("version")</code>
  + * </td><td colspan="2">1.3</td></tr>
  + * <tr align="center"><td align="left">
  + * <code>conf.{@link #getChild getChild}("widget").{@link #getAttribute getAttribute}("name")</code>
  + * </td><td colspan="2">fooWidget</td></tr>
  + * <tr align="center"><td align="left">
  + * <code>conf.{@link #getChild getChild}("widget")
  + * .{@link #getAttributeAsBoolean getAttributeAsBoolean}("threadsafe")</code></td><td colspan="2">
  + * <code>true</code></td></tr>
  + * <tr align="center"><td align="left">
  + * <code>conf.{@link #getChild getChild}("widget").{@link #getLocation getLocation}()</code>
  + * </td><td colspan="2">file:///home/jeff/tmp/java/avalon/src/java/new.xconf:4:60</td></tr>
  + * <tr align="center"><td align="left">
  + * <code>conf.{@link #getChild getChild}("desc").{@link #getName getName}()</code>
  + * </td><td>desc (see {@link #getChild(String)})</td><td>desc</td></tr>
  + * <tr align="center"><td align="left">
  + * <code>conf.{@link #getChild getChild}("doc:desc").{@link #getName getName}()</code>
  + * </td><td>doc:desc</td><td>doc:desc (see {@link #getChild(String)})</td></tr>
  + * <tr align="center"><td align="left">
  + * <code>conf.{@link #getChild getChild}("desc").{@link #getValue getValue}()</code>
  + * </td><td>{@link ConfigurationException}</td><td>This is a highly fictitious config file</td></tr>
  + * <tr align="center"><td align="left">
  + * <code>conf.{@link #getChild getChild}("doc:desc").{@link #getValue getValue}()</code>
  + * </td><td>This is a highly fictitious config file</td><td>{@link ConfigurationException}</td></tr>
  + * <tr align="center"><td align="left">
  + * <code>conf.{@link #getChild getChild}("desc").{@link #getNamespace getNamespace}()</code>
  + * </td><td>&nbsp;</td><td>http://myco.com/documentation"</td></tr>
    * </table>
    * </p>
    * <p>
  @@ -105,15 +129,16 @@
    * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
    * @author <a href="mailto:peter@apache.org">Peter Donald</a>
    * @author <a href="mailto:jefft@apache.org">Jeff Turner</a>
  + * @version 1.0
    */
   public interface Configuration
   {
       /**
        * Return the name of the node.
        *
  +     * @return name of the <code>Configuration</code> node.
        * @post getName() != null
        *
  -     * @return name of the <code>Configuration</code> node.
        */
       String getName();
   
  @@ -145,8 +170,9 @@
        * <p>The namespace of <code>foo</code> will be "", and the namespace of
        * <code>bar</code> will be "http://blah.com".</p>
        *
  -     * @since 4.1
        * @return a String identifying the namespace of this Configuration.
  +     * @exception ConfigurationException if an error occurs
  +     * @since 4.1
        */
       String getNamespace() throws ConfigurationException;
   
  @@ -164,11 +190,11 @@
        * use {@link #getChild(String, boolean) getChild("foo", <b>false</b>)}.
        * </p>
        *
  +     * @param child The name of the child node.
  +     * @return Configuration
        * @pre child != null
        * @post getConfiguration() != null
        *
  -     * @param child The name of the child node.
  -     * @return Configuration
        */
       Configuration getChild( String child );
   
  @@ -176,15 +202,15 @@
        * Return a <code>Configuration</code> instance encapsulating the specified
        * child node.
        *
  -     * @pre child != null
  -     * @post getConfiguration() != null
  -     *
        * @param child The name of the child node.
        * @param createNew If <code>true</code>, a new <code>Configuration</code>
        * will be created and returned if the specified child does not exist. If
        * <code>false</code>, <code>null</code> will be returned when the specified
        * child doesn't exist.
        * @return Configuration
  +     * @pre child != null
  +     * @post getConfiguration() != null
  +     *
        */
       Configuration getChild( String child, boolean createNew );
   
  @@ -202,11 +228,11 @@
        * elements containing all node children with the specified name. The array
        * order will reflect the order in the source config file.
        *
  +     * @param name The name of the children to get.
  +     * @return The child nodes with name <code>name</code>
        * @pre name != null
        * @post getConfigurations() != null
        *
  -     * @param name The name of the children to get.
  -     * @return The child nodes with name <code>name</code>
        */
       Configuration[] getChildren( String name );
   
  @@ -219,18 +245,19 @@
        * <tt>conf.getAttributeNames()[0]</tt>, then it is liable to break if a
        * different XML parser is used.
        * </p>
  +     * @return a <code>String[]</code> value
        */
       String[] getAttributeNames();
   
       /**
        * Return the value of specified attribute.
        *
  -     * @pre paramName != null
  -     * @post getAttribute != null
  -     *
        * @param paramName The name of the parameter you ask the value of.
        * @return String value of attribute.
        * @exception ConfigurationException If no attribute with that name exists.
  +     * @pre paramName != null
  +     * @post getAttribute != null
  +     *
        */
       String getAttribute( String paramName ) throws ConfigurationException;
   
  @@ -238,13 +265,13 @@
        * Return the <code>int</code> value of the specified attribute contained
        * in this node.
        *
  -     * @pre paramName != null
  -     * @post getAttributeAsInteger() != null
  -     *
        * @param paramName The name of the parameter you ask the value of.
        * @return int value of attribute
        * @exception ConfigurationException If no parameter with that name exists.
        *                                   or if conversion to <code>int</code> fails.
  +     * @pre paramName != null
  +     * @post getAttributeAsInteger() != null
  +     *
        */
       int getAttributeAsInteger( String paramName ) throws ConfigurationException;
   
  @@ -252,13 +279,20 @@
        * Returns the value of the attribute specified by its name as a
        * <code>long</code>.
        *
  +     * @param name The name of the parameter you ask the value of.
  +     * @return long value of attribute
  +     * @exception ConfigurationException If no parameter with that name exists.
  +     *                                   or if conversion to <code>long</code> fails.
        * @pre paramName != null
        * @post getAttributeAsLong() != null
        *
  +<<<<<<< Configuration.java
  +=======
        * @param name The name of the parameter you ask the value of.
        * @return long value of attribute
        * @exception ConfigurationException If no parameter with that name exists.
        *                                   or if conversion to <code>long</code> fails.
  +>>>>>>> 1.14
        */
       long getAttributeAsLong( String name ) throws ConfigurationException;
   
  @@ -266,13 +300,13 @@
        * Return the <code>float</code> value of the specified parameter contained
        * in this node.
        *
  -     * @pre paramName != null
  -     * @post getAttributeAsFloat() != null
  -     *
        * @param paramName The name of the parameter you ask the value of.
        * @return float value of attribute
        * @exception ConfigurationException If no parameter with that name exists.
        *                                   or if conversion to <code>float</code> fails.
  +     * @pre paramName != null
  +     * @post getAttributeAsFloat() != null
  +     *
        */
       float getAttributeAsFloat( String paramName ) throws ConfigurationException;
   
  @@ -280,63 +314,64 @@
        * Return the <code>boolean</code> value of the specified parameter contained
        * in this node.
        *
  -     * @pre paramName != null
  -     * @post getAttributeAsBoolean() != null
  -     *
        * @param paramName The name of the parameter you ask the value of.
        * @return boolean value of attribute
        * @exception ConfigurationException If no parameter with that name exists.
        *                                   or if conversion to <code>boolean</code> fails.
  +     * @pre paramName != null
  +     * @post getAttributeAsBoolean() != null
  +     *
        */
       boolean getAttributeAsBoolean( String paramName ) throws ConfigurationException;
   
       /**
        * Return the <code>String</code> value of the node.
        *
  +     * @return the value of the node.
  +     * @exception ConfigurationException if an error occurs
        * @post getValue() != null
        *
  -     * @return the value of the node.
        */
       String getValue() throws ConfigurationException;
   
       /**
        * Return the <code>int</code> value of the node.
        *
  -     * @post getValueAsInteger() != null
  -     *
        * @return the value of the node.
        *
        * @exception ConfigurationException If conversion to <code>int</code> fails.
  +     * @post getValueAsInteger() != null
  +     *
        */
       int getValueAsInteger() throws ConfigurationException;
   
       /**
        * Return the <code>float</code> value of the node.
        *
  -     * @post getValueAsFloat() != null
  -     *
        * @return the value of the node.
        * @exception ConfigurationException If conversion to <code>float</code> fails.
  +     * @post getValueAsFloat() != null
  +     *
        */
       float getValueAsFloat() throws ConfigurationException;
   
       /**
        * Return the <code>boolean</code> value of the node.
        *
  -     * @post getValueAsBoolean() != null
  -     *
        * @return the value of the node.
        * @exception ConfigurationException If conversion to <code>boolean</code> fails.
  +     * @post getValueAsBoolean() != null
  +     *
        */
       boolean getValueAsBoolean() throws ConfigurationException;
   
       /**
        * Return the <code>long</code> value of the node.
        *
  -     * @post getValueAsLong() != null
  -     *
        * @return the value of the node.
        * @exception ConfigurationException If conversion to <code>long</code> fails.
  +     * @post getValueAsLong() != null
  +     *
        */
       long getValueAsLong() throws ConfigurationException;
   
  @@ -345,12 +380,12 @@
        * If the configuration value is not set, the default value will be
        * used.
        *
  -     * @pre defaultValue != null
  -     * @post getValue(defaultValue) != null
  -     *
        * @param defaultValue The default value desired.
        * @return String value of the <code>Configuration</code>, or default
        *          if none specified.
  +     * @pre defaultValue != null
  +     * @post getValue(defaultValue) != null
  +     *
        */
       String getValue( String defaultValue );
   
  @@ -359,12 +394,12 @@
        * If the configuration value is not set, the default value will be
        * used.
        *
  -     * @pre defaultValue != null
  -     * @post getValueAsInteger(defaultValue) != null
  -     *
        * @param defaultValue The default value desired.
        * @return int value of the <code>Configuration</code>, or default
        *          if none specified.
  +     * @pre defaultValue != null
  +     * @post getValueAsInteger(defaultValue) != null
  +     *
        */
       int getValueAsInteger( int defaultValue );
   
  @@ -373,12 +408,12 @@
        * If the configuration value is not set, the default value will be
        * used.
        *
  -     * @pre defaultValue != null
  -     * @post getValueAsLong(defaultValue) != null
  -     *
        * @param defaultValue The default value desired.
        * @return long value of the <code>Configuration</code>, or default
        *          if none specified.
  +     * @pre defaultValue != null
  +     * @post getValueAsLong(defaultValue) != null
  +     *
        */
       long getValueAsLong( long defaultValue );
   
  @@ -387,12 +422,12 @@
        * If the configuration value is not set, the default value will be
        * used.
        *
  -     * @pre defaultValue != null
  -     * @post getValueAsFloat(defaultValue) != null
  -     *
        * @param defaultValue The default value desired.
        * @return float value of the <code>Configuration</code>, or default
        *          if none specified.
  +     * @pre defaultValue != null
  +     * @post getValueAsFloat(defaultValue) != null
  +     *
        */
       float getValueAsFloat( float defaultValue );
   
  @@ -401,12 +436,12 @@
        * If the configuration value is not set, the default value will be
        * used.
        *
  -     * @pre defaultValue != null
  -     * @post getValueAsBoolean(defaultValue) != null
  -     *
        * @param defaultValue The default value desired.
        * @return boolean value of the <code>Configuration</code>, or default
        *          if none specified.
  +     * @pre defaultValue != null
  +     * @post getValueAsBoolean(defaultValue) != null
  +     *
        */
       boolean getValueAsBoolean( boolean defaultValue );
   
  @@ -415,15 +450,17 @@
        * <code>String</code>, or the default value if no attribute by
        * that name exists or is empty.
        *
  -     * @pre name != null
  -     * @pre defaultValue != null
  -     * @post getAttribute(name, defaultValue) != null
  -     *
        * @param name The name of the attribute you ask the value of.
        * @param defaultValue The default value desired.
        * @return String value of attribute. It will return the default
        *         value if the named attribute does not exist, or if
        *         the value is not set.
  +     * @pre name != null
  +     * @pre defaultValue != null
  +     * @pre name != null
  +     * @pre defaultValue != null
  +     * @post getAttribute(name, defaultValue) != null
  +     *
        */
       String getAttribute( String name, String defaultValue );
   
  @@ -432,15 +469,17 @@
        * <code>int</code>, or the default value if no attribute by
        * that name exists or is empty.
        *
  -     * @pre name != null
  -     * @pre defaultValue != null
  -     * @post getAttributeAsInteger(name, defaultValue) != null
  -     *
        * @param name The name of the attribute you ask the value of.
        * @param defaultValue The default value desired.
        * @return int value of attribute. It will return the default
        *         value if the named attribute does not exist, or if
        *         the value is not set.
  +     * @pre name != null
  +     * @pre defaultValue != null
  +     * @pre name != null
  +     * @pre defaultValue != null
  +     * @post getAttributeAsInteger(name, defaultValue) != null
  +     *
        */
       int getAttributeAsInteger( String name, int defaultValue );
   
  @@ -449,15 +488,17 @@
        * <code>long</code>, or the default value if no attribute by
        * that name exists or is empty.
        *
  -     * @pre name != null
  -     * @pre defaultValue != null
  -     * @post getAttributeAsLong(name, defaultValue) != null
  -     *
        * @param name The name of the attribute you ask the value of.
        * @param defaultValue The default value desired.
        * @return long value of attribute. It will return the default
        *          value if the named attribute does not exist, or if
        *          the value is not set.
  +     * @pre name != null
  +     * @pre defaultValue != null
  +     * @pre name != null
  +     * @pre defaultValue != null
  +     * @post getAttributeAsLong(name, defaultValue) != null
  +     *
        */
       long getAttributeAsLong( String name, long defaultValue );
   
  @@ -466,15 +507,17 @@
        * <code>float</code>, or the default value if no attribute by
        * that name exists or is empty.
        *
  -     * @pre name != null
  -     * @pre defaultValue != null
  -     * @post getAttributeAsFloat(name, defaultValue) != null
  -     *
        * @param name The name of the attribute you ask the value of.
        * @param defaultValue The default value desired.
        * @return float value of attribute. It will return the default
        *          value if the named attribute does not exist, or if
        *          the value is not set.
  +     * @pre name != null
  +     * @pre defaultValue != null
  +     * @pre name != null
  +     * @pre defaultValue != null
  +     * @post getAttributeAsFloat(name, defaultValue) != null
  +     *
        */
       float getAttributeAsFloat( String name, float defaultValue );
   
  @@ -483,15 +526,17 @@
        * <code>boolean</code>, or the default value if no attribute by
        * that name exists or is empty.
        *
  -     * @pre name != null
  -     * @pre defaultValue != null
  -     * @post getAttributeAsBoolean(name, defaultValue) != null
  -     *
        * @param name The name of the attribute you ask the value of.
        * @param defaultValue The default value desired.
        * @return boolean value of attribute. It will return the default
        *         value if the named attribute does not exist, or if
        *         the value is not set.
  +     * @pre name != null
  +     * @pre defaultValue != null
  +     * @pre name != null
  +     * @pre defaultValue != null
  +     * @post getAttributeAsBoolean(name, defaultValue) != null
  +     *
        */
       boolean getAttributeAsBoolean( String name, boolean defaultValue );
   }
  
  
  
  1.15      +53 -4     jakarta-avalon/src/java/org/apache/avalon/framework/configuration/DefaultConfiguration.java
  
  Index: DefaultConfiguration.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/configuration/DefaultConfiguration.java,v
  retrieving revision 1.14
  retrieving revision 1.15
  diff -u -r1.14 -r1.15
  --- DefaultConfiguration.java	15 Feb 2002 23:06:25 -0000	1.14
  +++ DefaultConfiguration.java	21 Mar 2002 14:51:13 -0000	1.15
  @@ -18,11 +18,15 @@
    * @author <a href="mailto:stefano@apache.org">Stefano Mazzocchi</a>
    * @author <a href="mailto:fumagalli@exoffice.com">Pierpaolo Fumagalli</a>
    * @author <a href="mailto:peter@apache.org">Peter Donald</a>
  + * @version 1.0
    */
   public class DefaultConfiguration
       extends AbstractConfiguration
       implements Serializable
   {
  +    /**
  +     * An empty (length zero) array of configuration objects.
  +     */
       protected static final Configuration[]   EMPTY_ARRAY = new Configuration[ 0 ];
   
       private final String                     m_name;
  @@ -36,6 +40,8 @@
   
       /**
        * Create a new <code>DefaultConfiguration</code> instance.
  +     * @param name a <code>String</code> value
  +     * @param location a <code>String</code> value
        */
       public DefaultConfiguration( final String name, final String location )
       {
  @@ -65,6 +71,7 @@
   
       /**
        * Returns the name of this configuration element.
  +     * @return a <code>String</code> value
        */
       public String getName()
       {
  @@ -73,6 +80,8 @@
   
       /**
        * Returns the namespace of this configuration element
  +     * @return a <code>String</code> value
  +     * @exception ConfigurationException if an error occurs
        */
       public String getNamespace() throws ConfigurationException
       {
  @@ -82,7 +91,8 @@
           }
           else
           {
  -            throw new ConfigurationException( "No namespace (not even default \"\") is associated with the "+
  +            throw new ConfigurationException
  +                ( "No namespace (not even default \"\") is associated with the "+
                                                 "configuration element \"" + getName() +
                                                 "\" at " + getLocation() );
           }
  @@ -90,7 +100,8 @@
   
       /**
        * Returns the prefix of the namespace
  -     * @throws ConfigurationException if prefix is not present (<code>null</code>).
  +     * @return a <code>String</code> value
  +     * @exception ConfigurationException if prefix is not present (<code>null</code>).
        */
       protected String getPrefix() throws ConfigurationException
       {
  @@ -100,7 +111,8 @@
           }
           else
           {
  -            throw new ConfigurationException( "No prefix (not even default \"\") is associated with the "+
  +            throw new ConfigurationException
  +                ( "No prefix (not even default \"\") is associated with the "+
                                                 "configuration element \"" + getName() +
                                                 "\" at " + getLocation() );
           }
  @@ -109,6 +121,7 @@
   
       /**
        * Returns a description of location of element.
  +     * @return a <code>String</code> value
        */
       public String getLocation()
       {
  @@ -118,6 +131,7 @@
       /**
        * Returns the value of the configuration element as a <code>String</code>.
        *
  +     * @return a <code>String</code> value
        * @exception ConfigurationException If the value is not present.
        */
       public String getValue() throws ConfigurationException
  @@ -136,6 +150,7 @@
   
       /**
        * Return an array of all attribute names.
  +     * @return a <code>String[]</code> value
        */
       public String[] getAttributeNames()
       {
  @@ -171,6 +186,8 @@
        * Returns the value of the attribute specified by its name as a
        * <code>String</code>.
        *
  +     * @param name a <code>String</code> value
  +     * @return a <code>String</code> value
        * @exception ConfigurationException If the attribute is not present.
        */
       public String getAttribute( final String name )
  @@ -194,6 +211,9 @@
       /**
        * Return the first <code>Configuration</code> object child of this
        * associated with the given name.
  +     * @param name a <code>String</code> value
  +     * @param createNew a <code>boolean</code> value
  +     * @return a <code>Configuration</code> value
        */
       public Configuration getChild( final String name, final boolean createNew )
       {
  @@ -227,6 +247,7 @@
        * The returned <code>Enumeration</code> may be empty.
        *
        * @param name The name of the required children <code>Configuration</code>.
  +     * @return a <code>Configuration[]</code> value
        */
       public Configuration[] getChildren( final String name )
       {
  @@ -255,6 +276,7 @@
       /**
        * Append data to the value of this configuration element.
        *
  +     * @param value a <code>String</code> value
        * @deprecated Use setValue() instead
        */
       public void appendValueData( final String value )
  @@ -271,6 +293,11 @@
           }
       }
   
  +    /**
  +     * Set the value of this <code>Configuration</code> object to the specified string.
  +     *
  +     * @param value a <code>String</code> value
  +     */
       public void setValue( final String value )
       {
           checkWriteable();
  @@ -278,6 +305,12 @@
           m_value = value;
       }
   
  +    /**
  +     * Set the value of the specified attribute to the specified string.
  +     *
  +     * @param name name of the attribute to set
  +     * @param value a <code>String</code> value
  +     */
       public void setAttribute( final String name, final String value )
       {
           checkWriteable();
  @@ -293,6 +326,9 @@
        * Add an attribute to this configuration element, returning its old
        * value or <b>null</b>.
        *
  +     * @param name a <code>String</code> value
  +     * @param value a <code>String</code> value
  +     * @return a <code>String</code> value
        * @deprecated Use setAttribute() instead
        */
       public String addAttribute( final String name, String value )
  @@ -309,6 +345,7 @@
   
       /**
        * Add a child <code>Configuration</code> to this configuration element.
  +     * @param configuration a <code>Configuration</code> value
        */
       public void addChild( final Configuration configuration )
       {
  @@ -324,6 +361,7 @@
   
       /**
        * Remove a child <code>Configuration</code> to this configuration element.
  +     * @param configuration a <code>Configuration</code> value
        */
       public void removeChild( final Configuration configuration )
       {
  @@ -338,6 +376,7 @@
   
       /**
        * Return count of children.
  +     * @return an <code>int</code> value
        */
       public int getChildCount()
       {
  @@ -349,17 +388,27 @@
           return m_children.size();
       }
   
  +    /**
  +     * Make this configuration read-only.
  +     *
  +     */
       public void makeReadOnly()
       {
           m_readOnly = true;
       }
   
  +    /**
  +     * heck if this configuration is writeable.
  +     *
  +     * @exception IllegalStateException if this configuration s read-only
  +     */
       protected final void checkWriteable()
           throws IllegalStateException
       {
           if( m_readOnly )
           {
  -            throw new IllegalStateException( "Configuration is read only and can not be modified" );
  +            throw new IllegalStateException
  +                ( "Configuration is read only and can not be modified" );
           }
       }
   }
  
  
  
  1.14      +28 -0     jakarta-avalon/src/java/org/apache/avalon/framework/configuration/DefaultConfigurationBuilder.java
  
  Index: DefaultConfigurationBuilder.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/configuration/DefaultConfigurationBuilder.java,v
  retrieving revision 1.13
  retrieving revision 1.14
  diff -u -r1.13 -r1.14
  --- DefaultConfigurationBuilder.java	11 Dec 2001 09:00:45 -0000	1.13
  +++ DefaultConfigurationBuilder.java	21 Mar 2002 14:51:13 -0000	1.14
  @@ -47,6 +47,7 @@
    * @author <a href="mailto:fede@apache.org">Federico Barbieri</a>
    * @author <a href="mailto:peter@apache.org">Peter Donald</a>
    * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
  + * @version 1.0
    */
   public class DefaultConfigurationBuilder
   {
  @@ -95,6 +96,7 @@
   
       /**
        * Create a Configuration Builder with your own XMLReader.
  +     * @param parser an <code>XMLReader</code>
        */
       public DefaultConfigurationBuilder( XMLReader parser )
       {
  @@ -116,6 +118,7 @@
   
       /**
        * Get a SAXConfigurationHandler for your configuration reading.
  +     * @return a <code>SAXConfigurationHandler</code>
        */
       protected SAXConfigurationHandler getHandler()
       {
  @@ -136,6 +139,11 @@
   
       /**
        * Build a configuration object from a file using a filename.
  +     * @param filename name of the file
  +     * @return a <code>Configuration</code> object
  +     * @exception SAXException if a parsing error occurs
  +     * @exception IOException if an I/O error occurs
  +     * @exception ConfigurationException if an error occurs
        */
       public Configuration buildFromFile( final String filename )
           throws SAXException, IOException, ConfigurationException
  @@ -145,6 +153,11 @@
   
       /**
        * Build a configuration object from a file using a File object.
  +     * @param file a <code>File</code> object
  +     * @return a <code>Configuration</code> object
  +     * @exception SAXException if a parsing error occurs
  +     * @exception IOException if an I/O error occurs
  +     * @exception ConfigurationException if an error occurs
        */
       public Configuration buildFromFile( final File file )
           throws SAXException, IOException, ConfigurationException
  @@ -159,6 +172,11 @@
   
       /**
        * Build a configuration object using an InputStream.
  +     * @param inputStream an <code>InputStream</code> value
  +     * @return a <code>Configuration</code> object
  +     * @exception SAXException if a parsing error occurs
  +     * @exception IOException if an I/O error occurs
  +     * @exception ConfigurationException if an error occurs
        */
       public Configuration build( final InputStream inputStream )
           throws SAXException, IOException, ConfigurationException
  @@ -168,6 +186,11 @@
   
       /**
        * Build a configuration object using an URI
  +     * @param uri a <code>String</code> value
  +     * @return a <code>Configuration</code> object
  +     * @exception SAXException if a parsing error occurs
  +     * @exception IOException if an I/O error occurs
  +     * @exception ConfigurationException if an error occurs
        */
       public Configuration build( final String uri )
           throws SAXException, IOException, ConfigurationException
  @@ -177,6 +200,11 @@
   
       /**
        * Build a configuration object using an XML InputSource object
  +     * @param input an <code>InputSource</code> value
  +     * @return a <code>Configuration</code> object
  +     * @exception SAXException if a parsing error occurs
  +     * @exception IOException if an I/O error occurs
  +     * @exception ConfigurationException if an error occurs
        */
       public Configuration build( final InputSource input )
           throws SAXException, IOException, ConfigurationException
  
  
  
  1.10      +30 -2     jakarta-avalon/src/java/org/apache/avalon/framework/configuration/DefaultConfigurationSerializer.java
  
  Index: DefaultConfigurationSerializer.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/configuration/DefaultConfigurationSerializer.java,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- DefaultConfigurationSerializer.java	5 Mar 2002 07:38:54 -0000	1.9
  +++ DefaultConfigurationSerializer.java	21 Mar 2002 14:51:13 -0000	1.10
  @@ -11,7 +11,6 @@
   import java.io.FileOutputStream;
   import java.io.IOException;
   import java.io.OutputStream;
  -import java.io.OutputStream;
   import java.net.URL;
   import java.util.Properties;
   import javax.xml.transform.OutputKeys;
  @@ -20,7 +19,6 @@
   import javax.xml.transform.sax.TransformerHandler;
   import javax.xml.transform.stream.StreamResult;
   import org.xml.sax.SAXException;
  -import org.xml.sax.XMLReader;
   import org.xml.sax.helpers.AttributesImpl;
   import org.xml.sax.helpers.NamespaceSupport;
   
  @@ -28,6 +26,7 @@
    * A ConfigurationSerializer serializes configurations via SAX2 compliant parser.
    *
    * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
  + * @version 1.0
    */
   public class DefaultConfigurationSerializer
   {
  @@ -48,6 +47,7 @@
       /**
        * Sets the Serializer's use of indentation.  This will cause linefeeds to be added
        *  after each element, but it does not add any indentation via spaces.
  +     * @param indent a <code>boolean</code> value
        */
       public void setIndent( boolean indent )
       {
  @@ -63,6 +63,7 @@
   
       /**
        * Internally set the output strream we will be using.
  +     * @param out an <code>OutputStream</code> value
        */
       protected void setOutputStream( final OutputStream out )
       {
  @@ -83,6 +84,7 @@
       /**
        * Get the SAXTransformerFactory so we can get a serializer without being
        * tied to one vendor.
  +     * @return a <code>SAXTransformerFactory</code> value
        */
       protected SAXTransformerFactory getTransformerFactory()
       {
  @@ -97,6 +99,9 @@
       /**
        * Start the serialization process.  The output stream <strong>must</strong>
        * be set before calling this method.
  +     * @param source a <code>Configuration</code> value
  +     * @exception SAXException if an error occurs
  +     * @exception ConfigurationException if an error occurs
        */
       protected void serialize( final Configuration source )
           throws SAXException, ConfigurationException
  @@ -109,6 +114,9 @@
   
       /**
        * Serialize each Configuration element.  This method is called recursively.
  +     * @param element a <code>Configuration</code> value
  +     * @exception SAXException if an error occurs
  +     * @exception ConfigurationException if an error occurs
        */
       protected void serializeElement( final Configuration element )
           throws SAXException, ConfigurationException
  @@ -208,6 +216,11 @@
   
       /**
        * Serialize the configuration object to a file using a filename.
  +     * @param filename a <code>String</code> value
  +     * @param source a <code>Configuration</code> value
  +     * @exception SAXException if an error occurs
  +     * @exception IOException if an error occurs
  +     * @exception ConfigurationException if an error occurs
        */
       public void serializeToFile( final String filename, final Configuration source )
           throws SAXException, IOException, ConfigurationException
  @@ -217,6 +230,11 @@
   
       /**
        * Serialize the configuration object to a file using a File object.
  +     * @param file a <code>File</code> value
  +     * @param source a <code>Configuration</code> value
  +     * @exception SAXException if an error occurs
  +     * @exception IOException if an error occurs
  +     * @exception ConfigurationException if an error occurs
        */
       public void serializeToFile( final File file, final Configuration source )
           throws SAXException, IOException, ConfigurationException
  @@ -226,6 +244,11 @@
   
       /**
        * Serialize the configuration object to an output stream.
  +     * @param outputStream an <code>OutputStream</code> value
  +     * @param source a <code>Configuration</code> value
  +     * @exception SAXException if an error occurs
  +     * @exception IOException if an error occurs
  +     * @exception ConfigurationException if an error occurs
        */
       public void serialize( final OutputStream outputStream, final Configuration source )
           throws SAXException, IOException, ConfigurationException
  @@ -240,6 +263,11 @@
       /**
        * Serialize the configuration object to an output stream derived from an
        * URI.  The URI must be resolveable by the <code>java.net.URL</code> object.
  +     * @param uri a <code>String</code> value
  +     * @param source a <code>Configuration</code> value
  +     * @exception SAXException if an error occurs
  +     * @exception IOException if an error occurs
  +     * @exception ConfigurationException if an error occurs
        */
       public void serialize( final String uri, final Configuration source )
           throws SAXException, IOException, ConfigurationException
  
  
  
  1.4       +80 -3     jakarta-avalon/src/java/org/apache/avalon/framework/configuration/NamespacedSAXConfigurationHandler.java
  
  Index: NamespacedSAXConfigurationHandler.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/configuration/NamespacedSAXConfigurationHandler.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- NamespacedSAXConfigurationHandler.java	11 Dec 2001 09:00:45 -0000	1.3
  +++ NamespacedSAXConfigurationHandler.java	21 Mar 2002 14:51:13 -0000	1.4
  @@ -10,11 +10,9 @@
   import java.util.ArrayList;
   import java.util.Iterator;
   import org.xml.sax.Attributes;
  -import org.xml.sax.ErrorHandler;
   import org.xml.sax.Locator;
   import org.xml.sax.SAXException;
   import org.xml.sax.SAXParseException;
  -import org.xml.sax.helpers.DefaultHandler;
   import org.xml.sax.helpers.NamespaceSupport;
   import org.xml.sax.helpers.AttributesImpl;
   
  @@ -24,6 +22,7 @@
    *
    * @author <a href="mailto:fede@apache.org">Federico Barbieri</a>
    * @author <a href="mailto:peter@apache.org">Peter Donald</a>
  + * @version 1.0
    */
   public class NamespacedSAXConfigurationHandler
       extends SAXConfigurationHandler
  @@ -34,11 +33,19 @@
       private Locator                      m_locator;
       private NamespaceSupport             m_namespaceSupport = new NamespaceSupport();
   
  +    /**
  +     * Get the configuration object that was built.
  +     *
  +     * @return a <code>Configuration</code> object
  +     */
       public Configuration getConfiguration()
       {
           return m_configuration;
       }
   
  +    /**
  +     * Clears all data from this configuration handler.
  +     */
       public void clear()
       {
           m_elements.clear();
  @@ -51,11 +58,21 @@
           m_locator = null;
       }
   
  +    /**
  +     * Set the document <code>Locator</code> to use.
  +     *
  +     * @param locator a <code>Locator</code> value
  +     */
       public void setDocumentLocator( final Locator locator )
       {
           m_locator = locator;
       }
   
  +    /**
  +     * Handling hook for starting the document parsing.
  +     *
  +     * @exception SAXException if an error occurs
  +     */
       public void startDocument()
           throws SAXException
       {
  @@ -63,6 +80,11 @@
           super.startDocument();
       }
   
  +    /**
  +     * Handling hook for ending the document parsing.
  +     *
  +     * @exception SAXException if an error occurs
  +     */
       public void endDocument()
           throws SAXException
       {
  @@ -70,6 +92,14 @@
           m_namespaceSupport.reset();
       }
   
  +    /**
  +     * Handling hook for character data.
  +     *
  +     * @param ch a <code>char[]</code> of data
  +     * @param start offset in the character array from which to start reading
  +     * @param end length of character data
  +     * @exception SAXException if an error occurs
  +     */
       public void characters( final char[] ch, int start, int end )
           throws SAXException
       {
  @@ -94,6 +124,14 @@
           configuration.setValue( value );
       }
   
  +    /**
  +     * Handling hook for finishing parsing of an element.
  +     *
  +     * @param namespaceURI a <code>String</code> value
  +     * @param localName a <code>String</code> value
  +     * @param rawName a <code>String</code> value
  +     * @exception SAXException if an error occurs
  +     */
       public void endElement( final String namespaceURI,
                               final String localName,
                               final String rawName )
  @@ -118,15 +156,36 @@
           m_namespaceSupport.popContext();
       }
   
  +    /**
  +     * Create a new <code>DefaultConfiguration</code> with the specified
  +     * local name, namespace, and location.
  +     *
  +     * @param localName a <code>String</code> value
  +     * @param namespaceURI a <code>String</code> value
  +     * @param location a <code>String</code> value
  +     * @return a <code>DefaultConfiguration</code> value
  +     */
       protected DefaultConfiguration createConfiguration( final String localName,
                                                           final String namespaceURI,
                                                           final String location )
       {
           String prefix = m_namespaceSupport.getPrefix( namespaceURI );
  -        if (prefix == null) prefix = "";
  +        if (prefix == null) 
  +        {
  +            prefix = "";
  +        }
           return new DefaultConfiguration( localName, location, namespaceURI, prefix );
       }
   
  +    /**
  +     * Handling hook for starting parsing of an element.
  +     *
  +     * @param namespaceURI a <code>String</code> value
  +     * @param localName a <code>String</code> value
  +     * @param rawName a <code>String</code> value
  +     * @param attributes an <code>Attributes</code> value
  +     * @exception SAXException if an error occurs
  +     */
       public void startElement( final String namespaceURI,
                                 final String localName,
                                 final String rawName,
  @@ -189,6 +248,8 @@
   
       /**
        * This just throws an exception on a parse error.
  +     * @param exception the parse error
  +     * @exception SAXException if an error occurs
        */
       public void error( final SAXParseException exception )
           throws SAXException
  @@ -198,6 +259,8 @@
   
       /**
        * This just throws an exception on a parse error.
  +     * @param exception the parse error
  +     * @exception SAXException if an error occurs
        */
       public void warning( final SAXParseException exception )
           throws SAXException
  @@ -207,6 +270,8 @@
   
       /**
        * This just throws an exception on a parse error.
  +     * @param exception the parse error
  +     * @exception SAXException if an error occurs
        */
       public void fatalError( final SAXParseException exception )
           throws SAXException
  @@ -214,6 +279,11 @@
           throw exception;
       }
   
  +    /**
  +     * Returns a string showing the current system ID, line number and column number.
  +     *
  +     * @return a <code>String</code> value
  +     */
       protected String getLocationString()
       {
           if( null == m_locator )
  @@ -229,6 +299,13 @@
           }
       }
   
  +    /**
  +     * Handling hook for starting prefix mapping.
  +     *
  +     * @param prefix a <code>String</code> value
  +     * @param uri a <code>String</code> value
  +     * @exception SAXException if an error occurs
  +     */
       public void startPrefixMapping(String prefix, String uri)
           throws SAXException
       {
  
  
  
  1.6       +7 -0      jakarta-avalon/src/java/org/apache/avalon/framework/configuration/Reconfigurable.java
  
  Index: Reconfigurable.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/configuration/Reconfigurable.java,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- Reconfigurable.java	11 Dec 2001 09:00:45 -0000	1.5
  +++ Reconfigurable.java	21 Mar 2002 14:51:13 -0000	1.6
  @@ -14,10 +14,17 @@
    * @author <a href="mailto:pier@apache.org">Pierpaolo Fumagalli</a>
    * @author <a href="mailto:stefano@apache.org">Stefano Mazzocchi</a>
    * @author <a href="mailto:peter@apache.org">Peter Donald</a>
  + * @version 1.0
    */
   public interface Reconfigurable
       extends Configurable
   {
  +    /**
  +     * Describe <code>reconfigure</code> method here.
  +     *
  +     * @param configuration a <code>Configuration</code> value
  +     * @exception ConfigurationException if an error occurs
  +     */
       void reconfigure( Configuration configuration ) 
           throws ConfigurationException;
   }
  
  
  
  1.14      +57 -0     jakarta-avalon/src/java/org/apache/avalon/framework/configuration/SAXConfigurationHandler.java
  
  Index: SAXConfigurationHandler.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/configuration/SAXConfigurationHandler.java,v
  retrieving revision 1.13
  retrieving revision 1.14
  diff -u -r1.13 -r1.14
  --- SAXConfigurationHandler.java	11 Dec 2001 09:00:45 -0000	1.13
  +++ SAXConfigurationHandler.java	21 Mar 2002 14:51:13 -0000	1.14
  @@ -29,22 +29,43 @@
       private Configuration                m_configuration;
       private Locator                      m_locator;
   
  +    /**
  +     * Get the configuration object that was built.
  +     *
  +     * @return a <code>Configuration</code> object
  +     */
       public Configuration getConfiguration()
       {
           return m_configuration;
       }
   
  +    /**
  +     * Clears all data from this configuration handler.
  +     */
       public void clear()
       {
           m_elements.clear();
           m_locator = null;
       }
   
  +    /**
  +     * Set the document <code>Locator</code> to use.
  +     *
  +     * @param locator a <code>Locator</code> value
  +     */
       public void setDocumentLocator( final Locator locator )
       {
           m_locator = locator;
       }
   
  +    /**
  +     * Handling hook for character data.
  +     *
  +     * @param ch a <code>char[]</code> of data
  +     * @param start offset in the character array from which to start reading
  +     * @param end length of character data
  +     * @exception SAXException if an error occurs
  +     */
       public void characters( final char[] ch, int start, int end )
           throws SAXException
       {
  @@ -69,6 +90,14 @@
           configuration.setValue( value );
       }
   
  +    /**
  +     * Handling hook for finishing parsing of an element.
  +     *
  +     * @param namespaceURI a <code>String</code> value
  +     * @param localName a <code>String</code> value
  +     * @param rawName a <code>String</code> value
  +     * @exception SAXException if an error occurs
  +     */
       public void endElement( final String namespaceURI,
                               final String localName,
                               final String rawName )
  @@ -83,12 +112,29 @@
           }
       }
   
  +    /**
  +     * Create a new <code>DefaultConfiguration</code> with the specified
  +     * local name and location.
  +     *
  +     * @param localName a <code>String</code> value
  +     * @param location a <code>String</code> value
  +     * @return a <code>DefaultConfiguration</code> value
  +     */
       protected DefaultConfiguration createConfiguration( final String localName,
                                                           final String location )
       {
           return new DefaultConfiguration( localName, location );
       }
   
  +    /**
  +     * Handling hook for starting parsing of an element.
  +     *
  +     * @param namespaceURI a <code>String</code> value
  +     * @param localName a <code>String</code> value
  +     * @param rawName a <code>String</code> value
  +     * @param attributes an <code>Attributes</code> value
  +     * @exception SAXException if an error occurs
  +     */
       public void startElement( final String namespaceURI,
                                 final String localName,
                                 final String rawName,
  @@ -128,6 +174,8 @@
   
       /**
        * This just throws an exception on a parse error.
  +     * @param exception the parse error
  +     * @exception SAXException if an error occurs
        */
       public void error( final SAXParseException exception )
           throws SAXException
  @@ -137,6 +185,8 @@
   
       /**
        * This just throws an exception on a parse error.
  +     * @param exception the parse error
  +     * @exception SAXException if an error occurs
        */
       public void warning( final SAXParseException exception )
           throws SAXException
  @@ -146,6 +196,8 @@
   
       /**
        * This just throws an exception on a parse error.
  +     * @param exception the parse error
  +     * @exception SAXException if an error occurs
        */
       public void fatalError( final SAXParseException exception )
           throws SAXException
  @@ -153,6 +205,11 @@
           throw exception;
       }
   
  +    /**
  +     * Returns a string showing the current system ID, line number and column number.
  +     *
  +     * @return a <code>String</code> value
  +     */
       protected String getLocationString()
       {
           if( null == m_locator )
  
  
  
  1.5       +2 -0      jakarta-avalon/src/java/org/apache/avalon/framework/context/Resolvable.java
  
  Index: Resolvable.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/context/Resolvable.java,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- Resolvable.java	11 Dec 2001 09:00:45 -0000	1.4
  +++ Resolvable.java	21 Mar 2002 14:51:13 -0000	1.5
  @@ -12,6 +12,7 @@
    * resolved in some particular context.
    *
    * @author <a href="mailto:peter@apache.org">Peter Donald</a>
  + * @version 1.0
    */
   public interface Resolvable
   {
  @@ -20,6 +21,7 @@
        *
        * @param context the contextwith respect which to resolve
        * @return the resolved object
  +     * @exception ContextException if an error occurs
        */
       Object resolve( Context context )
           throws ContextException;
  
  
  
  1.13      +6 -2      jakarta-avalon/src/java/org/apache/avalon/framework/logger/AvalonFormatter.java
  
  Index: AvalonFormatter.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/logger/AvalonFormatter.java,v
  retrieving revision 1.12
  retrieving revision 1.13
  diff -u -r1.12 -r1.13
  --- AvalonFormatter.java	15 Mar 2002 14:14:57 -0000	1.12
  +++ AvalonFormatter.java	21 Mar 2002 14:51:13 -0000	1.13
  @@ -58,7 +58,8 @@
        * @param printCascading true enables printing of nested exceptions,
        *   false only prints out the outermost exception
        */
  -    public AvalonFormatter( final String pattern, final int stackDepth, final boolean printCascading )
  +    public AvalonFormatter( final String pattern, final int stackDepth, 
  +                            final boolean printCascading )
       {
           super( pattern );
           m_stackDepth = stackDepth;
  @@ -74,7 +75,10 @@
        */
       protected String getStackTrace( final Throwable throwable, final String format )
       {
  -        if( null == throwable ) return "";
  +        if( null == throwable ) 
  +        {
  +            return "";
  +        }
           return ExceptionUtil.printStackTrace( throwable, m_stackDepth, m_printCascading );
       }
   }
  
  
  
  1.4       +105 -6    jakarta-avalon/src/java/org/apache/avalon/framework/logger/ConsoleLogger.java
  
  Index: ConsoleLogger.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/logger/ConsoleLogger.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- ConsoleLogger.java	12 Mar 2002 11:43:45 -0000	1.3
  +++ ConsoleLogger.java	21 Mar 2002 14:51:13 -0000	1.4
  @@ -14,16 +14,28 @@
    *
    * @author <a href="mailto:leo.sutic@inspireinfrastructure.com">Leo Sutic</a>
    * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
  + * @version 1.0
    */
   public final class ConsoleLogger
       implements Logger
   {
  -    public final static int LEVEL_DEBUG = 0;
  -    public final static int LEVEL_INFO = 1;
  -    public final static int LEVEL_WARN = 2;
  -    public final static int LEVEL_ERROR = 3;
  -    public final static int LEVEL_FATAL = 4;
  -    public final static int LEVEL_DISABLED = 5;
  +    /** Typecode for debugging messages. */
  +    public static final int LEVEL_DEBUG = 0;
  +
  +    /** Typecode for informational messages. */
  +    public static final int LEVEL_INFO = 1;
  +
  +    /** Typecode for warning messages. */
  +    public static final int LEVEL_WARN = 2;
  +
  +    /** Typecode for error messages. */
  +    public static final int LEVEL_ERROR = 3;
  +
  +    /** Typecode for fatal error messages. */
  +    public static final int LEVEL_FATAL = 4;
  +
  +    /** Typecode for disabled log levels. */
  +    public static final int LEVEL_DISABLED = 5;
   
       private final int m_logLevel;
   
  @@ -37,17 +49,29 @@
   
       /**
        * Creates a new ConsoleLogger.
  +     * @param logLevel log level typecode
        */
       public ConsoleLogger( final int logLevel )
       {
           m_logLevel = logLevel;
       }
   
  +    /**
  +     * Logs a debugging message.
  +     *
  +     * @param message a <code>String</code> value
  +     */
       public void debug( final String message )
       {
           debug( message, null );
       }
   
  +    /**
  +     * Logs a debugging message and an exception.
  +     *
  +     * @param message a <code>String</code> value
  +     * @param throwable a <code>Throwable</code> value
  +     */
       public void debug( final String message, final Throwable throwable )
       {
           if ( m_logLevel <= LEVEL_DEBUG )
  @@ -62,16 +86,32 @@
           }
       }
   
  +    /**
  +     * Returns <code>true</code> if debug-level logging is enabled, false otherwise.
  +     *
  +     * @return <code>true</code> if debug-level logging
  +     */
       public boolean isDebugEnabled()
       {
           return m_logLevel <= LEVEL_DEBUG;
       }
   
  +    /**
  +     * Logs an informational message.
  +     *
  +     * @param message a <code>String</code> value
  +     */
       public void info( final String message )
       {
           info( message, null );
       }
   
  +    /**
  +     * Logs an informational message and an exception.
  +     *
  +     * @param message a <code>String</code> value
  +     * @param throwable a <code>Throwable</code> value
  +     */
       public void info( final String message, final Throwable throwable )
       {
           if ( m_logLevel <= LEVEL_INFO )
  @@ -86,16 +126,32 @@
           }
       }
   
  +    /**
  +     * Returns <code>true</code> if info-level logging is enabled, false otherwise.
  +     *
  +     * @return <code>true</code> if info-level logging is enabled
  +     */
       public boolean isInfoEnabled()
       {
           return m_logLevel <= LEVEL_INFO;
       }
   
  +    /**
  +     * Logs a warning message.
  +     *
  +     * @param message a <code>String</code> value
  +     */
       public void warn( final String message )
       {
           warn( message, null );
       }
   
  +    /**
  +     * Logs a warning message and an exception.
  +     *
  +     * @param message a <code>String</code> value
  +     * @param throwable a <code>Throwable</code> value
  +     */
       public void warn(final String message, final Throwable throwable)
       {
           if ( m_logLevel <= LEVEL_WARN )
  @@ -110,16 +166,32 @@
           }
       }
   
  +    /**
  +     * Returns <code>true</code> if warn-level logging is enabled, false otherwise.
  +     *
  +     * @return <code>true</code> if warn-level logging is enabled
  +     */
       public boolean isWarnEnabled()
       {
           return m_logLevel <= LEVEL_WARN;
       }
   
  +    /**
  +     * Logs an error message.
  +     *
  +     * @param message a <code>String</code> value
  +     */
       public void error( final String message )
       {
           error( message, null );
       }
   
  +    /**
  +     * Logs an error message and an exception.
  +     *
  +     * @param message a <code>String</code> value
  +     * @param throwable a <code>Throwable</code> value
  +     */
       public void error( final String message, final Throwable throwable )
       {
           if ( m_logLevel <= LEVEL_ERROR )
  @@ -134,16 +206,32 @@
           }
       }
   
  +    /**
  +     * Returns <code>true</code> if error-level logging is enabled, false otherwise.
  +     *
  +     * @return <code>true</code> if error-level logging is enabled
  +     */
       public boolean isErrorEnabled()
       {
           return m_logLevel <= LEVEL_ERROR;
       }
   
  +    /**
  +     * Logs a fatal error message.
  +     *
  +     * @param message a <code>String</code> value
  +     */
       public void fatalError( final String message )
       {
           fatalError( message, null );
       }
   
  +    /**
  +     * Logs a fatal error message and an exception.
  +     *
  +     * @param message a <code>String</code> value
  +     * @param throwable a <code>Throwable</code> value
  +     */
       public void fatalError( final String message, final Throwable throwable )
       {
           if ( m_logLevel <= LEVEL_FATAL )
  @@ -158,11 +246,22 @@
           }
       }
   
  +    /**
  +     * Returns <code>true</code> if fatal-level logging is enabled, false otherwise.
  +     *
  +     * @return <code>true</code> if fatal-level logging is enabled
  +     */
       public boolean isFatalErrorEnabled()
       {
           return m_logLevel <= LEVEL_FATAL;
       }
   
  +    /**
  +     * Just returns this logger (<code>ConsoleLogger</code> is not hierarchical).
  +     *
  +     * @param name ignored
  +     * @return this logger
  +     */
       public Logger getChildLogger( final String name )
       {
           return this;
  
  
  
  1.7       +1 -1      jakarta-avalon/src/java/org/apache/avalon/framework/logger/Jdk14Logger.java
  
  Index: Jdk14Logger.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/logger/Jdk14Logger.java,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- Jdk14Logger.java	11 Dec 2001 09:00:46 -0000	1.6
  +++ Jdk14Logger.java	21 Mar 2002 14:51:13 -0000	1.7
  @@ -207,10 +207,10 @@
       /**
        * Create a new child logger.
        * The name of the child logger is [current-loggers-name].[passed-in-name]
  +     * Throws <code>IllegalArgumentException</code> if name has an empty element name
        *
        * @param name the subname of this logger
        * @return the new logger
  -     * @exception IllegalArgumentException if name has an empty element name
        */
       public final Logger getChildLogger( final String name )
       {
  
  
  
  1.6       +1 -1      jakarta-avalon/src/java/org/apache/avalon/framework/logger/Log4JLogger.java
  
  Index: Log4JLogger.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/logger/Log4JLogger.java,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- Log4JLogger.java	11 Dec 2001 09:00:46 -0000	1.5
  +++ Log4JLogger.java	21 Mar 2002 14:51:13 -0000	1.6
  @@ -190,10 +190,10 @@
       /**
        * Create a new child logger.
        * The name of the child logger is [current-loggers-name].[passed-in-name]
  +     * Throws <code>IllegalArgumentException</code> if name has an empty element name
        *
        * @param name the subname of this logger
        * @return the new logger
  -     * @exception IllegalArgumentException if name has an empty element name
        */
       public final Logger getChildLogger( final String name )
       {
  
  
  
  1.5       +1 -1      jakarta-avalon/src/java/org/apache/avalon/framework/logger/LogKitLogger.java
  
  Index: LogKitLogger.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/logger/LogKitLogger.java,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- LogKitLogger.java	11 Dec 2001 09:00:46 -0000	1.4
  +++ LogKitLogger.java	21 Mar 2002 14:51:13 -0000	1.5
  @@ -187,10 +187,10 @@
       /**
        * Create a new child logger.
        * The name of the child logger is [current-loggers-name].[passed-in-name]
  +     * Throws <code>IllegalArgumentException</code> if name has an empty element name
        *
        * @param name the subname of this logger
        * @return the new logger
  -     * @exception IllegalArgumentException if name has an empty element name
        */
       public final Logger getChildLogger( final String name )
       {
  
  
  
  1.5       +1 -1      jakarta-avalon/src/java/org/apache/avalon/framework/logger/Logger.java
  
  Index: Logger.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/logger/Logger.java,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- Logger.java	11 Dec 2001 09:00:46 -0000	1.4
  +++ Logger.java	21 Mar 2002 14:51:13 -0000	1.5
  @@ -129,10 +129,10 @@
       /**
        * Create a new child logger.
        * The name of the child logger is [current-loggers-name].[passed-in-name]
  +     * Throws <code>IllegalArgumentException</code> if name has an empty element name
        *
        * @param name the subname of this logger
        * @return the new logger
  -     * @exception IllegalArgumentException if name has an empty element name
        */
       Logger getChildLogger( String name );
   }
  
  
  
  1.3       +90 -0     jakarta-avalon/src/java/org/apache/avalon/framework/logger/NullLogger.java
  
  Index: NullLogger.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/logger/NullLogger.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- NullLogger.java	11 Feb 2002 15:08:58 -0000	1.2
  +++ NullLogger.java	21 Mar 2002 14:51:13 -0000	1.3
  @@ -14,78 +14,168 @@
    * It also helps when you have a utility that does not have a logger to supply.
    *
    * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
  + * @version 1.0
    */
   public final class NullLogger implements Logger
   {
  +    /**
  +     * Creates a new <code>NullLogger</code>.
  +     */
       public NullLogger()
       {
       }
   
  +    /**
  +     * No-op.
  +     *
  +     * @param message ignored
  +     */
       public void debug(String message)
       {
       }
   
  +    /**
  +     * No-op.
  +     *
  +     * @param message ignored
  +     * @param throwable ignored
  +     */
       public void debug(String message, Throwable throwable)
       {
       }
   
  +    /**
  +     * No-op.
  +     *
  +     * @return <code>false</code>
  +     */
       public boolean isDebugEnabled()
       {
           return false;
       }
   
  +    /**
  +     * No-op.
  +     *
  +     * @param message ignored
  +     */
       public void info(String message)
       {
       }
   
  +    /**
  +     * No-op.
  +     *
  +     * @param message ignored
  +     * @param throwable ignored
  +     */
       public void info(String message, Throwable throwable)
       {
       }
   
  +    /**
  +     * No-op.
  +     *
  +     * @return <code>false</code>
  +     */
       public boolean isInfoEnabled()
       {
           return false;
       }
   
  +    /**
  +     * No-op.
  +     *
  +     * @param message ignored
  +     */
       public void warn(String message)
       {
       }
   
  +    /**
  +     * No-op.
  +     *
  +     * @param message ignored
  +     * @param throwable ignored
  +     */
       public void warn(String message, Throwable throwable)
       {
       }
   
  +    /**
  +     * No-op.
  +     *
  +     * @return <code>false</code>
  +     */
       public boolean isWarnEnabled()
       {
           return false;
       }
   
  +    /**
  +     * No-op.
  +     *
  +     * @param message ignored
  +     */
       public void error(String message)
       {
       }
   
  +    /**
  +     * No-op.
  +     *
  +     * @param message ignored
  +     * @param throwable ignored
  +     */
       public void error(String message, Throwable throwable)
       {
       }
   
  +    /**
  +     * No-op.
  +     *
  +     * @return <code>false</code>
  +     */
       public boolean isErrorEnabled()
       {
           return false;
       }
   
  +    /**
  +     * No-op.
  +     *
  +     * @param message ignored
  +     */
       public void fatalError(String message)
       {
       }
   
  +    /**
  +     * No-op.
  +     *
  +     * @param message ignored
  +     * @param throwable ignored
  +     */
       public void fatalError(String message, Throwable throwable)
       {
       }
   
  +    /**
  +     * No-op.
  +     *
  +     * @return <code>false</code>
  +     */
       public boolean isFatalErrorEnabled()
       {
           return false;
       }
   
  +    /**
  +     * Returns this <code>NullLogger</code>.
  +     *
  +     * @param name ignored
  +     * @return this <code>NullLogger</code>
  +     */
       public Logger getChildLogger(String name)
       {
           return this;
  
  
  
  1.22      +17 -5     jakarta-avalon/src/java/org/apache/avalon/framework/parameters/Parameters.java
  
  Index: Parameters.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/parameters/Parameters.java,v
  retrieving revision 1.21
  retrieving revision 1.22
  diff -u -r1.21 -r1.22
  --- Parameters.java	28 Feb 2002 13:35:58 -0000	1.21
  +++ Parameters.java	21 Mar 2002 14:51:13 -0000	1.22
  @@ -44,6 +44,7 @@
    *
    * @author <a href="mailto:fumagalli@exoffice.com">Pierpaolo Fumagalli</a>
    * @author <a href="mailto:peter@apache.org">Peter Donald</a>
  + * @version 1.0
    */
   public class Parameters
       implements Serializable
  @@ -68,6 +69,8 @@
        * <p />
        * If the specified value is <b>null</b> the parameter is removed.
        *
  +     * @param name a <code>String</code> value
  +     * @param value a <code>String</code> value
        * @return The previous value of the parameter or <b>null</b>.
        * @exception IllegalStateException if the Parameters object is read-only
        */
  @@ -91,6 +94,7 @@
   
       /**
        * Remove a parameter from the parameters object
  +     * @param name a <code>String</code> value
        */
       public void removeParameter( final String name )
       {
  @@ -136,7 +140,7 @@
        *
        * @param name the name of parameter
        * @return the value of parameter
  -     * @throws ParameterException
  +     * @throws ParameterException if the specified parameter cannot be found
        */
       public String getParameter( final String name )
           throws ParameterException
  @@ -189,7 +193,7 @@
        *
        * @param name the name of parameter
        * @return the integer parameter type
  -     * @throws ParameterException
  +     * @throws ParameterException if the specified parameter cannot be found
        */
       public int getParameterAsInteger( final String name )
           throws ParameterException
  @@ -256,7 +260,7 @@
        *
        * @param name the name of parameter
        * @return the long parameter type
  -     * @throws ParameterException
  +     * @throws ParameterException  if the specified parameter cannot be found
        */
       public long getParameterAsLong( final String name )
           throws ParameterException
  @@ -320,7 +324,7 @@
        *
        * @param name the parameter name
        * @return the value
  -     * @throws ParameterException
  +     * @throws ParameterException if the specified parameter cannot be found
        */
       public float getParameterAsFloat( final String name )
           throws ParameterException
  @@ -364,7 +368,8 @@
        *
        * @param name the parameter name
        * @return the value
  -     * @throws ParemterException
  +     * @exception ParameterException if an error occurs
  +     * @exception ParemterException
        */
       public boolean getParameterAsBoolean( final String name )
           throws ParameterException
  @@ -449,6 +454,11 @@
           m_readOnly = true;
       }
   
  +    /**
  +     * Checks is this <code>Parameters</code> object is writeable.
  +     *
  +     * @exception IllegalStateException if this <code>Parameters</code> object is read-only
  +     */
       protected final void checkWriteable()
           throws IllegalStateException
       {
  @@ -467,6 +477,7 @@
        *
        * @param configuration the Configuration
        * @return This <code>Parameters</code> instance.
  +     * @exception ConfigurationException if an error occurs
        */
       public static Parameters fromConfiguration( final Configuration configuration )
           throws ConfigurationException
  @@ -481,6 +492,7 @@
        * @param configuration the Configuration
        * @param elementName   the element name for the parameters
        * @return This <code>Parameters</code> instance.
  +     * @exception ConfigurationException if an error occurs
        */
       public static Parameters fromConfiguration( final Configuration configuration,
                                                   final String elementName )
  
  
  
  1.3       +21 -3     jakarta-avalon/src/java/org/apache/avalon/framework/service/DefaultServiceManager.java
  
  Index: DefaultServiceManager.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/service/DefaultServiceManager.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- DefaultServiceManager.java	21 Feb 2002 17:03:47 -0000	1.2
  +++ DefaultServiceManager.java	21 Mar 2002 14:51:13 -0000	1.3
  @@ -19,6 +19,7 @@
    * @author <a href="mailto:fede@apache.org">Federico Barbieri</a>
    * @author <a href="mailto:peter@apache.org">Peter Donald</a>
    * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
  + * @version 1.0
    */
   public class DefaultServiceManager
       implements ServiceManager
  @@ -72,7 +73,14 @@
           }
       }
   
  -    public boolean hasService( final String role ) {
  +    /**
  +     * Check to see if a <code>Object</code> exists for a role.
  +     *
  +     * @param role  a string identifying the role to check.
  +     * @return True if the object exists, False if it does not.
  +     */
  +    public boolean hasService( final String role ) 
  +    {
           boolean objectExists = false;
   
           try
  @@ -91,7 +99,7 @@
        * Place Object into ComponentManager.
        *
        * @param role the components role
  -     * @param component the component
  +     * @param object an <code>Object</code> value
        */
       public void put( final String role, final Object object )
       {
  @@ -140,17 +148,27 @@
           return m_objects;
       }
   
  +    /**
  +     * Makes this service manager read-only.
  +     *
  +     */
       public void makeReadOnly()
       {
           m_readOnly = true;
       }
   
  +    /**
  +     * Checks if this service manager is writeable.
  +     *
  +     * @exception IllegalStateException if this service manager is read-only
  +     */
       protected final void checkWriteable()
           throws IllegalStateException
       {
           if( m_readOnly )
           {
  -            throw new IllegalStateException( "ServiceManager is read only and can not be modified" );
  +            throw new IllegalStateException
  +                ( "ServiceManager is read only and can not be modified" );
           }
       }
   
  
  
  
  1.2       +19 -3     jakarta-avalon/src/java/org/apache/avalon/framework/service/DefaultServiceSelector.java
  
  Index: DefaultServiceSelector.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/service/DefaultServiceSelector.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- DefaultServiceSelector.java	21 Feb 2002 16:31:08 -0000	1.1
  +++ DefaultServiceSelector.java	21 Mar 2002 14:51:13 -0000	1.2
  @@ -15,6 +15,7 @@
    *
    * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
    * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
  + * @version 1.0
    */
   public class DefaultServiceSelector
       implements ServiceSelector
  @@ -47,8 +48,11 @@
   
       /**
        * Returns whether a Object exists or not
  +     * @param hint the hint to retrieve Object
  +     * @return <code>true</code> if the Object exists
        */
  -    public boolean isSelectable( final Object hint ) {
  +    public boolean isSelectable( final Object hint ) 
  +    {
           boolean objectExists = false;
   
           try
  @@ -67,7 +71,7 @@
       /**
        * Release object.
        *
  -     * @param <code>Object</code> the object to release
  +     * @param object the <code>Object</code> to release
        */
       public void release( final Object object )
       {
  @@ -77,6 +81,8 @@
   
       /**
        * Populate the ServiceSelector.
  +     * @param hint the hint to be used to retrieve the Object later
  +     * @param object the Object to hold
        */
       public void put( final Object hint, final Object object )
       {
  @@ -94,16 +100,26 @@
           return m_objects;
       }
   
  +    /**
  +     * Makes this service selector read-only.
  +     *
  +     */
       public void makeReadOnly()
       {
           m_readOnly = true;
       }
   
  +    /**
  +     * Checks if this service selector is writeable.
  +     *
  +     * @exception IllegalStateException if this service selector is read-only
  +     */
       protected final void checkWriteable()
           throws IllegalStateException
       {
           if( m_readOnly )
           {
  -            throw new IllegalStateException( "ServiceSelector is read only and can not be modified" );       }
  +            throw new IllegalStateException
  +                ( "ServiceSelector is read only and can not be modified" );       }
       }
   }
  
  
  
  1.2       +6 -4      jakarta-avalon/src/java/org/apache/avalon/framework/service/ServiceManager.java
  
  Index: ServiceManager.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/service/ServiceManager.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- ServiceManager.java	21 Feb 2002 04:36:35 -0000	1.1
  +++ ServiceManager.java	21 Mar 2002 14:51:13 -0000	1.2
  @@ -32,14 +32,15 @@
    * Therefore the <code>ServiceManager</code> can be implemented with a
    * factory pattern, an object pool, or a simple Hashtable.
    *
  - * @see org.apache.avalon.framework.service.Serviceable
  - * @see org.apache.avalon.framework.service.ServiceSelector
  - *
    * @author <a href="mailto:scoobie@betaversion.org">Federico Barbieri</a>
    * @author <a href="mailto:stefano@apache.org">Stefano Mazzocchi</a>
    * @author <a href="mailto:fumagalli@exoffice.com">Pierpaolo Fumagalli</a>
    * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
    * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
  + * @version 1.0
  + * @see org.apache.avalon.framework.service.Serviceable
  + * @see org.apache.avalon.framework.service.ServiceSelector
  + *
    */
   public interface ServiceManager
   {
  @@ -60,7 +61,8 @@
        * }
        * </pre>
        *
  -     * @param name The role name of the <code>Object</code> to retrieve.
  +     * @param role The role name of the <code>Object</code> to retrieve.
  +     * @return an <code>Object</code> value
        * @exception ServiceException if an error occurs
        */
       Object lookup( String role )
  
  
  
  1.2       +5 -3      jakarta-avalon/src/java/org/apache/avalon/framework/service/ServiceSelector.java
  
  Index: ServiceSelector.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/service/ServiceSelector.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- ServiceSelector.java	21 Feb 2002 04:36:35 -0000	1.1
  +++ ServiceSelector.java	21 Mar 2002 14:51:13 -0000	1.2
  @@ -12,11 +12,12 @@
    * supplied policy.  The contract is that all the <code>Object</code>s implement the
    * same role.
    *
  + * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
  + * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
  + * @version 1.0
    * @see org.apache.avalon.framework.service.Serviceable
    * @see org.apache.avalon.framework.service.ServiceManager
    *
  - * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
  - * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
    */
   public interface ServiceSelector
   {
  @@ -40,7 +41,8 @@
        *
        * @param policy A criteria against which a <code>Object</code> is selected.
        *
  -     * @exception ServiceSelector If the requested <code>Object</code> cannot be supplied
  +     * @return an <code>Object</code> value
  +     * @exception ServiceException If the requested <code>Object</code> cannot be supplied
        */
       Object select( Object policy )
           throws ServiceException;
  
  
  
  1.4       +4 -2      jakarta-avalon/src/java/org/apache/avalon/framework/service/Serviceable.java
  
  Index: Serviceable.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/service/Serviceable.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- Serviceable.java	28 Feb 2002 13:35:58 -0000	1.3
  +++ Serviceable.java	21 Mar 2002 14:51:13 -0000	1.4
  @@ -20,13 +20,14 @@
    * the <code>compose</code> method before the <code>Serviceable</code> 
    * can be considered valid. 
    *
  - * @see org.apache.avalon.framework.service.ServiceManager
  - *
    * @author <a href="mailto:fede@apache.org">Federico Barbieri</a>
    * @author <a href="mailto:pier@apache.org">Pierpaolo Fumagalli</a>
    * @author <a href="mailto:stefano@apache.org">Stefano Mazzocchi</a>
    * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
    * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
  + * @version 1.0
  + * @see org.apache.avalon.framework.service.ServiceManager
  + *
    */
   public interface Serviceable
   {
  @@ -38,6 +39,7 @@
        *
        * @param manager The <code>ServiceManager</code> which this
        *                <code>Serviceable</code> uses.
  +     * @exception ServiceException if an error occurs
        */
       void service( ServiceManager manager )
           throws ServiceException;
  
  
  

--
To unsubscribe, e-mail:   <mailto:avalon-cvs-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-cvs-help@jakarta.apache.org>


Mime
View raw message