Class ExceptionUtils
ExceptionUtils provides utilities for manipulating Throwable objects.
- Since:
- 1.0
- Version:
- $Id$
-
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic voidaddCauseMethodName(String methodName) Adds to the list of method names used in the search forThrowableobjects.static ThrowableIntrospects the specifiedThrowableto obtain the cause.static ThrowableIntrospects the specifiedThrowableto obtain the cause using a supplied array of method names.private static ThrowablegetCauseUsingFieldName(Throwable throwable, String fieldName) Find a throwable by field name.private static ThrowablegetCauseUsingMethodName(Throwable throwable, String methodName) Find a throwable by method name.private static ThrowablegetCauseUsingWellKnownTypes(Throwable throwable) Usesinstanceofchecks to examine the exception, looking for well known types which could contain chained or wrapped exceptions.static StringA way to get the entire nested stack-trace of an throwable.static ThrowablegetRootCause(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.Produces a List of stack frames - the message is not included.(package private) static String[]getStackFrames(String stackTrace) Functionality shared between thegetStackFrames(Throwable)methods of this and the classes.static String[]Captures the stack trace associated with the specifiedThrowableobject, decomposing it into a list of stack frames.static StringA convenient way of extracting the stack trace from an exception.static intgetThrowableCount(Throwable throwable) Returns the number ofThrowableobjects in the exception chain.static Throwable[]getThrowables(Throwable throwable) Returns the list ofThrowableobjects in the exception chain.static intindexOfThrowable(Throwable throwable, Class type) Delegates toindexOfThrowable(Throwable, Class, int), starting the search at the beginning of the exception chain.static intindexOfThrowable(Throwable throwable, Class type, int fromIndex) Returns the (zero based) index, of the firstThrowablethat matches the specified type in the exception chain ofThrowableobjects with an index greater than or equal to the specified index, or-1if the type is not found.static booleanisNestedThrowable(Throwable throwable) Whether an Throwable is considered nested or not.static voidEquivalent to printRootCauseStackTrace(t, System.err)static voidprintRootCauseStackTrace(Throwable t, PrintStream stream) Prints a compact stack trace for the root cause of a throwable.static voidprintRootCauseStackTrace(Throwable t, PrintWriter writer) Same as printRootCauseStackTrace(t, stream), except it takes a PrintWriter as an argument.private static voidremoveCommonFrames(List<String> causeFrames, List<String> wrapperFrames) Given two stack traces, removes common frames from the cause trace.
-
Field Details
-
WRAPPED_MARKER
Used when printing stack frames to denote the start of a wrapped exception. Package private for accessibility by test suite.- See Also:
-
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
Throwableobjects.- Parameters:
methodName- the methodName to add to the list, null and empty strings are ignored
-
getCause
Introspects the specified
Throwableto obtain the cause.The method searches for methods with specific names that return a
Throwableobject. 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
detailfield 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
Throwableto obtain the cause using a supplied array of method names.- Parameters:
throwable- The exception to introspect for a cause.- 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.
-
getCauseUsingWellKnownTypes
Uses
instanceofchecks to examine the exception, looking for well known types which could contain chained or wrapped exceptions.- Parameters:
throwable- the exception to examine- Returns:
- The wrapped exception, or
nullif not found.
-
getCauseUsingMethodName
Find a throwable by method name.
- Parameters:
throwable- the exception to examinemethodName- the name of the method to find and invoke- Returns:
- The wrapped exception, or
nullif not found.
-
getCauseUsingFieldName
Find a throwable by field name.
- Parameters:
throwable- the exception to examinefieldName- the name of the attribute to examine- Returns:
- The wrapped exception, or
nullif not found.
-
getThrowableCount
Returns the number of
Throwableobjects in the exception chain.- Parameters:
throwable- the exception to inspect- Returns:
- The throwable count.
-
getThrowables
Returns the list of
Throwableobjects in the exception chain.- Parameters:
throwable- the exception to inspect- Returns:
- The list of
Throwableobjects.
-
indexOfThrowable
Delegates to
indexOfThrowable(Throwable, Class, int), starting the search at the beginning of the exception chain.- See Also:
-
indexOfThrowable
Returns the (zero based) index, of the first
Throwablethat matches the specified type in the exception chain ofThrowableobjects with an index greater than or equal to the specified index, or-1if the type is not found.- Parameters:
throwable- the exception to inspecttype-Classto 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
-1if the type is not found - Throws:
IndexOutOfBoundsException- If thefromIndexargument is negative or not less than the count ofThrowables 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.
-
printRootCauseStackTrace
Equivalent to printRootCauseStackTrace(t, System.err) -
printRootCauseStackTrace
Same as printRootCauseStackTrace(t, stream), except it takes a PrintWriter as an argument. -
getRootCauseStackTrace
Creates a compact stack trace for the root cause of the supplied throwable. SeeprintRootCauseStackTrace(Throwable t, PrintStream s) -
removeCommonFrames
Given two stack traces, removes common frames from the cause trace.- Parameters:
causeFrames- stack trace of a cause throwablewrapperFrames- stack trace of a wrapper throwable
-
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 specifiedThrowableobject, decomposing it into a list of stack frames.- Parameters:
t- TheThrowable.- Returns:
- An array of strings describing each stack frame.
-
getStackFrames
Functionality shared between thegetStackFrames(Throwable)methods of this and the classes. -
getStackFrameList
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".- Parameters:
t- is any throwable- Returns:
- List of stack frames
-