Apache
/
commons-lang
mirror of https://github.com/apache/commons-lang.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
This commit is contained in:
Henri Yandell 2003-07-14 22:22:46 +00:00
parent 1dc0785f8e
commit 99a9ac4d5e
2 changed files with 167 additions and 125 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

175
src/java/org/apache/commons/lang/enum/Enum.java
View File

@ -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.
* <p>
* One feature of the C programming language lacking in Java is enumerations. The
* <p>Abstract superclass for type-safe enums.</p>
*
* <p>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.
* <p>
* <em>NOTE:</em>Due to the way in which Java ClassLoaders work, comparing Enum objects
* class follows the basic Java type-safe enumeration pattern.</p>
*
* <p><em>NOTE:</em>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.</p>
*
* <h4>Simple Enums</h4>
* To use this class, it must be subclassed. For example:
*
* <p>To use this class, it must be subclassed. For example:</p>
*
* <pre>
* public final class ColorEnum extends Enum {
@ -105,19 +107,19 @@ import java.util.Map;
* }
* }
* </pre>
* <p>
* As shown, each enum has a name. This can be accessed using <code>getName</code>.
* <p>
* The <code>getEnum</code> and <code>iterator</code> methods are recommended.
*
* <p>As shown, each enum has a name. This can be accessed using <code>getName</code>.</p>
*
* <p>The <code>getEnum</code> and <code>iterator</code> 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.</p>
*
* <h4>Subclassed Enums</h4>
* A hierarchy of Enum classes can be built. In this case, the superclass is
* <p>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 <i>of the type of the superclass</i>. The
* may add additional Enum constants <em>of the type of the superclass</em>. The
* query methods on the subclass will return all of the Enum constants from the
* superclass and subclass.
* superclass and subclass.</p>
*
* <pre>
* public class ExtraColorEnum extends ColorEnum {
@ -146,15 +148,16 @@ import java.util.Map;
* }
* }
* </pre>
*
* This example will return RED, GREEN, BLUE, YELLOW from the List and iterator
*
* <p>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.</p>
*
* <h4>Functional Enums</h4>
* The enums can have functionality by using anonymous inner classes
* [Effective Java, Bloch01]:
*
* <p>The enums can have functionality by using anonymous inner classes
* [Effective Java, Bloch01]:</p>
*
* <pre>
* public abstract class OperationEnum extends Enum {
@ -192,26 +195,25 @@ import java.util.Map;
* }
* }
* </pre>
* <p>
* <em>NOTE:</em> This class originated in the Jakarta Avalon project.
* </p>
*
* <p><em>NOTE:</em> This class originated in the Jakarta Avalon project.</p>
*
* @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 <code>Map</code>, 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.
* <code>Map</code>, key of class name, value of <code>Entry</code>.
*/
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
* <p>Enable the iterator to retain the source code order.</p>
*/
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
* <p>Restrictive constructor.</p>
*/
private Entry() {
}
}
/**
* Constructor to add a new named item to the enumeration.
* <p>Constructor to add a new named item to the enumeration.</p>
*
* @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 <code>null</code>
* 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.
* <p>Handle the deserialization of the class to ensure that multiple
* copies are not wastefully created, or illegal enum types created.</p>
*
* @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.
* <p>Gets an <code>Enum</code> object by class and name.</p>
*
* @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 <code>null</code>
* @param name the name of the <code>Enum</code> to get,
* may be <code>null</code>
* @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 <code>null</code>
*/
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.
* <p>Gets the <code>Map</code> of <code>Enum</code> objects by
* name using the <code>Enum</code> class.</p>
*
* <p>If the requested class has no enum objects an empty
* <code>Map</code> is returned.</p>
*
* @param enumClass the class of the Enum to get, must not be null
* @param enumClass the class of the <code>Enum</code> to get,
* must not be <code>null</code>
* @return the enum object Map
* @throws IllegalArgumentException if the enum class is null
* @throws IllegalArgumentException if the enum class is <code>null</code>
* @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.
* <p>Gets the <code>List</code> of <code>Enum</code> objects using the
* <code>Enum</code> class.</p>
*
* <p>The list is in the order that the objects were created (source code order).
* If the requested class has no enum objects an empty <code>List</code> is
* returned.</p>
*
* @param enumClass the class of the Enum to get, must not be null
* @param enumClass the class of the <code>Enum</code> to get,
* must not be <code>null</code>
* @return the enum object Map
* @throws IllegalArgumentException if the enum class is null
* @throws IllegalArgumentException if the enum class is <code>null</code>
* @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.
* <p>Gets an <code>Iterator</code> over the <code>Enum</code> objects in
* an <code>Enum</code> class.</p>
*
* <p>The <code>Iterator</code> is in the order that the objects were
* created (source code order). If the requested class has no enum
* objects an empty <code>Iterator</code> is returned.</p>
*
* @param enumClass the class of the Enum to get, must not be null
* @param enumClass the class of the <code>Enum</code> to get,
* must not be <code>null</code>
* @return an iterator of the Enum objects
* @throws IllegalArgumentException if the enum class is null
* @throws IllegalArgumentException if the enum class is <code>null</code>
* @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.
* <p>Gets an <code>Entry</code> from the map of Enums.</p>
*
* @param enumClass the class of the Enum to get
* @param enumClass the class of the <code>Enum</code> 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.
* <p>Creates an <code>Entry</code> for storing the Enums.</p>
*
* <p>This accounts for subclassed Enums.</p>
*
* @param enumClass the class of the Enum to get
* @param enumClass the class of the <code>Enum</code> 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.
* <p>Convert a class to the actual common enum class.</p>
*
* <p>This accounts for anonymous inner classes.</p>
*
* @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.
* <p>Retrieve the name of this Enum item, set in the constructor.</p>
*
* @return the <code>String</code> 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
* <p>Tests for equality.</p>
*
* <p>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.</p>
*
* @param other the other object to compare for equality
* @return true if the Enums are equal
* @return <code>true</code> 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.
* <p>Returns a suitable hashCode for the enumeration.</p>
*
* @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.
* <p>Tests for order.</p>
*
* <p>The default ordering is alphabetic by name, but this
* can be overridden by subclasses.</p>
*
* @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, <code>0</code> of equal
* @throws ClassCastException if other is not an Enum
* @throws NullPointerException if other is null
* @throws NullPointerException if other is <code>null</code>
*/
public int compareTo(Object other) {
return iName.compareTo(((Enum) other).iName);
}
/**
* Human readable description of this Enum item. For use when debugging.
* <p>Human readable description of this Enum item.</p>
*
* <p>For use when debugging.</p>
*
* @return String in the form <code>type[name]</code>, for example:
* <code>Color[Red]</code>. Note that the package name is stripped from

117
src/java/org/apache/commons/lang/exception/ExceptionUtils.java
View File

@ -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 <a href="mailto:ggregory@seagullsw.com">Gary Gregory</a>
* @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.
* <p>Used when printing stack frames to denote the start of a
* wrapped exception.</p>
*
* <p>Package private for accessibility by test suite.</p>
*/
static final String WRAPPED_MARKER = " [wrapped] ";
/**
* The names of methods commonly used to access a wrapped
* exception.
* <p>The names of methods commonly used to access a wrapped
* exception.</p>
*/
protected static String[] CAUSE_METHOD_NAMES = {
"getCause",
@ -105,8 +106,8 @@ public class ExceptionUtils {
};
/**
* Constructs a new <code>ExceptionUtils</code>. Protected to
* discourage instantiation.
* <p>Constructs a new <code>ExceptionUtils</code>. Protected to
* discourage instantiation.</p>
*/
protected ExceptionUtils() {
}
@ -115,10 +116,11 @@ public class ExceptionUtils {
* <p>Adds to the list of method names used in the search for <code>Throwable</code>
* objects.</p>
*
* @param methodName the methodName to add to the list, null and empty strings are ignored
* @param methodName the methodName to add to the list, <code>null</code>
* 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 {
* <code>Throwable</code> 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:</p>
* The method names can be added to using {@link #addCauseMethodName(String)}.</p>
*
* <p>The default list searched for are:</p>
* <ul>
* <li><code>getCause()</code>
* <li><code>getNextException()</code>
* <li><code>getTargetException()</code>
* <li><code>getException()</code>
* <li><code>getSourceException()</code>
* <li><code>getRootCause()</code>
* <li><code>getCausedByException()</code>
* <li><code>getNested()</code>
* <li><code>getCause()</code></li>
* <li><code>getNextException()</code></li>
* <li><code>getTargetException()</code></li>
* <li><code>getException()</code></li>
* <li><code>getSourceException()</code></li>
* <li><code>getRootCause()</code></li>
* <li><code>getCausedByException()</code></li>
* <li><code>getNested()</code></li>
* </ul>
*
* <p>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 <code>Throwable</code>.
* @throws NullPointerException if the throwable is null
* @throws NullPointerException if the throwable is <code>null</code>
*/
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 <code>Throwable</code>.
* @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 <code>null</code>
* or contains <code>null</code>
* @throws NullPointerException if the throwable is <code>null</code>
*/
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 <code>null</code> 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 <code>null</code> 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
* <p>Prints a compact stack trace for the root cause of a throwable.</p>
*
* <p>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.
* <p>
* 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.</p>
*
* <p>The method is equivalent to t.printStackTrace() for throwables
* that don't have nested causes.</p>
*/
public static void printRootCauseStackTrace(Throwable t, PrintStream stream) {
String trace[] = getRootCauseStackTrace(t);
@ -372,7 +377,7 @@ public class ExceptionUtils {
}
/**
* Equivalent to <code>printRootCauseStackTrace(t, System.err);</code>
* <p>Equivalent to <code>printRootCauseStackTrace(t, System.err);</code></p>
*
* @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.
* <p>Same as {@link #printRootCauseStackTrace(Throwable,java.io.PrintStream)},
* except it takes a <code>PrintWriter</code> as an argument.</p>
*/
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
* <code>Throwable</code>.
* <p>Creates a compact stack trace for the root cause of the supplied
* <code>Throwable</code>.</p>
*/
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.
* <p>Removes common frames from the cause trace given the two stack traces.</p>
*
* @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.
* <p>A convenient way of extracting the stack trace from an
* exception.</p>
*
* @param t The <code>Throwable</code>.
* @return The stack trace as generated by the exception's
* <code>printStackTrace(PrintWriter)</code> method.
* <code>printStackTrace(PrintWriter)</code> 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.
* <p>A way to get the entire nested stack-trace of an throwable.</p>
*
* @param t The <code>Throwable</code>.
* @return The nested stack trace, with the root cause first.
@ -476,10 +481,11 @@ public class ExceptionUtils {
}
/**
* Returns whether a <code>Throwable </code> is considered nested or not.
* <p>Returns whether a <code>Throwable</code> is considered nested
* or not.</p>
*
* @param t The <code>Throwable</code>.
* @return boolean true/false
* @param throwable The <code>Throwable</code>.
* @return boolean <code>true</code> if nested otherwise <code>false</code>
*/
public static boolean isNestedThrowable(Throwable throwable) {
if(throwable == null) {
@ -519,9 +525,9 @@ public class ExceptionUtils {
}
/**
* Captures the stack trace associated with the specified
* <p>Captures the stack trace associated with the specified
* <code>Throwable</code> object, decomposing it into a list of
* stack frames.
* stack frames.</p>
*
* @param t The <code>Throwable</code>.
* @return An array of strings describing each stack frame.
@ -531,10 +537,10 @@ public class ExceptionUtils {
}
/**
* Functionality shared between the
* <p>Functionality shared between the
* <code>getStackFrames(Throwable)</code> methods of this and the
* {@link org.apache.commons.lang.exception.NestableDelegate}
* classes.
* classes.</p>
*/
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".
* <p>Produces a <code>List</code> of stack frames - the message
* is not included.</p>
*
* <p>This works in most cases - it will only fail if the exception
* message contains a line that starts with:
* <code>&quot;&nbsp;&nbsp;&nbsp;at&quot;.</code></p>
*
* @param t is any throwable
* @return List of stack frames
@ -585,7 +594,7 @@ public class ExceptionUtils {
}
/**
* Checks if the Throwable class has a <code>getCause</code> method.
* <p>Checks if the Throwable class has a <code>getCause</code> method.</p>
*/
public static boolean isThrowableNested() {
return (getCauseMethod != null);