Provides utilities for manipulating and examining
-Throwable objects.
Throwable objects.
*
* @author Daniel Rall
* @author Dmitri Plotnikov
@@ -74,16 +74,12 @@ public class ExceptionUtils {
};
/**
- * - * The Method object for Java 1.4 getCause. - *
+ *The Method object for Java 1.4 getCause.
*/ private static final Method THROWABLE_CAUSE_METHOD; /** - *- * The Method object for Java 1.4 initCause. - *
+ *The Method object for Java 1.4 initCause.
*/ private static final Method THROWABLE_INITCAUSE_METHOD; @@ -149,16 +145,12 @@ public static void removeCauseMethodName(String methodName) { } /** - *
- * Sets the cause of a Throwable using introspection, allowing source code compatibility between
- * pre-1.4 and post-1.4 Java releases.
- *
- * The typical use of this method is inside a constructor as in the following example: - *
- * - *+ *
Sets the cause of a Throwable using introspection, allowing
+ * source code compatibility between pre-1.4 and post-1.4 Java releases.
The typical use of this method is inside a constructor as in + * the following example:
+ * *
* import org.apache.commons.lang.exception.ExceptionUtils;
*
@@ -167,20 +159,16 @@ public static void removeCauseMethodName(String methodName) {
* public MyException(String msg) {
* super(msg);
* }
- *
+ *
* public MyException(String msg, Throwable cause) {
* super(msg);
* ExceptionUtils.setCause(this, cause);
* }
- *
- * }
+ * }
*
- *
- *
- * @param target
- * the target Throwable
- * @param cause
- * the Throwable to set in the target
+ *
+ * @param target the target Throwable
+ * @param cause the Throwable to set in the target
* @return a true if the target has been modified
* @since 2.2
*/
@@ -225,6 +213,7 @@ private static String[] toArray(List list) {
/**
* Returns {@link #CAUSE_METHOD_NAMES} as a List.
+ *
* @return {@link #CAUSE_METHOD_NAMES} as a List.
*/
private static ArrayList getCauseMethodNameList() {
@@ -246,7 +235,7 @@ public static boolean isCauseMethodName(String methodName) {
/**
* Introspects the Throwable to obtain the cause.
The method searches for methods with specific names that return a
* Throwable object. This will pick up most wrapping exceptions,
* including those from JDK 1.4, and
@@ -267,7 +256,7 @@ public static boolean isCauseMethodName(String methodName) {
*
*
In the absence of any such method, the object is inspected for a
* detail field assignable to a Throwable.
If none of the above is found, returns null.
Introspects the Throwable to obtain the cause.
A null set of method names means use the default set.
* A null in the set of method names will be ignored.
Introspects the Throwable to obtain the root cause.
This method walks through the exception chain to the last element, * "root" of the tree, using {@link #getCause(Throwable)}, and * returns that exception.
@@ -369,7 +358,7 @@ private static Throwable getCauseUsingWellKnownTypes(Throwable throwable) { /** *Finds a Throwable by method name.
null if not found
@@ -400,7 +389,7 @@ private static Throwable getCauseUsingMethodName(Throwable throwable, String met
/**
* Finds a Throwable by field name.
null if not found
@@ -430,9 +419,9 @@ private static Throwable getCauseUsingFieldName(Throwable throwable, String fiel
//-----------------------------------------------------------------------
/**
* Checks if the Throwable class has a getCause method.
This is true for JDK 1.4 and above.
- * + * * @return true if Throwable is nestable * @since 2.0 */ @@ -442,7 +431,7 @@ public static boolean isThrowableNested() { /** *Checks whether this Throwable class can store a cause.
This method does not check whether it actually does store a cause.
*
* @param throwable the Throwable to examine, may be null
@@ -496,11 +485,11 @@ public static boolean isNestedThrowable(Throwable throwable) {
/**
*
Counts the number of Throwable objects in the
* exception chain.
A throwable without cause will return 1.
* A throwable with one cause will return 2 and so on.
* A null throwable will return 0.
Returns the list of Throwable objects in the
* exception chain.
A throwable without cause will return an array containing * one element - the input throwable. * A throwable with one cause will return an array containing @@ -541,7 +530,7 @@ public static Throwable[] getThrowables(Throwable throwable) { * that matches the specified class (exactly) in the exception chain. * Subclasses of the specified class do not match - see * {@link #indexOfType(Throwable, Class)} for the opposite.
- * + * *A null throwable returns -1.
* A null type returns -1.
* No match in the chain returns -1.
A null throwable returns -1.
* A null type returns -1.
* No match in the chain returns -1.
@@ -583,7 +572,7 @@ public static int indexOfThrowable(Throwable throwable, Class clazz, int fromInd
* that matches the specified class or subclass in the exception chain.
* Subclasses of the specified class do match - see
* {@link #indexOfThrowable(Throwable, Class)} for the opposite.
A null throwable returns -1.
* A null type returns -1.
* No match in the chain returns -1.
A null throwable returns -1.
* A null type returns -1.
* No match in the chain returns -1.
@@ -623,7 +612,7 @@ public static int indexOfType(Throwable throwable, Class type, int fromIndex) {
/**
*
Worker method for the indexOfType methods.
Prints a compact stack trace for the root cause of a throwable
* to System.err.
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 output of this method is consistent across JDK versions. + * Note that this is the opposite order to the JDK1.4 display.
+ * *The method is equivalent to printStackTrace for throwables
* that don't have nested causes.
The output of this method is consistent across JDK versions. + * Note that this is the opposite order to the JDK1.4 display.
+ * *The method is equivalent to printStackTrace for throwables
* that don't have nested causes.
null
@@ -717,9 +712,12 @@ public static void printRootCauseStackTrace(Throwable throwable, PrintStream str
* Then it prints the wrapped exception and continues with stack frames
* until the wrapper exception is caught and wrapped again, etc.
*
+ * The output of this method is consistent across JDK versions. + * Note that this is the opposite order to the JDK1.4 display.
+ * *The method is equivalent to printStackTrace for throwables
* that don't have nested causes.
null
@@ -743,7 +741,12 @@ public static void printRootCauseStackTrace(Throwable throwable, PrintWriter wri
/**
* Creates a compact stack trace for the root cause of the supplied
* Throwable.
The output of this method is consistent across JDK versions. + * It consists of the root exception followed by each of its wrapping + * exceptions separated by '[wrapped]'. Note that this is the opposite + * order to the JDK1.4 display.
+ * * @param throwable the throwable to examine, may be null * @return an array of stack trace frames, never null * @since 2.0 @@ -776,7 +779,7 @@ public static String[] getRootCauseStackTrace(Throwable throwable) { /** *Removes common frames from the cause trace given the two stack traces.
- * + * * @param causeFrames stack trace of a cause throwable * @param wrapperFrames stack trace of a wrapper throwable * @throws IllegalArgumentException if either argument is null @@ -805,6 +808,11 @@ public static void removeCommonFrames(List causeFrames, List wrapperFrames) { /** *Gets the stack trace from a Throwable as a String.
* + *The result of this method vary by JDK version as this method + * uses {@link Throwable#printStackTrace(java.io.PrintWriter)}. + * On JDK1.3 and earlier, the cause exception will not be shown + * unless the specified throwable alters printStackTrace.
+ * * @param throwable theThrowable to be examined
* @return the stack trace as generated by the exception's
* printStackTrace(PrintWriter) method
@@ -819,6 +827,9 @@ public static String getStackTrace(Throwable throwable) {
/**
* A way to get the entire nested stack-trace of an throwable.
* + *The result of this method is highly dependent on the JDK version + * and whether the exceptions override printStackTrace or not.
+ * * @param throwable theThrowable to be examined
* @return the nested stack trace, with the root cause first
* @since 2.0
@@ -842,6 +853,11 @@ public static String getFullStackTrace(Throwable throwable) {
* Throwable object, decomposing it into a list of
* stack frames.
*
+ * The result of this method vary by JDK version as this method + * uses {@link Throwable#printStackTrace(java.io.PrintWriter)}. + * On JDK1.3 and earlier, the cause exception will not be shown + * unless the specified throwable alters printStackTrace.
+ * * @param throwable theThrowable to examine, may be null
* @return an array of strings describing each stack frame, never null
*/
@@ -853,21 +869,16 @@ public static String[] getStackFrames(Throwable throwable) {
}
/**
- * - * Returns an array where each element is a line from the argument. - *
- *- * The end of line is determined by the value of {@link SystemUtils#LINE_SEPARATOR}. - *
- * - *
- * Functionality shared between the getStackFrames(Throwable) methods of this and the
- * {@link org.apache.commons.lang.exception.NestableDelegate} classes.
- *
Returns an array where each element is a line from the argument.
+ * + *The end of line is determined by the value of {@link SystemUtils#LINE_SEPARATOR}.
+ * + *Functionality shared between the
+ * getStackFrames(Throwable) methods of this and the
+ * {@link org.apache.commons.lang.exception.NestableDelegate} classes.
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: @@ -909,5 +921,5 @@ static List getStackFrameList(Throwable t) { } return list; } - + }