Class ExceptionUtils
- java.lang.Object
-
- org.apache.commons.lang.exception.ExceptionUtils
-
@Deprecated(since="2021-04-30") public class ExceptionUtils extends java.lang.Object
Deprecated.Commons Lang 2 is in maintenance mode. Commons Lang 3 should be used instead.Provides utilities for manipulating and examining
Throwable
objects.- Since:
- 1.0
-
-
Constructor Summary
Constructors Constructor Description ExceptionUtils()
Deprecated.Public constructor allows an instance ofExceptionUtils
to be created, although that is not normally necessary.
-
Method Summary
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static void
addCauseMethodName(java.lang.String methodName)
Deprecated.Adds to the list of method names used in the search forThrowable
objects.static java.lang.Throwable
getCause(java.lang.Throwable throwable)
Deprecated.Introspects theThrowable
to obtain the cause.static java.lang.Throwable
getCause(java.lang.Throwable throwable, java.lang.String[] methodNames)
Deprecated.Introspects theThrowable
to obtain the cause.static java.lang.String
getFullStackTrace(java.lang.Throwable throwable)
Deprecated.A way to get the entire nested stack-trace of an throwable.static java.lang.String
getMessage(java.lang.Throwable th)
Deprecated.Gets a short message summarising the exception.static java.lang.Throwable
getRootCause(java.lang.Throwable throwable)
Deprecated.Introspects theThrowable
to obtain the root cause.static java.lang.String
getRootCauseMessage(java.lang.Throwable th)
Deprecated.Gets a short message summarising the root cause exception.static java.lang.String[]
getRootCauseStackTrace(java.lang.Throwable throwable)
Deprecated.Creates a compact stack trace for the root cause of the suppliedThrowable
.static java.lang.String[]
getStackFrames(java.lang.Throwable throwable)
Deprecated.Captures the stack trace associated with the specifiedThrowable
object, decomposing it into a list of stack frames.static java.lang.String
getStackTrace(java.lang.Throwable throwable)
Deprecated.Gets the stack trace from a Throwable as a String.static int
getThrowableCount(java.lang.Throwable throwable)
Deprecated.Counts the number ofThrowable
objects in the exception chain.static java.util.List
getThrowableList(java.lang.Throwable throwable)
Deprecated.Returns the list ofThrowable
objects in the exception chain.static java.lang.Throwable[]
getThrowables(java.lang.Throwable throwable)
Deprecated.Returns the list ofThrowable
objects in the exception chain.static int
indexOfThrowable(java.lang.Throwable throwable, java.lang.Class clazz)
Deprecated.Returns the (zero based) index of the firstThrowable
that matches the specified class (exactly) in the exception chain.static int
indexOfThrowable(java.lang.Throwable throwable, java.lang.Class clazz, int fromIndex)
Deprecated.Returns the (zero based) index of the firstThrowable
that matches the specified type in the exception chain from a specified index.static int
indexOfType(java.lang.Throwable throwable, java.lang.Class type)
Deprecated.Returns the (zero based) index of the firstThrowable
that matches the specified class or subclass in the exception chain.static int
indexOfType(java.lang.Throwable throwable, java.lang.Class type, int fromIndex)
Deprecated.Returns the (zero based) index of the firstThrowable
that matches the specified type in the exception chain from a specified index.static boolean
isCauseMethodName(java.lang.String methodName)
Deprecated.Tests if the list of method names used in the search forThrowable
objects include the given name.static boolean
isNestedThrowable(java.lang.Throwable throwable)
Deprecated.Checks whether thisThrowable
class can store a cause.static boolean
isThrowableNested()
Deprecated.Checks if the Throwable class has agetCause
method.static void
printRootCauseStackTrace(java.lang.Throwable throwable)
Deprecated.Prints a compact stack trace for the root cause of a throwable toSystem.err
.static void
printRootCauseStackTrace(java.lang.Throwable throwable, java.io.PrintStream stream)
Deprecated.Prints a compact stack trace for the root cause of a throwable.static void
printRootCauseStackTrace(java.lang.Throwable throwable, java.io.PrintWriter writer)
Deprecated.Prints a compact stack trace for the root cause of a throwable.static void
removeCauseMethodName(java.lang.String methodName)
Deprecated.Removes from the list of method names used in the search forThrowable
objects.static void
removeCommonFrames(java.util.List causeFrames, java.util.List wrapperFrames)
Deprecated.Removes common frames from the cause trace given the two stack traces.static boolean
setCause(java.lang.Throwable target, java.lang.Throwable cause)
Deprecated.Sets the cause of aThrowable
using introspection, allowing source code compatibility between pre-1.4 and post-1.4 Java releases.
-
-
-
Method Detail
-
addCauseMethodName
public static void addCauseMethodName(java.lang.String methodName)
Deprecated.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
-
removeCauseMethodName
public static void removeCauseMethodName(java.lang.String methodName)
Deprecated.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
-
setCause
public static boolean setCause(java.lang.Throwable target, java.lang.Throwable cause)
Deprecated.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 targetThrowable
cause
- theThrowable
to set in the target- Returns:
- a
true
if the target has been modified - Since:
- 2.2
-
isCauseMethodName
public static boolean isCauseMethodName(java.lang.String methodName)
Deprecated.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
-
getCause
public static java.lang.Throwable getCause(java.lang.Throwable throwable)
Deprecated.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, andNestableException
. 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 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
-
getCause
public static java.lang.Throwable getCause(java.lang.Throwable throwable, java.lang.String[] methodNames)
Deprecated.Introspects the
Throwable
to obtain the cause.- Try known exception types.
- Try the supplied array of method names.
- Try the field 'detail'.
A
null
set of method names means use the default set. Anull
in the set of method names will be ignored.- Parameters:
throwable
- the throwable to introspect for a cause, may be nullmethodNames
- 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
-
getRootCause
public static java.lang.Throwable getRootCause(java.lang.Throwable throwable)
Deprecated.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.
- 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
-
isThrowableNested
public static boolean isThrowableNested()
Deprecated.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
-
isNestedThrowable
public static boolean isNestedThrowable(java.lang.Throwable throwable)
Deprecated.Checks whether this
Throwable
class can store a cause.This method does not check whether it actually does store a cause.
- Parameters:
throwable
- theThrowable
to examine, may be null- Returns:
- boolean
true
if nested otherwisefalse
- Since:
- 2.0
-
getThrowableCount
public static int getThrowableCount(java.lang.Throwable throwable)
Deprecated.Counts the number of
Throwable
objects in the exception chain.A throwable without cause will return
1
. A throwable with one cause will return2
and so on. Anull
throwable will return0
.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
-
getThrowables
public static java.lang.Throwable[] getThrowables(java.lang.Throwable throwable)
Deprecated.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(Throwable)
-
getThrowableList
public static java.util.List getThrowableList(java.lang.Throwable throwable)
Deprecated.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
-
indexOfThrowable
public static int indexOfThrowable(java.lang.Throwable throwable, java.lang.Class clazz)
Deprecated.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 - seeindexOfType(Throwable, Class)
for the opposite.A
null
throwable returns-1
. Anull
type returns-1
. No match in the chain returns-1
.- Parameters:
throwable
- the throwable to inspect, may be nullclazz
- 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
-
indexOfThrowable
public static int indexOfThrowable(java.lang.Throwable throwable, java.lang.Class clazz, int fromIndex)
Deprecated.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 - seeindexOfType(Throwable, Class, int)
for the opposite.A
null
throwable returns-1
. Anull
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 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 -1- Returns:
- the index into the throwable chain, -1 if no match or null input
-
indexOfType
public static int indexOfType(java.lang.Throwable throwable, java.lang.Class type)
Deprecated.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 - seeindexOfThrowable(Throwable, Class)
for the opposite.A
null
throwable returns-1
. Anull
type returns-1
. No match in the chain returns-1
.- Parameters:
throwable
- the throwable to inspect, may be nulltype
- 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
-
indexOfType
public static int indexOfType(java.lang.Throwable throwable, java.lang.Class type, int fromIndex)
Deprecated.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 - seeindexOfThrowable(Throwable, Class)
for the opposite.A
null
throwable returns-1
. Anull
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 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 -1- Returns:
- the index into the throwable chain, -1 if no match or null input
- Since:
- 2.1
-
printRootCauseStackTrace
public static void printRootCauseStackTrace(java.lang.Throwable throwable)
Deprecated.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
-
printRootCauseStackTrace
public static void printRootCauseStackTrace(java.lang.Throwable throwable, java.io.PrintStream stream)
Deprecated.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 nullstream
- the stream to output to, may not be null- Throws:
java.lang.IllegalArgumentException
- if the stream isnull
- Since:
- 2.0
-
printRootCauseStackTrace
public static void printRootCauseStackTrace(java.lang.Throwable throwable, java.io.PrintWriter writer)
Deprecated.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 nullwriter
- the writer to output to, may not be null- Throws:
java.lang.IllegalArgumentException
- if the writer isnull
- Since:
- 2.0
-
getRootCauseStackTrace
public static java.lang.String[] getRootCauseStackTrace(java.lang.Throwable throwable)
Deprecated.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
-
removeCommonFrames
public static void removeCommonFrames(java.util.List causeFrames, java.util.List wrapperFrames)
Deprecated.Removes common frames from the cause trace given the two stack traces.
- Parameters:
causeFrames
- stack trace of a cause throwablewrapperFrames
- stack trace of a wrapper throwable- Throws:
java.lang.IllegalArgumentException
- if either argument is null- Since:
- 2.0
-
getFullStackTrace
public static java.lang.String getFullStackTrace(java.lang.Throwable throwable)
Deprecated.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
- theThrowable
to be examined- Returns:
- the nested stack trace, with the root cause first
- Since:
- 2.0
-
getStackTrace
public static java.lang.String getStackTrace(java.lang.Throwable throwable)
Deprecated.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
- theThrowable
to be examined- Returns:
- the stack trace as generated by the exception's
printStackTrace(PrintWriter)
method
-
getStackFrames
public static java.lang.String[] getStackFrames(java.lang.Throwable throwable)
Deprecated.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
- theThrowable
to examine, may be null- Returns:
- an array of strings describing each stack frame, never null
-
getMessage
public static java.lang.String getMessage(java.lang.Throwable th)
Deprecated.Gets a short message summarising the exception.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
-
getRootCauseMessage
public static java.lang.String getRootCauseMessage(java.lang.Throwable th)
Deprecated.Gets a short message summarising the root cause exception.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
-
-