public class ExceptionUtils
extends java.lang.Object
Provides utilities for manipulating and examining
Throwable
objects.
Modifier and Type | Field and Description |
---|---|
private static java.lang.String[] |
CAUSE_METHOD_NAMES
The names of methods commonly used to access a wrapped exception.
|
(package private) static java.lang.String |
WRAPPED_MARKER
Used when printing stack frames to denote the start of a
wrapped exception.
|
Constructor and Description |
---|
ExceptionUtils()
Public constructor allows an instance of
ExceptionUtils to be created, although that is not
normally necessary. |
Modifier and Type | Method and Description |
---|---|
static java.lang.Throwable |
getCause(java.lang.Throwable throwable)
Deprecated.
This feature will be removed in Lang 4.0, use
Throwable.getCause() instead |
static java.lang.Throwable |
getCause(java.lang.Throwable throwable,
java.lang.String[] methodNames)
Deprecated.
This feature will be removed in Lang 4.0, use
Throwable.getCause() instead |
private static java.lang.Throwable |
getCauseUsingMethodName(java.lang.Throwable throwable,
java.lang.String methodName)
Finds a
Throwable by method name. |
static java.lang.String[] |
getDefaultCauseMethodNames()
Deprecated.
This feature will be removed in Lang 4.0
|
static java.lang.String |
getMessage(java.lang.Throwable th)
Gets a short message summarising the exception.
|
static java.lang.Throwable |
getRootCause(java.lang.Throwable throwable)
Introspects the
Throwable to obtain the root cause. |
static java.lang.String |
getRootCauseMessage(java.lang.Throwable th)
Gets a short message summarising the root cause exception.
|
static java.lang.String[] |
getRootCauseStackTrace(java.lang.Throwable throwable)
Creates a compact stack trace for the root cause of the supplied
Throwable . |
(package private) static java.util.List<java.lang.String> |
getStackFrameList(java.lang.Throwable t)
Produces a
List of stack frames - the message
is not included. |
(package private) static java.lang.String[] |
getStackFrames(java.lang.String stackTrace)
Returns an array where each element is a line from the argument.
|
static java.lang.String[] |
getStackFrames(java.lang.Throwable throwable)
Captures the stack trace associated with the specified
Throwable object, decomposing it into a list of
stack frames. |
static java.lang.String |
getStackTrace(java.lang.Throwable throwable)
Gets the stack trace from a Throwable as a String.
|
static int |
getThrowableCount(java.lang.Throwable throwable)
Counts the number of
Throwable objects in the
exception chain. |
static java.util.List<java.lang.Throwable> |
getThrowableList(java.lang.Throwable throwable)
Returns the list of
Throwable objects in the
exception chain. |
static java.lang.Throwable[] |
getThrowables(java.lang.Throwable throwable)
Returns the list of
Throwable objects in the
exception chain. |
static boolean |
hasCause(java.lang.Throwable chain,
java.lang.Class<? extends java.lang.Throwable> type)
Does the throwable's causal chain have an immediate or wrapped exception
of the given type?
|
private static int |
indexOf(java.lang.Throwable throwable,
java.lang.Class<?> type,
int fromIndex,
boolean subclass)
Worker method for the
indexOfType methods. |
static int |
indexOfThrowable(java.lang.Throwable throwable,
java.lang.Class<?> clazz)
Returns the (zero based) index of the first
Throwable
that matches the specified class (exactly) in the exception chain. |
static int |
indexOfThrowable(java.lang.Throwable throwable,
java.lang.Class<?> clazz,
int fromIndex)
Returns the (zero based) index of the first
Throwable
that matches the specified type in the exception chain from
a specified index. |
static int |
indexOfType(java.lang.Throwable throwable,
java.lang.Class<?> type)
Returns the (zero based) index of the first
Throwable
that matches the specified class or subclass in the exception chain. |
static int |
indexOfType(java.lang.Throwable throwable,
java.lang.Class<?> type,
int fromIndex)
Returns the (zero based) index of the first
Throwable
that matches the specified type in the exception chain from
a specified index. |
static void |
printRootCauseStackTrace(java.lang.Throwable throwable)
Prints a compact stack trace for the root cause of a throwable
to
System.err . |
static void |
printRootCauseStackTrace(java.lang.Throwable throwable,
java.io.PrintStream stream)
Prints a compact stack trace for the root cause of a throwable.
|
static void |
printRootCauseStackTrace(java.lang.Throwable throwable,
java.io.PrintWriter writer)
Prints a compact stack trace for the root cause of a throwable.
|
static void |
removeCommonFrames(java.util.List<java.lang.String> causeFrames,
java.util.List<java.lang.String> wrapperFrames)
Removes common frames from the cause trace given the two stack traces.
|
static <R> R |
rethrow(java.lang.Throwable throwable)
Throw a checked exception without adding the exception to the throws
clause of the calling method.
|
private static <R,T extends java.lang.Throwable> |
typeErasure(java.lang.Throwable throwable)
Claim a Throwable is another Exception type using type erasure.
|
static <R> R |
wrapAndThrow(java.lang.Throwable throwable)
Throw a checked exception without adding the exception to the throws
clause of the calling method.
|
static final java.lang.String WRAPPED_MARKER
Used when printing stack frames to denote the start of a wrapped exception.
Package private for accessibility by test suite.
private static final java.lang.String[] CAUSE_METHOD_NAMES
The names of methods commonly used to access a wrapped exception.
public ExceptionUtils()
Public constructor allows an instance of ExceptionUtils
to be created, although that is not
normally necessary.
@Deprecated public static java.lang.String[] getDefaultCauseMethodNames()
Returns the default names used when searching for the cause of an exception.
This may be modified and used in the overloaded getCause(Throwable, String[]) method.
@Deprecated public static java.lang.Throwable getCause(java.lang.Throwable throwable)
Throwable.getCause()
insteadIntrospects 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.
The default list searched for are:
getCause()
getNextException()
getTargetException()
getException()
getSourceException()
getRootCause()
getCausedByException()
getNested()
If none of the above is found, returns null
.
throwable
- the throwable to introspect for a cause, may be nullThrowable
,
null
if none found or null throwable input@Deprecated public static java.lang.Throwable getCause(java.lang.Throwable throwable, java.lang.String[] methodNames)
Throwable.getCause()
insteadIntrospects 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.
throwable
- the throwable to introspect for a cause, may be nullmethodNames
- the method names, null treated as default setThrowable
,
null
if none found or null throwable inputpublic static java.lang.Throwable getRootCause(java.lang.Throwable throwable)
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(Throwable)
, 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.
throwable
- the throwable to get the root cause for, may be nullThrowable
,
null
if none found or null throwable inputprivate static java.lang.Throwable getCauseUsingMethodName(java.lang.Throwable throwable, java.lang.String methodName)
Finds a Throwable
by method name.
throwable
- the exception to examinemethodName
- the name of the method to find and invokenull
if not foundpublic static int getThrowableCount(java.lang.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
.
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.
throwable
- the throwable to inspect, may be nullpublic static java.lang.Throwable[] getThrowables(java.lang.Throwable throwable)
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.
throwable
- the throwable to inspect, may be nullgetThrowableList(Throwable)
public static java.util.List<java.lang.Throwable> getThrowableList(java.lang.Throwable throwable)
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.
throwable
- the throwable to inspect, may be nullpublic static int indexOfThrowable(java.lang.Throwable throwable, java.lang.Class<?> clazz)
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
indexOfType(Throwable, Class)
for the opposite.
A null
throwable returns -1
.
A null
type returns -1
.
No match in the chain returns -1
.
throwable
- the throwable to inspect, may be nullclazz
- the class to search for, subclasses do not match, null returns -1public static int indexOfThrowable(java.lang.Throwable throwable, java.lang.Class<?> clazz, int fromIndex)
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
indexOfType(Throwable, Class, int)
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
.
throwable
- the throwable to inspect, may be nullclazz
- the class to search for, subclasses do not match, null returns -1fromIndex
- the (zero based) index of the starting position,
negative treated as zero, larger than chain size returns -1public static int indexOfType(java.lang.Throwable throwable, java.lang.Class<?> type)
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
indexOfThrowable(Throwable, Class)
for the opposite.
A null
throwable returns -1
.
A null
type returns -1
.
No match in the chain returns -1
.
throwable
- the throwable to inspect, may be nulltype
- the type to search for, subclasses match, null returns -1public static int indexOfType(java.lang.Throwable throwable, java.lang.Class<?> type, int fromIndex)
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
indexOfThrowable(Throwable, Class)
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
.
throwable
- the throwable to inspect, may be nulltype
- the type to search for, subclasses match, null returns -1fromIndex
- the (zero based) index of the starting position,
negative treated as zero, larger than chain size returns -1private static int indexOf(java.lang.Throwable throwable, java.lang.Class<?> type, int fromIndex, boolean subclass)
Worker method for the indexOfType
methods.
throwable
- the throwable to inspect, may be nulltype
- the type to search for, subclasses match, null returns -1fromIndex
- the (zero based) index of the starting position,
negative treated as zero, larger than chain size returns -1subclass
- if true
, compares with Class.isAssignableFrom(Class)
, otherwise compares
using referencestype
within throwables nested within the specified throwable
public static void printRootCauseStackTrace(java.lang.Throwable throwable)
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.
throwable
- the throwable to outputpublic static void printRootCauseStackTrace(java.lang.Throwable throwable, java.io.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. 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.
throwable
- the throwable to output, may be nullstream
- the stream to output to, may not be nulljava.lang.IllegalArgumentException
- if the stream is null
public static void printRootCauseStackTrace(java.lang.Throwable throwable, java.io.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. 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.
throwable
- the throwable to output, may be nullwriter
- the writer to output to, may not be nulljava.lang.IllegalArgumentException
- if the writer is null
public static java.lang.String[] getRootCauseStackTrace(java.lang.Throwable throwable)
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.
throwable
- the throwable to examine, may be nullpublic static void removeCommonFrames(java.util.List<java.lang.String> causeFrames, java.util.List<java.lang.String> wrapperFrames)
Removes common frames from the cause trace given the two stack traces.
causeFrames
- stack trace of a cause throwablewrapperFrames
- stack trace of a wrapper throwablejava.lang.IllegalArgumentException
- if either argument is nullpublic static java.lang.String getStackTrace(java.lang.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)
.
On JDK1.3 and earlier, the cause exception will not be shown
unless the specified throwable alters printStackTrace.
throwable
- the Throwable
to be examinedprintStackTrace(PrintWriter)
methodpublic static java.lang.String[] getStackFrames(java.lang.Throwable throwable)
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.
throwable
- the Throwable
to examine, may be nullstatic java.lang.String[] getStackFrames(java.lang.String stackTrace)
Returns an array where each element is a line from the argument.
The end of line is determined by the value of SystemUtils.LINE_SEPARATOR
.
stackTrace
- a stack trace Stringstatic java.util.List<java.lang.String> getStackFrameList(java.lang.Throwable t)
Produces a List
of stack frames - the message
is not included. Only the trace of the specified exception is
returned, any caused by trace is stripped.
This works in most cases - it will only fail if the exception
message contains a line that starts with:
" at".
t
- is any throwablepublic static java.lang.String getMessage(java.lang.Throwable th)
The message returned is of the form {ClassNameWithoutPackage}: {ThrowableMessage}
th
- the throwable to get a message for, null returns empty stringpublic static java.lang.String getRootCauseMessage(java.lang.Throwable th)
The message returned is of the form {ClassNameWithoutPackage}: {ThrowableMessage}
th
- the throwable to get a message for, null returns empty stringpublic static <R> R rethrow(java.lang.Throwable throwable)
The use of this technique may be controversial, but exceedingly useful to
library developers.
public int propagateExample { // note that there is no throws clause
try {
return invocation(); // throws IOException
} catch (Exception e) {
return ExceptionUtils.rethrow(e); // propagates a checked exception
}
}
This is an alternative to the more conservative approach of wrapping the
checked exception in a RuntimeException:
public int wrapExample { // note that there is no throws clause
try {
return invocation(); // throws IOException
} catch (Error e) {
throw e;
} catch (RuntimeException e) {
throw e; // wraps a checked exception
} catch (Exception e) {
throw new UndeclaredThrowableException(e); // wraps a checked exception
}
}
One downside to using this approach is that the java compiler will not allow invoking code to specify a checked exception in a catch clause unless there is some code path within the try block that has invoked a method declared with that checked exception. If the invoking site wishes to catch the shaded checked exception, it must either invoke the shaded code through a method re-declaring the desired checked exception, or catch Exception and use the instanceof operator. Either of these techniques are required when interacting with non-java jvm code such as Jyton, Scala, or Groovy, since these languages do not consider any exceptions as checked.
R
- The type of the returned value.throwable
- The throwable to rethrow.wrapAndThrow(Throwable)
private static <R,T extends java.lang.Throwable> R typeErasure(java.lang.Throwable throwable) throws T extends java.lang.Throwable
T extends java.lang.Throwable
public static <R> R wrapAndThrow(java.lang.Throwable throwable)
The downside to using this approach is that invoking code which needs to handle specific checked exceptions must sniff up the exception chain to determine if the caught exception was caused by the checked exception.
R
- The type of the returned value.throwable
- The throwable to rethrow.rethrow(Throwable)
,
hasCause(Throwable, Class)
public static boolean hasCause(java.lang.Throwable chain, java.lang.Class<? extends java.lang.Throwable> type)
chain
- The root of a Throwable causal chain.type
- The exception type to test.wrapAndThrow(Throwable)