From 99a9ac4d5e67a0448bc3ed8a00b999301a3d2410 Mon Sep 17 00:00:00 2001 From: Henri Yandell Date: Mon, 14 Jul 2003 22:22:46 +0000 Subject: [PATCH] Javadoc fixes and a refactoring to use StringUtils. git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/lang/trunk@137415 13f79535-47bb-0310-9956-ffa450edef68 --- .../org/apache/commons/lang/enum/Enum.java | 175 +++++++++++------- .../lang/exception/ExceptionUtils.java | 117 ++++++------ 2 files changed, 167 insertions(+), 125 deletions(-) diff --git a/src/java/org/apache/commons/lang/enum/Enum.java b/src/java/org/apache/commons/lang/enum/Enum.java index d03b322b8..f1558b3c4 100644 --- a/src/java/org/apache/commons/lang/enum/Enum.java +++ b/src/java/org/apache/commons/lang/enum/Enum.java @@ -62,21 +62,23 @@ import java.util.HashMap; import java.util.Iterator; import java.util.List; import java.util.Map; +import org.apache.commons.lang.StringUtils; /** - * Abstract superclass for type-safe enums. - *

- * One feature of the C programming language lacking in Java is enumerations. The + *

Abstract superclass for type-safe enums.

+ * + *

One feature of the C programming language lacking in Java is enumerations. The * C implementation based on ints was poor and open to abuse. The original Java * recommendation and most of the JDK also uses int constants. It has been recognised * however that a more robust type-safe class-based solution can be designed. This - * class follows the basic Java type-safe enumeration pattern. - *

- * NOTE:Due to the way in which Java ClassLoaders work, comparing Enum objects + * class follows the basic Java type-safe enumeration pattern.

+ * + *

NOTE:Due to the way in which Java ClassLoaders work, comparing Enum objects * should always be done using the equals() method, not ==. The equals() method will - * try == first so in most cases the effect is the same. + * try == first so in most cases the effect is the same.

* *

Simple Enums

- * To use this class, it must be subclassed. For example: + * + *

To use this class, it must be subclassed. For example:

* * 
  * public final class ColorEnum extends Enum {
@@ -105,19 +107,19 @@ import java.util.Map;
  *   }
  * }
  *
- *

- * As shown, each enum has a name. This can be accessed using getName. - *

- * The getEnum and iterator methods are recommended. + * + *

As shown, each enum has a name. This can be accessed using getName.

+ * + *

The getEnum and iterator methods are recommended. * Unfortunately, Java restrictions require these to be coded as shown in each subclass. - * An alternative choice is to use the {@link EnumUtils} class. + * An alternative choice is to use the {@link EnumUtils} class.

* *

Subclassed Enums

- * A hierarchy of Enum classes can be built. In this case, the superclass is + *

A hierarchy of Enum classes can be built. In this case, the superclass is * unaffected by the addition of subclasses (as per normal Java). The subclasses - * may add additional Enum constants of the type of the superclass. The + * may add additional Enum constants of the type of the superclass. The * query methods on the subclass will return all of the Enum constants from the - * superclass and subclass. + * superclass and subclass.

* * 
  * public class ExtraColorEnum extends ColorEnum {
@@ -146,15 +148,16 @@ import java.util.Map;
  *   }
  * }
  *
- * - * This example will return RED, GREEN, BLUE, YELLOW from the List and iterator + * + *

This example will return RED, GREEN, BLUE, YELLOW from the List and iterator * methods in that order. The RED, GREEN and BLUE instances will be the same (==) * as those from the superclass ColorEnum. Note that YELLOW is declared as a - * ColorEnum and not an ExtraColorEnum. + * ColorEnum and not an ExtraColorEnum.

* *

Functional Enums

- * The enums can have functionality by using anonymous inner classes - * [Effective Java, Bloch01]: + * + *

The enums can have functionality by using anonymous inner classes + * [Effective Java, Bloch01]:

* * 
  * public abstract class OperationEnum extends Enum {
@@ -192,26 +195,25 @@ import java.util.Map;
  *   }
  * }
  *
- *

- * NOTE: This class originated in the Jakarta Avalon project. - *

+ * + *

NOTE: This class originated in the Jakarta Avalon project.

* * @author Stephen Colebourne * @author Chris Webb * @author Mike Bowler * @since 1.0 - * @version $Id: Enum.java,v 1.10 2003/02/06 20:13:07 scolebourne Exp $ + * @version $Id: Enum.java,v 1.11 2003/07/14 22:20:20 bayard Exp $ */ public abstract class Enum implements Comparable, Serializable { // After discussion, the default size for HashMaps is used, as the // sizing algorithm changes across the JDK versions /** - * An empty map, as JDK1.2 didn't have an empty map + * An empty Map, as JDK1.2 didn't have an empty map. */ private static final Map EMPTY_MAP = Collections.unmodifiableMap(new HashMap(0)); /** - * Map, key of class name, value of Entry. + * Map, key of class name, value of Entry. */ private static final Map cEnumClasses = new HashMap(); /** @@ -220,30 +222,36 @@ public abstract class Enum implements Comparable, Serializable { private final String iName; /** - * Enable the iterator to retain the source code order + *

Enable the iterator to retain the source code order.

*/ private static class Entry { - /** Map of Enum name to Enum */ + /** + * Map of Enum name to Enum. + */ final Map map = new HashMap(); - /** List of Enums in source code order */ + /** + * List of Enums in source code order. + */ final List list = new ArrayList(25); /** - * Restrictive constructor + *

Restrictive constructor.

*/ private Entry() { } } /** - * Constructor to add a new named item to the enumeration. + *

Constructor to add a new named item to the enumeration.

* * @param name the name of the enum object - * @throws IllegalArgumentException if the name is null or a blank string + * @throws IllegalArgumentException if the name is null + * or a blank string */ protected Enum(String name) { super(); - if (name == null || name.length() == 0) { + + if (StringUtils.isEmpty(name)) { throw new IllegalArgumentException("The Enum name must not be empty or null"); } iName = name; @@ -261,8 +269,9 @@ public abstract class Enum implements Comparable, Serializable { } /** - * Handle the deserialization of the class to ensure that multiple - * copies are not wastefully created, or illegal enum types created. + *

Handle the deserialization of the class to ensure that multiple + * copies are not wastefully created, or illegal enum types created.

+ * * @return the resolved object */ protected Object readResolve() { @@ -276,12 +285,15 @@ public abstract class Enum implements Comparable, Serializable { //-------------------------------------------------------------------------------- /** - * Gets an Enum object by class and name. + *

Gets an Enum object by class and name.

* - * @param enumClass the class of the Enum to get, must not be null - * @param name the name of the Enum to get, may be null + * @param enumClass the class of the Enum to get, must not + * be null + * @param name the name of the Enum to get, + * may be null * @return the enum object, or null if the enum does not exist - * @throws IllegalArgumentException if the enum class is null + * @throws IllegalArgumentException if the enum class + * is null */ protected static Enum getEnum(Class enumClass, String name) { Entry entry = getEntry(enumClass); @@ -292,12 +304,16 @@ public abstract class Enum implements Comparable, Serializable { } /** - * Gets the Map of Enum objects by name using the Enum class. - * If the requested class has no enum objects an empty Map is returned. + *

Gets the Map of Enum objects by + * name using the Enum class.

+ * + *

If the requested class has no enum objects an empty + * Map is returned.

* - * @param enumClass the class of the Enum to get, must not be null + * @param enumClass the class of the Enum to get, + * must not be null * @return the enum object Map - * @throws IllegalArgumentException if the enum class is null + * @throws IllegalArgumentException if the enum class is null * @throws IllegalArgumentException if the enum class is not a subclass of Enum */ protected static Map getEnumMap(Class enumClass) { @@ -309,13 +325,17 @@ public abstract class Enum implements Comparable, Serializable { } /** - * Gets the List of Enum objects using the Enum class. - * The list is in the order that the objects were created (source code order). - * If the requested class has no enum objects an empty List is returned. + *

Gets the List of Enum objects using the + * Enum class.

+ * + *

The list is in the order that the objects were created (source code order). + * If the requested class has no enum objects an empty List is + * returned.

* - * @param enumClass the class of the Enum to get, must not be null + * @param enumClass the class of the Enum to get, + * must not be null * @return the enum object Map - * @throws IllegalArgumentException if the enum class is null + * @throws IllegalArgumentException if the enum class is null * @throws IllegalArgumentException if the enum class is not a subclass of Enum */ protected static List getEnumList(Class enumClass) { @@ -327,13 +347,17 @@ public abstract class Enum implements Comparable, Serializable { } /** - * Gets an iterator over the Enum objects in an Enum class. - * The iterator is in the order that the objects were created (source code order). - * If the requested class has no enum objects an empty Iterator is returned. + *

Gets an Iterator over the Enum objects in + * an Enum class.

+ * + *

The Iterator is in the order that the objects were + * created (source code order). If the requested class has no enum + * objects an empty Iterator is returned.

* - * @param enumClass the class of the Enum to get, must not be null + * @param enumClass the class of the Enum to get, + * must not be null * @return an iterator of the Enum objects - * @throws IllegalArgumentException if the enum class is null + * @throws IllegalArgumentException if the enum class is null * @throws IllegalArgumentException if the enum class is not a subclass of Enum */ protected static Iterator iterator(Class enumClass) { @@ -342,9 +366,9 @@ public abstract class Enum implements Comparable, Serializable { //----------------------------------------------------------------------- /** - * Gets an entry from the map of Enums. + *

Gets an Entry from the map of Enums.

* - * @param enumClass the class of the Enum to get + * @param enumClass the class of the Enum to get * @return the enum entry */ private static Entry getEntry(Class enumClass) { @@ -359,10 +383,11 @@ public abstract class Enum implements Comparable, Serializable { } /** - * Creates an entry for storing the Enums. - * This accounts for subclassed Enums. + *

Creates an Entry for storing the Enums.

+ * + *

This accounts for subclassed Enums.

* - * @param enumClass the class of the Enum to get + * @param enumClass the class of the Enum to get * @return the enum entry */ private static Entry createEntry(Class enumClass) { @@ -381,8 +406,9 @@ public abstract class Enum implements Comparable, Serializable { } /** - * Convert a class to the actual common enum class. - * This accounts for anonymous inner classes. + *

Convert a class to the actual common enum class.

+ * + *

This accounts for anonymous inner classes.

* * @param cls the class to get the name for * @return the class name @@ -404,7 +430,7 @@ public abstract class Enum implements Comparable, Serializable { //----------------------------------------------------------------------- /** - * Retrieve the name of this Enum item, set in the constructor. + *

Retrieve the name of this Enum item, set in the constructor.

* * @return the String name of this Enum item */ @@ -413,12 +439,14 @@ public abstract class Enum implements Comparable, Serializable { } /** - * Tests for equality. Two Enum objects are considered equal + *

Tests for equality.

+ * + *

Two Enum objects are considered equal * if they have the same class names and the same names. - * Identity is tested for first, so this method usually runs fast. + * Identity is tested for first, so this method usually runs fast.

* * @param other the other object to compare for equality - * @return true if the Enums are equal + * @return true if the Enums are equal */ public final boolean equals(Object other) { if (other == this) { @@ -455,7 +483,7 @@ public abstract class Enum implements Comparable, Serializable { } /** - * Returns a suitable hashCode for the enumeration. + *

Returns a suitable hashCode for the enumeration.

* * @return a hashcode based on the name */ @@ -464,21 +492,26 @@ public abstract class Enum implements Comparable, Serializable { } /** - * Tests for order. The default ordering is alphabetic by name, but this - * can be overridden by subclasses. + *

Tests for order.

+ * + *

The default ordering is alphabetic by name, but this + * can be overridden by subclasses.

* * @see java.lang.Comparable#compareTo(Object) * @param other the other object to compare to - * @return -ve if this is less than the other object, +ve if greater than, 0 of equal + * @return -ve if this is less than the other object, +ve if greater + * than, 0 of equal * @throws ClassCastException if other is not an Enum - * @throws NullPointerException if other is null + * @throws NullPointerException if other is null */ public int compareTo(Object other) { return iName.compareTo(((Enum) other).iName); } /** - * Human readable description of this Enum item. For use when debugging. + *

Human readable description of this Enum item.

+ * + *

For use when debugging.

* * @return String in the form type[name], for example: * Color[Red]. Note that the package name is stripped from diff --git a/src/java/org/apache/commons/lang/exception/ExceptionUtils.java b/src/java/org/apache/commons/lang/exception/ExceptionUtils.java index becc198a2..8b0b38c3e 100644 --- a/src/java/org/apache/commons/lang/exception/ExceptionUtils.java +++ b/src/java/org/apache/commons/lang/exception/ExceptionUtils.java @@ -65,8 +65,8 @@ import java.util.Arrays; import java.util.LinkedList; import java.util.List; import java.util.StringTokenizer; - import org.apache.commons.lang.ArrayUtils; +import org.apache.commons.lang.StringUtils; import org.apache.commons.lang.SystemUtils; /** @@ -78,20 +78,21 @@ import org.apache.commons.lang.SystemUtils; * @author Stephen Colebourne * @author Gary Gregory * @since 1.0 - * @version $Id: ExceptionUtils.java,v 1.24 2003/05/31 17:16:11 ggregory Exp $ + * @version $Id: ExceptionUtils.java,v 1.25 2003/07/14 22:22:46 bayard Exp $ */ public class ExceptionUtils { /** - * Used when printing stack frames to denote the start of a - * wrapped exception. Package private for accessibility by test - * suite. + *

Used when printing stack frames to denote the start of a + * wrapped exception.

+ * + *

Package private for accessibility by test suite.

*/ static final String WRAPPED_MARKER = " [wrapped] "; /** - * The names of methods commonly used to access a wrapped - * exception. + *

The names of methods commonly used to access a wrapped + * exception.

*/ protected static String[] CAUSE_METHOD_NAMES = { "getCause", @@ -105,8 +106,8 @@ public class ExceptionUtils { }; /** - * Constructs a new ExceptionUtils. Protected to - * discourage instantiation. + *

Constructs a new ExceptionUtils. Protected to + * discourage instantiation.

*/ protected ExceptionUtils() { } @@ -115,10 +116,11 @@ public class ExceptionUtils { *

Adds to the list of method names used in the search for Throwable * objects.

* - * @param methodName the methodName to add to the list, null and empty strings are ignored + * @param methodName the methodName to add to the list, null + * and empty strings are ignored */ public static void addCauseMethodName(String methodName) { - if (methodName != null && methodName.length() > 0) { + if(StringUtils.isNotEmpty(methodName)) { List list = new ArrayList(Arrays.asList(CAUSE_METHOD_NAMES)); list.add(methodName); CAUSE_METHOD_NAMES = (String[]) list.toArray(new String[list.size()]); @@ -132,17 +134,18 @@ public class ExceptionUtils { * Throwable object. This will pick up most wrapping exceptions, * including those from JDK 1.4, and * {@link org.apache.commons.lang.exception.NestableException NestableException}. - * The method names can be added to using {@link #addCauseMethodName(String)}. - * The default list searched for are:

+ * The method names can be added to using {@link #addCauseMethodName(String)}.

+ * + *

The default list searched for are:

* * *

In the absence of any such method, the object is inspected for a @@ -152,7 +155,7 @@ public class ExceptionUtils { * * @param throwable The exception to introspect for a cause. * @return The cause of the Throwable. - * @throws NullPointerException if the throwable is null + * @throws NullPointerException if the throwable is null */ public static Throwable getCause(Throwable throwable) { return getCause(throwable, CAUSE_METHOD_NAMES); @@ -164,8 +167,9 @@ public class ExceptionUtils { * * @param throwable The exception to introspect for a cause. * @return The cause of the Throwable. - * @throws NullPointerException if the method names array is null or contains null - * @throws NullPointerException if the throwable is null + * @throws NullPointerException if the method names array is null + * or contains null + * @throws NullPointerException if the throwable is null */ public static Throwable getCause(Throwable throwable, String[] methodNames) { Throwable cause = getCauseUsingWellKnownTypes(throwable); @@ -230,7 +234,7 @@ public class ExceptionUtils { * @param throwable the exception to examine * @param methodName the name of the method to find and invoke * @return The wrapped exception, or null if not - * found. + * found. */ private static Throwable getCauseUsingMethodName(Throwable throwable, String methodName) { Method method = null; @@ -257,7 +261,7 @@ public class ExceptionUtils { * @param throwable the exception to examine * @param fieldName the name of the attribute to examine * @return The wrapped exception, or null if not - * found. + * found. */ private static Throwable getCauseUsingFieldName(Throwable throwable, String fieldName) { Field field = null; @@ -354,14 +358,15 @@ public class ExceptionUtils { } /** - * Prints a compact stack trace for the root cause of a throwable. - * The compact stack trace starts with the root cause and prints + *

Prints a compact stack trace for the root cause of a throwable.

+ * + *

The compact stack trace starts with the root cause and prints * stack frames up to the place where it was caught and wrapped. * Then it prints the wrapped exception and continues with stack frames - * until the wrapper exception is caught and wrapped again, etc. - *

- * The method is equivalent to t.printStackTrace() for throwables - * that don't have nested causes. + * until the wrapper exception is caught and wrapped again, etc.

+ * + *

The method is equivalent to t.printStackTrace() for throwables + * that don't have nested causes.

*/ public static void printRootCauseStackTrace(Throwable t, PrintStream stream) { String trace[] = getRootCauseStackTrace(t); @@ -372,7 +377,7 @@ public class ExceptionUtils { } /** - * Equivalent to printRootCauseStackTrace(t, System.err); + *

Equivalent to printRootCauseStackTrace(t, System.err);

* * @see #printRootCauseStackTrace(Throwable,PrintWriter) */ @@ -381,8 +386,8 @@ public class ExceptionUtils { } /** - * Same as {@link #printRootCauseStackTrace(Throwable,java.io.PrintStream)}, except it takes - * a PrintWriter as an argument. + *

Same as {@link #printRootCauseStackTrace(Throwable,java.io.PrintStream)}, + * except it takes a PrintWriter as an argument.

*/ public static void printRootCauseStackTrace(Throwable t, PrintWriter writer) { String trace[] = getRootCauseStackTrace(t); @@ -393,8 +398,8 @@ public class ExceptionUtils { } /** - * Creates a compact stack trace for the root cause of the supplied - * Throwable. + *

Creates a compact stack trace for the root cause of the supplied + * Throwable.

*/ public static String[] getRootCauseStackTrace(Throwable t) { Throwable throwables[] = getThrowables(t); @@ -420,9 +425,9 @@ public class ExceptionUtils { } /** - * Removes common frames from the cause trace given the two stack traces. + *

Removes common frames from the cause trace given the two stack traces.

* - * @param causeFrames stack trace of a cause throwable + * @param causeFrames stack trace of a cause throwable * @param wrapperFrames stack trace of a wrapper throwable */ public static void removeCommonFrames(List causeFrames, List wrapperFrames) { @@ -442,12 +447,12 @@ public class ExceptionUtils { } /** - * A convenient way of extracting the stack trace from an - * exception. + *

A convenient way of extracting the stack trace from an + * exception.

* * @param t The Throwable. * @return The stack trace as generated by the exception's - * printStackTrace(PrintWriter) method. + * printStackTrace(PrintWriter) method. */ public static String getStackTrace(Throwable t) { StringWriter sw = new StringWriter(); @@ -457,7 +462,7 @@ public class ExceptionUtils { } /** - * A way to get the entire nested stack-trace of an throwable. + *

A way to get the entire nested stack-trace of an throwable.

* * @param t The Throwable. * @return The nested stack trace, with the root cause first. @@ -476,10 +481,11 @@ public class ExceptionUtils { } /** - * Returns whether a Throwable is considered nested or not. + *

Returns whether a Throwable is considered nested + * or not.

* - * @param t The Throwable. - * @return boolean true/false + * @param throwable The Throwable. + * @return boolean true if nested otherwise false */ public static boolean isNestedThrowable(Throwable throwable) { if(throwable == null) { @@ -519,9 +525,9 @@ public class ExceptionUtils { } /** - * Captures the stack trace associated with the specified + *

Captures the stack trace associated with the specified * Throwable object, decomposing it into a list of - * stack frames. + * stack frames.

* * @param t The Throwable. * @return An array of strings describing each stack frame. @@ -531,10 +537,10 @@ public class ExceptionUtils { } /** - * Functionality shared between the + *

Functionality shared between the * getStackFrames(Throwable) methods of this and the * {@link org.apache.commons.lang.exception.NestableDelegate} - * classes. + * classes.

*/ static String[] getStackFrames(String stackTrace) { String linebreak = SystemUtils.LINE_SEPARATOR; @@ -548,9 +554,12 @@ public class ExceptionUtils { } /** - * Produces a List of stack frames - the message is not included. - * This works in most cases - it will only fail if the exception message - * contains a line that starts with: " at". + *

Produces a List of stack frames - the message + * is not included.

+ * + *

This works in most cases - it will only fail if the exception + * message contains a line that starts with: + * "   at".

* * @param t is any throwable * @return List of stack frames @@ -585,7 +594,7 @@ public class ExceptionUtils { } /** - * Checks if the Throwable class has a getCause method. + *

Checks if the Throwable class has a getCause method.

*/ public static boolean isThrowableNested() { return (getCauseMethod != null);