org.apache.commons.lang3.exception
Class ExceptionUtils

java.lang.Object
  org.apache.commons.lang3.exception.ExceptionUtils

public class ExceptionUtils
extends Object

Provides utilities for manipulating and examining Throwable objects.

Since:

1.0

Version:

$Id: ExceptionUtils.java 1199894 2011-11-09 17:53:59Z ggregory $

Constructor Summary

ExceptionUtils()
Public constructor allows an instance of ExceptionUtils to be created, although that is not normally necessary.

Method Summary

static Throwable	getCause(Throwable throwable) Deprecated. This feature will be removed in Lang 4.0
static Throwable	getCause(Throwable throwable, String[] methodNames) Deprecated. This feature will be removed in Lang 4.0
static String[]	getDefaultCauseMethodNames() Deprecated. This feature will be removed in Lang 4.0
static String	getMessage(Throwable th) Gets a short message summarising the exception.
static Throwable	getRootCause(Throwable throwable) Introspects the Throwable to obtain the root cause.
static String	getRootCauseMessage(Throwable th) Gets a short message summarising the root cause exception.
static String[]	getRootCauseStackTrace(Throwable throwable) Creates a compact stack trace for the root cause of the supplied Throwable.
static String[]	getStackFrames(Throwable throwable) Captures the stack trace associated with the specified Throwable object, decomposing it into a list of stack frames.
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<Throwable>	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 void	printRootCauseStackTrace(Throwable throwable) Prints a compact stack trace for the root cause of a throwable to System.err.
static void	printRootCauseStackTrace(Throwable throwable, PrintStream stream) Prints a compact stack trace for the root cause of a throwable.
static void	printRootCauseStackTrace(Throwable throwable, PrintWriter writer) Prints a compact stack trace for the root cause of a throwable.
static void	removeCommonFrames(List<String> causeFrames, List<String> wrapperFrames) Removes common frames from the cause trace given the two stack traces.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ExceptionUtils

public ExceptionUtils()

Public constructor allows an instance of ExceptionUtils to be created, although that is not normally necessary.

Method Detail

getDefaultCauseMethodNames

@Deprecated
public static String[] getDefaultCauseMethodNames()

Deprecated. This feature will be removed in Lang 4.0

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.

Returns:

cloned array of the default method names

Since:

3.0

getCause

@Deprecated
public static Throwable getCause(Throwable throwable)

Deprecated. This feature will be removed in Lang 4.0

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.

The default list searched for are:

• getCause()
• getNextException()
• getTargetException()
• getException()
• getSourceException()
• getRootCause()
• getCausedByException()
• getNested()

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

@Deprecated
public static Throwable getCause(Throwable throwable,
                                            String[] methodNames)

Deprecated. This feature will be removed in Lang 4.0

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.

Parameters:

throwable - the throwable to introspect for a cause, may be null

methodNames - 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 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.

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

getThrowableCount

public 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.

Parameters:

throwable - the throwable to inspect, may be null

Returns:

the count of throwables, zero if null input

getThrowables

public 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.

Parameters:

throwable - the throwable to inspect, may be null

Returns:

the array of throwables, never null

See Also:

getThrowableList(Throwable)

getThrowableList

public static List<Throwable> 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.

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(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.

Parameters:

throwable - the throwable to inspect, may be null

clazz - 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(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.

Parameters:

throwable - the throwable to inspect, may be null

clazz - the class to search for, subclasses do not match, null returns -1

fromIndex - 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(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.

Parameters:

throwable - the throwable to inspect, may be null

type - 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(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.

Parameters:

throwable - the throwable to inspect, may be null

type - the type to search for, subclasses match, null returns -1

fromIndex - 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(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.

Parameters:

throwable - the throwable to output

Since:

2.0

printRootCauseStackTrace

public static void printRootCauseStackTrace(Throwable throwable,
                                            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.

Parameters:

throwable - the throwable to output, may be null

stream - the stream to output to, may not be null

Throws:

IllegalArgumentException - if the stream is null

Since:

2.0

printRootCauseStackTrace

public static void printRootCauseStackTrace(Throwable throwable,
                                            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.

Parameters:

throwable - the throwable to output, may be null

writer - the writer to output to, may not be null

Throws:

IllegalArgumentException - if the writer is null

Since:

2.0

getRootCauseStackTrace

public static String[] getRootCauseStackTrace(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.

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(List<String> causeFrames,
                                      List<String> wrapperFrames)

Removes common frames from the cause trace given the two stack traces.

Parameters:

causeFrames - stack trace of a cause throwable

wrapperFrames - stack trace of a wrapper throwable

Throws:

IllegalArgumentException - if either argument is null

Since:

2.0

getStackTrace

public 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.

Parameters:

throwable - the Throwable to be examined

Returns:

the stack trace as generated by the exception's printStackTrace(PrintWriter) method

getStackFrames

public static String[] getStackFrames(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.

Parameters:

throwable - the Throwable to examine, may be null

Returns:

an array of strings describing each stack frame, never null

getMessage

public static String getMessage(Throwable th)

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 String getRootCauseMessage(Throwable th)

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