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 <[EMAIL PROTECTED]>
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:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Peter Donald</a>
* @author <a href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Peter Donald</a>
* @author <a href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
* @author <a href="mailto:[EMAIL PROTECTED]">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>[EMAIL PROTECTED] #getName
getName}()</code></td><td colspan="2">my-system</td></tr>
- * <tr align="center"><td align="left"><code>[EMAIL PROTECTED]
#getAttributeNames
getAttributeNames}().length</code></td><td>2</td><td>1</td></tr>
- * <tr align="center"><td align="left"><code>[EMAIL PROTECTED] #getChildren
getChildren}().length</code></td><td colspan="2">2</td></tr>
- * <tr align="center"><td align="left"><code>[EMAIL PROTECTED]
#getAttributeAsFloat getAttributeAsFloat}("version")</code></td><td
colspan="2">1.3</td></tr>
- * <tr align="center"><td align="left"><code>[EMAIL PROTECTED] #getChild
getChild}("widget")[EMAIL PROTECTED] #getAttribute
getAttribute}("name")</code></td><td colspan="2">fooWidget</td></tr>
- * <tr align="center"><td align="left"><code>[EMAIL PROTECTED] #getChild
getChild}("widget")[EMAIL PROTECTED] #getAttributeAsBoolean
getAttributeAsBoolean}("threadsafe")</code></td><td
colspan="2"><code>true</code></td></tr>
- * <tr align="center"><td align="left"><code>[EMAIL PROTECTED] #getChild
getChild}("widget")[EMAIL PROTECTED] #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>[EMAIL PROTECTED] #getChild
getChild}("desc")[EMAIL PROTECTED] #getName getName}()</code></td><td>desc (see
[EMAIL PROTECTED] #getChild(String)})</td><td>desc</td></tr>
- * <tr align="center"><td align="left"><code>[EMAIL PROTECTED] #getChild
getChild}("doc:desc")[EMAIL PROTECTED] #getName
getName}()</code></td><td>doc:desc</td><td>doc:desc (see [EMAIL PROTECTED]
#getChild(String)})</td></tr>
- * <tr align="center"><td align="left"><code>[EMAIL PROTECTED] #getChild
getChild}("desc")[EMAIL PROTECTED] #getValue getValue}()</code></td><td>[EMAIL
PROTECTED] ConfigurationException}</td><td>This is a highly fictitious config
file</td></tr>
- * <tr align="center"><td align="left"><code>[EMAIL PROTECTED] #getChild
getChild}("doc:desc")[EMAIL PROTECTED] #getValue
getValue}()</code></td><td>This is a highly fictitious config
file</td><td>[EMAIL PROTECTED] ConfigurationException}</td></tr>
- * <tr align="center"><td align="left"><code>[EMAIL PROTECTED] #getChild
getChild}("desc")[EMAIL PROTECTED] #getNamespace
getNamespace}()</code></td><td> </td><td>http://myco.com/documentation";</td></tr>
+ * <tr align="center"><td align="left">
+ * <code>[EMAIL PROTECTED] #getName getName}()</code></td><td
colspan="2">my-system</td></tr>
+ * <tr align="center"><td align="left">
+ * <code>[EMAIL PROTECTED] #getAttributeNames
getAttributeNames}().length</code>
+ * </td><td>2</td><td>1</td></tr>
+ * <tr align="center"><td align="left">
+ * <code>[EMAIL PROTECTED] #getChildren getChildren}().length</code>
+ * </td><td colspan="2">2</td></tr>
+ * <tr align="center"><td align="left">
+ * <code>[EMAIL PROTECTED] #getAttributeAsFloat
getAttributeAsFloat}("version")</code>
+ * </td><td colspan="2">1.3</td></tr>
+ * <tr align="center"><td align="left">
+ * <code>[EMAIL PROTECTED] #getChild getChild}("widget")[EMAIL PROTECTED]
#getAttribute getAttribute}("name")</code>
+ * </td><td colspan="2">fooWidget</td></tr>
+ * <tr align="center"><td align="left">
+ * <code>[EMAIL PROTECTED] #getChild getChild}("widget")
+ * [EMAIL PROTECTED] #getAttributeAsBoolean
getAttributeAsBoolean}("threadsafe")</code></td><td colspan="2">
+ * <code>true</code></td></tr>
+ * <tr align="center"><td align="left">
+ * <code>[EMAIL PROTECTED] #getChild getChild}("widget")[EMAIL PROTECTED]
#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>[EMAIL PROTECTED] #getChild getChild}("desc")[EMAIL PROTECTED]
#getName getName}()</code>
+ * </td><td>desc (see [EMAIL PROTECTED]
#getChild(String)})</td><td>desc</td></tr>
+ * <tr align="center"><td align="left">
+ * <code>[EMAIL PROTECTED] #getChild getChild}("doc:desc")[EMAIL PROTECTED]
#getName getName}()</code>
+ * </td><td>doc:desc</td><td>doc:desc (see [EMAIL PROTECTED]
#getChild(String)})</td></tr>
+ * <tr align="center"><td align="left">
+ * <code>[EMAIL PROTECTED] #getChild getChild}("desc")[EMAIL PROTECTED]
#getValue getValue}()</code>
+ * </td><td>[EMAIL PROTECTED] ConfigurationException}</td><td>This is a
highly fictitious config file</td></tr>
+ * <tr align="center"><td align="left">
+ * <code>[EMAIL PROTECTED] #getChild getChild}("doc:desc")[EMAIL PROTECTED]
#getValue getValue}()</code>
+ * </td><td>This is a highly fictitious config file</td><td>[EMAIL
PROTECTED] ConfigurationException}</td></tr>
+ * <tr align="center"><td align="left">
+ * <code>[EMAIL PROTECTED] #getChild getChild}("desc")[EMAIL PROTECTED]
#getNamespace getNamespace}()</code>
+ * </td><td> </td><td>http://myco.com/documentation";</td></tr>
* </table>
* </p>
* <p>
@@ -105,15 +129,16 @@
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
* @author <a href="mailto:[EMAIL PROTECTED]">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 [EMAIL PROTECTED] #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:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @author <a href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
* @author <a href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
* @author <a href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Leo Sutic</a>
* @author <a href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @author <a href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
* @author <a href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Berin Loritsch</a>
* @author <a href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
* @author <a href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Berin Loritsch</a>
+ * @author <a href="mailto:[EMAIL PROTECTED]">Stephen McConnell</a>
+ * @version 1.0
* @see org.apache.avalon.framework.service.Serviceable
* @see org.apache.avalon.framework.service.ServiceManager
*
- * @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
- * @author <a href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
* @author <a href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
