org.apache.commons.lang.exception
Class ExceptionUtils

java.lang.Object
  |
  +--org.apache.commons.lang.exception.ExceptionUtils

public class ExceptionUtils

extends Object

Utility routines for manipulating Throwable objects.

Since:

1.0

Author:

Daniel Rall

Field Summary

protected static String[]	CAUSE_METHOD_NAMES The names of methods commonly used to access a wrapped exception.
protected static Object[]	CAUSE_METHOD_PARAMS The empty parameter list passed to methods used to access a wrapped exception.

Constructor Summary

protected

ExceptionUtils() Constructs a new ExceptionUtils.

Method Summary

static Throwable	getCause(Throwable t) Introspects the specified Throwable for a getCause(), getNextException(), getTargetException(), or getException() method which returns a Throwable object (standard as of JDK 1.4, and part of the NestableException API), extracting and returning the cause of the exception.
static Throwable	getCause(Throwable t, String[] methodNames) Extends the API of getCause(Throwable) by introspecting for only user-specified method names.
private static Throwable	getCauseUsingFieldName(Throwable t, String fieldName)
private static Throwable	getCauseUsingMethodName(Throwable t, String methodName)
private static Throwable	getCauseUsingWellKnownTypes(Throwable t) Uses instanceof checks to examine the exception, looking for well known types which could contain chained or wrapped exceptions.
static Throwable	getRootCause(Throwable t) Walks through the exception chain to the last element -- the "root" of the tree -- using getCause(Throwable), and returns that exception.
(package private) static String[]	getStackFrames(String stackTrace) Functionality shared between the getStackFrames(Throwable) methods of this and the NestableDelegate classes.
static String[]	getStackFrames(Throwable t) Captures the stack trace associated with the specified Throwable object, decomposing it into a list of stack frames.
static String	getStackTrace(Throwable t) A convenient way of extracting the stack trace from an exception.
static int	getThrowableCount(Throwable t) Returns the number of Throwable objects in the exception chain.
static Throwable[]	getThrowables(Throwable t) Returns the list of Throwable objects in the exception chain.
static int	indexOfThrowable(Throwable t, Class type) Delegates to indexOfThrowable(Throwable, Class, int), starting the search at the beginning of the exception chain.
static int	indexOfThrowable(Throwable t, Class type, int fromIndex) Returns the (zero based) index, of the first Throwable that matches the specified type in the exception chain of Throwable objects with an index greater than or equal to the specified index, or -1 if the type is not found.

Methods inherited from class java.lang.Object

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

Field Detail

CAUSE_METHOD_NAMES

protected static final String[] CAUSE_METHOD_NAMES

The names of methods commonly used to access a wrapped exception.

CAUSE_METHOD_PARAMS

protected static final Object[] CAUSE_METHOD_PARAMS

The empty parameter list passed to methods used to access a wrapped exception.

Constructor Detail

ExceptionUtils

protected ExceptionUtils()

Constructs a new ExceptionUtils. Protected to discourage instantiation.

Method Detail

getCause

public static Throwable getCause(Throwable t)

Introspects the specified Throwable for a getCause(), getNextException(), getTargetException(), or getException() method which returns a Throwable object (standard as of JDK 1.4, and part of the NestableException API), extracting and returning the cause of the exception. 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.

Parameters:

t - The exception to introspect for a cause.

Returns:

The cause of the Throwable.

getCause

public static Throwable getCause(Throwable t,
                                 String[] methodNames)

Extends the API of getCause(Throwable) by introspecting for only user-specified method names.

See Also:

getCause(Throwable)

getRootCause

public static Throwable getRootCause(Throwable t)

Walks through the exception chain to the last element -- the "root" of the tree -- using getCause(Throwable), and returns that exception.

Returns:

The root cause of the Throwable.

See Also:

getCause(Throwable)

getCauseUsingWellKnownTypes

private static Throwable getCauseUsingWellKnownTypes(Throwable t)

Uses instanceof checks to examine the exception, looking for well known types which could contain chained or wrapped exceptions.

Parameters:

t - The exception to examine.

Returns:

The wrapped exception, or null if not found.

getCauseUsingMethodName

private static Throwable getCauseUsingMethodName(Throwable t,
                                                 String methodName)

Parameters:

t - The exception to examine.

methodName - The name of the method to find and invoke.

Returns:

The wrapped exception, or null if not found.

getCauseUsingFieldName

private static Throwable getCauseUsingFieldName(Throwable t,
                                                String fieldName)

Parameters:

t - The exception to examine.

fieldName - The name of the attribute to examine.

Returns:

The wrapped exception, or null if not found.

getThrowableCount

public static int getThrowableCount(Throwable t)

Returns the number of Throwable objects in the exception chain.

Parameters:

t - The exception to inspect.

Returns:

The throwable count.

getThrowables

public static Throwable[] getThrowables(Throwable t)

Returns the list of Throwable objects in the exception chain.

Parameters:

t - The exception to inspect.

Returns:

The list of Throwable objects.

indexOfThrowable

public static int indexOfThrowable(Throwable t,
                                   Class type)

Delegates to indexOfThrowable(Throwable, Class, int), starting the search at the beginning of the exception chain.

See Also:

indexOfThrowable(Throwable, Class, int)

indexOfThrowable

public static int indexOfThrowable(Throwable t,
                                   Class type,
                                   int fromIndex)

Returns the (zero based) index, of the first Throwable that matches the specified type in the exception chain of Throwable objects with an index greater than or equal to the specified index, or -1 if the type is not found.

Parameters:

t - The exception to inspect.

type - Class to look for.

fromIndex - The (zero based) index of the starting position in the chain to be searched.

Returns:

index The first occurrence of the type in the chain, or -1 if the type is not found.

Throws:

IndexOutOfBoundsException - If the fromIndex argument is negative or not less than the count of Throwables in the chain.

getStackTrace

public static String getStackTrace(Throwable t)

A convenient way of extracting the stack trace from an exception.

Parameters:

t - The Throwable.

Returns:

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

getStackFrames

public static String[] getStackFrames(Throwable t)

Captures the stack trace associated with the specified Throwable object, decomposing it into a list of stack frames.

Parameters:

t - The Throwable.

Returns:

An array of strings describing each stack frame.

getStackFrames

static String[] getStackFrames(String stackTrace)

Functionality shared between the getStackFrames(Throwable) methods of this and the NestableDelegate classes.