Class ExceptionUtils
ExceptionUtils
provides utilities for manipulating Throwable
objects.
- Since:
- 1.0
- Author:
- Daniel Rall, Dmitri Plotnikov, Stephen Colebourne
-
Field Summary
Modifier and TypeFieldDescriptionprotected static String[]
The names of methods commonly used to access a wrapped exception. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic void
addCauseMethodName
(String methodName) Adds to the list of method names used in the search forThrowable
objects.static Throwable
Introspects the specifiedThrowable
to obtain the cause.static Throwable
Introspects the specifiedThrowable
to obtain the cause using a supplied array of method names.static String
A way to get the entire nested stack-trace of an throwable.static Throwable
getRootCause
(Throwable throwable) Walks through the exception chain to the last element -- the "root" of the tree -- usinggetCause(Throwable)
, and returns that exception.static String[]
Creates a compact stack trace for the root cause of the supplied throwable.static String[]
Captures the stack trace associated with the specifiedThrowable
object, decomposing it into a list of stack frames.static String
A convenient way of extracting the stack trace from an exception.static int
getThrowableCount
(Throwable throwable) Returns the number ofThrowable
objects in the exception chain.static Throwable[]
getThrowables
(Throwable throwable) Returns the list ofThrowable
objects in the exception chain.static int
indexOfThrowable
(Throwable throwable, Class type) Delegates toindexOfThrowable(Throwable, Class, int)
, starting the search at the beginning of the exception chain.static int
indexOfThrowable
(Throwable throwable, Class type, int fromIndex) Returns the (zero based) index, of the firstThrowable
that matches the specified type in the exception chain ofThrowable
objects with an index greater than or equal to the specified index, or-1
if the type is not found.static boolean
isNestedThrowable
(Throwable throwable) Whether an Throwable is considered nested or not.static void
Equivalent to printRootCauseStackTrace(t, System.err)static void
printRootCauseStackTrace
(Throwable t, PrintStream stream) Prints a compact stack trace for the root cause of a throwable.static void
printRootCauseStackTrace
(Throwable t, PrintWriter writer) Same as printRootCauseStackTrace(t, stream), except it takes a PrintWriter as an argument.
-
Field Details
-
CAUSE_METHOD_NAMES
The names of methods commonly used to access a wrapped exception.
-
-
Constructor Details
-
ExceptionUtils
protected ExceptionUtils()Constructs a newExceptionUtils
. Protected to discourage instantiation.
-
-
Method Details
-
addCauseMethodName
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
-
getCause
Introspects the specified
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 The method names can be added to usingaddCauseMethodName(String)
. 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 aThrowable
.If none of the above is found, returns
null
.- Parameters:
throwable
- The exception to introspect for a cause.- Returns:
- The cause of the
Throwable
. - Throws:
NullPointerException
- if the throwable is null
-
getCause
Introspects the specified
Throwable
to obtain the cause using a supplied array of method names.- Parameters:
throwable
- The exception to introspect for a cause.methodNames
- the methods names to match- Returns:
- The cause of the
Throwable
. - Throws:
NullPointerException
- if the method names array is null or contains nullNullPointerException
- if the throwable is null
-
getRootCause
Walks through the exception chain to the last element -- the "root" of the tree -- using
getCause(Throwable)
, and returns that exception.- Parameters:
throwable
- the throwable to get the root cause for- Returns:
- The root cause of the
Throwable
.
-
getThrowableCount
Returns the number of
Throwable
objects in the exception chain.- Parameters:
throwable
- the exception to inspect- Returns:
- The throwable count.
-
getThrowables
Returns the list of
Throwable
objects in the exception chain.- Parameters:
throwable
- the exception to inspect- Returns:
- The list of
Throwable
objects.
-
indexOfThrowable
Delegates to
indexOfThrowable(Throwable, Class, int)
, starting the search at the beginning of the exception chain.- Parameters:
throwable
- the exception to inspecttype
-Class
to look for- Returns:
- index of the stack matching the type
- See Also:
-
indexOfThrowable
Returns the (zero based) index, of the first
Throwable
that matches the specified type in the exception chain ofThrowable
objects with an index greater than or equal to the specified index, or-1
if the type is not found.- Parameters:
throwable
- the exception to inspecttype
-Class
to look forfromIndex
- the (zero based) index of the starting position in the chain to be searched- Returns:
- the first occurrence of the type in the chain, or
-1
if the type is not found - Throws:
IndexOutOfBoundsException
- If thefromIndex
argument is negative or not less than the count ofThrowable
s in the chain.
-
printRootCauseStackTrace
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.
- Parameters:
t
- the exceptionstream
- the stream
-
printRootCauseStackTrace
Equivalent to printRootCauseStackTrace(t, System.err)- Parameters:
t
- the exception
-
printRootCauseStackTrace
Same as printRootCauseStackTrace(t, stream), except it takes a PrintWriter as an argument.- Parameters:
t
- the causewriter
- the writer
-
getRootCauseStackTrace
Creates a compact stack trace for the root cause of the supplied throwable. SeeprintRootCauseStackTrace(Throwable t, PrintStream s)
- Parameters:
t
- the cause- Returns:
- the Stack
-
getStackTrace
A convenient way of extracting the stack trace from an exception.- Parameters:
t
- TheThrowable
.- Returns:
- The stack trace as generated by the exception's
printStackTrace(PrintWriter)
method.
-
getFullStackTrace
A way to get the entire nested stack-trace of an throwable.- Parameters:
t
- TheThrowable
.- Returns:
- The nested stack trace, with the root cause first.
-
isNestedThrowable
Whether an Throwable is considered nested or not.- Parameters:
throwable
- TheThrowable
.- Returns:
- boolean true/false
-
getStackFrames
Captures the stack trace associated with the specifiedThrowable
object, decomposing it into a list of stack frames.- Parameters:
t
- TheThrowable
.- Returns:
- An array of strings describing each stack frame.
-