public class ApacheCommonsExceptionUtil extends Object
Provides utilities for manipulating and examining
Throwable objects.
| Modifier and Type | Class and Description |
|---|---|
static interface |
ApacheCommonsExceptionUtil.Nestable
An interface to be implemented by
Throwable
extensions which would like to be able to nest root exceptions
inside themselves. |
| Constructor and Description |
|---|
ApacheCommonsExceptionUtil()
Public constructor allows an instance of
ExceptionUtils to be created, although that is not
normally necessary. |
| Modifier and Type | Method and Description |
|---|---|
static void |
addCauseMethodName(String methodName)
Adds to the list of method names used in the search for
Throwable
objects. |
static Throwable |
getCause(Throwable throwable)
Introspects the
Throwable to obtain the cause. |
static Throwable |
getCause(Throwable throwable,
String[] methodNames)
Introspects the
Throwable to obtain the cause. |
static String |
getFullStackTrace(Throwable throwable)
A way to get the entire nested stack-trace of an throwable.
|
static Throwable |
getRootCause(Throwable throwable)
Introspects the
Throwable to obtain the root cause. |
static String |
getStackTrace(Throwable throwable)
Gets the stack trace from a Throwable as a String.
|
static int |
getThrowableCount(Throwable throwable)
Counts the number of
Throwable objects in the
exception chain. |
static List |
getThrowableList(Throwable throwable)
Returns the list of
Throwable objects in the
exception chain. |
static Throwable[] |
getThrowables(Throwable throwable)
Returns the list of
Throwable objects in the
exception chain. |
static int |
indexOfThrowable(Throwable throwable,
Class clazz)
Returns the (zero based) index of the first
Throwable
that matches the specified class (exactly) in the exception chain. |
static int |
indexOfThrowable(Throwable throwable,
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(Throwable throwable,
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(Throwable throwable,
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 boolean |
isCauseMethodName(String methodName)
Tests if the list of method names used in the search for
Throwable
objects include the given name. |
static boolean |
isNestedThrowable(Throwable throwable)
Checks whether this
Throwable class can store a cause. |
static boolean |
isThrowableNested()
Checks if the Throwable class has a
getCause method. |
static void |
removeCauseMethodName(String methodName)
Removes from the list of method names used in the search for
Throwable
objects. |
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
Throwable using introspection, allowing
source code compatibility between pre-1.4 and post-1.4 Java releases. |
public ApacheCommonsExceptionUtil()
Public constructor allows an instance of ExceptionUtils to be created, although that is not
normally necessary.
public static void addCauseMethodName(String methodName)
Adds to the list of method names used in the search for Throwable
objects.
methodName - the methodName to add to the list, null
and empty strings are ignoredpublic static void removeCauseMethodName(String methodName)
Removes from the list of method names used in the search for Throwable
objects.
methodName - the methodName to remove from the list, null
and empty strings are ignoredpublic static boolean setCause(Throwable target, Throwable cause)
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);
}
}
target - the target Throwablecause - the Throwable to set in the targettrue if the target has been modifiedpublic static boolean isCauseMethodName(String methodName)
Tests if the list of method names used in the search for Throwable
objects include the given name.
methodName - the methodName to search in the list.Throwable
objects include the given name.public static Throwable getCause(Throwable throwable)
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
The method names can be added to using addCauseMethodName(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 a Throwable.
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 inputpublic static Throwable getCause(Throwable throwable, String[] methodNames)
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.
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 Throwable getRootCause(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 inputpublic static boolean isThrowableNested()
Checks if the Throwable class has a getCause method.
This is true for JDK 1.4 and above.
public static boolean isNestedThrowable(Throwable throwable)
Checks whether this Throwable class can store a cause.
This method does not check whether it actually does store a cause.
throwable - the Throwable to examine, may be nulltrue if nested otherwise falsepublic static int getThrowableCount(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 Throwable[] getThrowables(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 List getThrowableList(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(Throwable throwable, 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(Throwable throwable, 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(Throwable throwable, 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(Throwable throwable, 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 -1public static void removeCommonFrames(List causeFrames, List 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 throwableIllegalArgumentException - if either argument is nullpublic 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.
throwable - the Throwable to be examinedpublic 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).
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) methodCopyright © 2017. All rights reserved.