org.apache.commons.lang.exception
public class ExceptionUtils extends Object
Provides utilities for manipulating and examining
Throwable
objects.
Since: 1.0
Version: $Id: ExceptionUtils.java 437554 2006-08-28 06:21:41Z bayard $
Constructor Summary | |
---|---|
ExceptionUtils()
Public constructor allows an instance of |
Method Summary | |
---|---|
static void | addCauseMethodName(String methodName) Adds to the list of method names used in the search for |
static Throwable | getCause(Throwable throwable) Introspects the The method searches for methods with specific names that return a
|
static Throwable | getCause(Throwable throwable, String[] methodNames) Introspects the
A |
static String | getFullStackTrace(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. |
static String | getMessage(Throwable th)
Gets a short message summarising the exception.
|
static Throwable | getRootCause(Throwable throwable) Introspects the This method walks through the exception chain to the last element, "root" of the tree, using getCause, and returns that exception. From version 2.2, this method handles recursive cause structures that might otherwise cause infinite loops. |
static String | getRootCauseMessage(Throwable th)
Gets a short message summarising the root cause exception.
|
static String[] | getRootCauseStackTrace(Throwable throwable) Creates a compact stack trace for the root cause of the supplied
The output of this method is consistent across JDK versions. |
static String[] | getStackFrames(Throwable throwable) Captures the stack trace associated with the specified
The result of this method vary by JDK version as this method uses Throwable#printStackTrace(java.io.PrintWriter). |
static String | getStackTrace(Throwable throwable) Gets the stack trace from a Throwable as a String. The result of this method vary by JDK version as this method uses Throwable#printStackTrace(java.io.PrintWriter). |
static int | getThrowableCount(Throwable throwable) Counts the number of A throwable without cause will return |
static List | getThrowableList(Throwable throwable) Returns the list of A throwable without cause will return a list containing one element - the input throwable. |
static Throwable[] | getThrowables(Throwable throwable) Returns the list of A throwable without cause will return an array containing one element - the input throwable. |
static int | indexOfThrowable(Throwable throwable, Class clazz) Returns the (zero based) index of the first |
static int | indexOfThrowable(Throwable throwable, Class clazz, int fromIndex) Returns the (zero based) index of the first |
static int | indexOfType(Throwable throwable, Class type) Returns the (zero based) index of the first |
static int | indexOfType(Throwable throwable, Class type, int fromIndex) Returns the (zero based) index of the first |
static boolean | isCauseMethodName(String methodName) Tests if the list of method names used in the search for |
static boolean | isNestedThrowable(Throwable throwable) Checks whether this This method does not check whether it actually does store a cause.
|
static boolean | isThrowableNested() Checks if the Throwable class has a This is true for JDK 1.4 and above. |
static void | printRootCauseStackTrace(Throwable throwable) Prints a compact stack trace for the root cause of a throwable
to The compact stack trace starts with the root cause and prints stack frames up to the place where it was caught and wrapped. |
static void | printRootCauseStackTrace(Throwable throwable, PrintStream stream) 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. |
static void | printRootCauseStackTrace(Throwable throwable, PrintWriter writer) 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. |
static void | removeCauseMethodName(String methodName) Removes from the list of method names used in the search for |
static void | removeCommonFrames(List causeFrames, List wrapperFrames) Removes common frames from the cause trace given the two stack traces. |
static boolean | setCause(Throwable target, Throwable cause) Sets the cause of a The typical use of this method is inside a constructor as in the following example: import org.apache.commons.lang.exception.ExceptionUtils; public class MyException extends Exception { public MyException(String msg) { super(msg); } public MyException(String msg, Throwable cause) { super(msg); ExceptionUtils.setCause(this, cause); } } |
Public constructor allows an instance of ExceptionUtils
to be created, although that is not
normally necessary.
Adds to the list of method names used in the search for Throwable
objects.
Parameters: methodName the methodName to add to the list, null
and empty strings are ignored
Since: 2.0
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
NestableException
.
The method names can be added to using addCauseMethodName.
The default list searched for are:
getCause()
getNextException()
getTargetException()
getException()
getSourceException()
getRootCause()
getCausedByException()
getNested()
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
.
Parameters: throwable the throwable to introspect for a cause, may be null
Returns: the cause of the Throwable
,
null
if none found or null throwable input
Since: 1.0
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.
Parameters: throwable the throwable to introspect for a cause, may be null methodNames the method names, null treated as default set
Returns: the cause of the Throwable
,
null
if none found or null throwable input
Since: 1.0
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.
Parameters: throwable the Throwable
to be examined
Returns: the nested stack trace, with the root cause first
Since: 2.0
The message returned is of the form {ClassNameWithoutPackage}: {ThrowableMessage}
Parameters: th the throwable to get a message for, null returns empty string
Returns: the message, non-null
Since: Commons Lang 2.2
Introspects the Throwable
to obtain the root cause.
This method walks through the exception chain to the last element, "root" of the tree, using getCause, and returns that exception.
From version 2.2, this method handles recursive cause structures that might otherwise cause infinite loops. If the throwable parameter has a cause of itself, then null will be returned. If the throwable parameter cause chain loops, the last element in the chain before the loop is returned.
Parameters: throwable the throwable to get the root cause for, may be null
Returns: the root cause of the Throwable
,
null
if none found or null throwable input
The message returned is of the form {ClassNameWithoutPackage}: {ThrowableMessage}
Parameters: th the throwable to get a message for, null returns empty string
Returns: the message, non-null
Since: Commons Lang 2.2
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.
Parameters: throwable the throwable to examine, may be null
Returns: an array of stack trace frames, never null
Since: 2.0
Captures the stack trace associated with the specified
Throwable
object, decomposing it into a list of
stack frames.
The result of this method vary by JDK version as this method uses Throwable#printStackTrace(java.io.PrintWriter). On JDK1.3 and earlier, the cause exception will not be shown unless the specified throwable alters printStackTrace.
Parameters: throwable the Throwable
to examine, may be null
Returns: an array of strings describing each stack frame, never null
Gets the stack trace from a Throwable as a String.
The result of this method vary by JDK version as this method uses Throwable#printStackTrace(java.io.PrintWriter). On JDK1.3 and earlier, the cause exception will not be shown unless the specified throwable alters printStackTrace.
Parameters: throwable the Throwable
to be examined
Returns: the stack trace as generated by the exception's
printStackTrace(PrintWriter)
method
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
.
From version 2.2, this method handles recursive cause structures that might otherwise cause infinite loops. The cause chain is processed until the end is reached, or until the next item in the chain is already in the result set.
Parameters: throwable the throwable to inspect, may be null
Returns: the count of throwables, zero if null input
Returns the list of Throwable
objects in the
exception chain.
A throwable without cause will return a list containing
one element - the input throwable.
A throwable with one cause will return a list containing
two elements. - the input throwable and the cause throwable.
A null
throwable will return a list of size zero.
This method handles recursive cause structures that might otherwise cause infinite loops. The cause chain is processed until the end is reached, or until the next item in the chain is already in the result set.
Parameters: throwable the throwable to inspect, may be null
Returns: the list of throwables, never null
Since: Commons Lang 2.2
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
two elements. - the input throwable and the cause throwable.
A null
throwable will return an array of size zero.
From version 2.2, this method handles recursive cause structures that might otherwise cause infinite loops. The cause chain is processed until the end is reached, or until the next item in the chain is already in the result set.
Parameters: throwable the throwable to inspect, may be null
Returns: the array of throwables, never null
See Also: getThrowableList
Returns the (zero based) index of the first Throwable
that matches the specified class (exactly) in the exception chain.
Subclasses of the specified class do not match - see
ExceptionUtils for the opposite.
A null
throwable returns -1
.
A null
type returns -1
.
No match in the chain returns -1
.
Parameters: throwable the throwable to inspect, may be null clazz the class to search for, subclasses do not match, null returns -1
Returns: the index into the throwable chain, -1 if no match or null input
Returns the (zero based) index of the first Throwable
that matches the specified type in the exception chain from
a specified index.
Subclasses of the specified class do not match - see
ExceptionUtils for the opposite.
A null
throwable returns -1
.
A null
type returns -1
.
No match in the chain returns -1
.
A negative start index is treated as zero.
A start index greater than the number of throwables returns -1
.
Parameters: throwable the throwable to inspect, may be null clazz the class to search for, subclasses do not match, null returns -1 fromIndex the (zero based) index of the starting position, negative treated as zero, larger than chain size returns -1
Returns: the index into the throwable chain, -1 if no match or null input
Returns the (zero based) index of the first Throwable
that matches the specified class or subclass in the exception chain.
Subclasses of the specified class do match - see
ExceptionUtils for the opposite.
A null
throwable returns -1
.
A null
type returns -1
.
No match in the chain returns -1
.
Parameters: throwable the throwable to inspect, may be null type the type to search for, subclasses match, null returns -1
Returns: the index into the throwable chain, -1 if no match or null input
Since: 2.1
Returns the (zero based) index of the first Throwable
that matches the specified type in the exception chain from
a specified index.
Subclasses of the specified class do match - see
ExceptionUtils for the opposite.
A null
throwable returns -1
.
A null
type returns -1
.
No match in the chain returns -1
.
A negative start index is treated as zero.
A start index greater than the number of throwables returns -1
.
Parameters: throwable the throwable to inspect, may be null type the type to search for, subclasses match, null returns -1 fromIndex the (zero based) index of the starting position, negative treated as zero, larger than chain size returns -1
Returns: the index into the throwable chain, -1 if no match or null input
Since: 2.1
Tests if the list of method names used in the search for Throwable
objects include the given name.
Parameters: methodName the methodName to search in the list.
Returns: if the list of method names used in the search for Throwable
objects include the given name.
Since: 2.1
Checks whether this Throwable
class can store a cause.
This method does not check whether it actually does store a cause.
Parameters: throwable the Throwable
to examine, may be null
Returns: boolean true
if nested otherwise false
Since: 2.0
Checks if the Throwable class has a getCause
method.
This is true for JDK 1.4 and above.
Returns: true if Throwable is nestable
Since: 2.0
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.
Parameters: throwable the throwable to output
Since: 2.0
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 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.
Parameters: throwable the throwable to output, may be null stream the stream to output to, may not be null
Throws: IllegalArgumentException if the stream is null
Since: 2.0
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 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.
Parameters: throwable the throwable to output, may be null writer the writer to output to, may not be null
Throws: IllegalArgumentException if the writer is null
Since: 2.0
Removes from the list of method names used in the search for Throwable
objects.
Parameters: methodName the methodName to remove from the list, null
and empty strings are ignored
Since: 2.1
Removes common frames from the cause trace given the two stack traces.
Parameters: causeFrames stack trace of a cause throwable wrapperFrames stack trace of a wrapper throwable
Throws: IllegalArgumentException if either argument is null
Since: 2.0
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; public class MyException extends Exception { public MyException(String msg) { super(msg); } public MyException(String msg, Throwable cause) { super(msg); ExceptionUtils.setCause(this, cause); } }
Parameters: target the target Throwable
cause the Throwable
to set in the target
Returns: a true
if the target has been modified
Since: 2.2