org.apache.commons.lang.exception
Class ExceptionUtils

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

public class ExceptionUtils

extends java.lang.Object

Utility routines for manipulating Throwable objects.

Since:

1.0

Author:

Daniel Rall

Field Summary

protected static java.lang.String[]	CAUSE_METHOD_NAMES The names of methods commonly used to access a wrapped exception.
protected static java.lang.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 java.lang.Throwable	getCause(java.lang.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 java.lang.Throwable	getCause(java.lang.Throwable t, java.lang.String[] methodNames) Extends the API of getCause(Throwable) by introspecting for only user-specified method names.
private static java.lang.Throwable	getCauseUsingFieldName(java.lang.Throwable t, java.lang.String fieldName)
private static java.lang.Throwable	getCauseUsingMethodName(java.lang.Throwable t, java.lang.String methodName)
private static java.lang.Throwable	getCauseUsingWellKnownTypes(java.lang.Throwable t) Uses instanceof checks to examine the exception, looking for well known types which could contain chained or wrapped exceptions.
static java.lang.Throwable	getRootCause(java.lang.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 java.lang.String[]	getStackFrames(java.lang.String stackTrace) Functionality shared between the getStackFrames(Throwable) methods of this and the NestableDelegate classes.
static java.lang.String[]	getStackFrames(java.lang.Throwable t) 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 t) A convenient way of extracting the stack trace from an exception.
static int	getThrowableCount(java.lang.Throwable t) Returns the number of Throwable objects in the exception chain.
static java.lang.Throwable[]	getThrowables(java.lang.Throwable t) Returns the list of Throwable objects in the exception chain.
static int	indexOfThrowable(java.lang.Throwable t, java.lang.Class type) Delegates to indexOfThrowable(Throwable, Class, int), starting the search at the beginning of the exception chain.
static int	indexOfThrowable(java.lang.Throwable t, java.lang.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, registerNatives, toString, wait, wait, wait

Field Detail

CAUSE_METHOD_NAMES

protected static final java.lang.String[] CAUSE_METHOD_NAMES

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

CAUSE_METHOD_PARAMS

protected static final java.lang.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 java.lang.Throwable getCause(java.lang.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 java.lang.Throwable getCause(java.lang.Throwable t,
                                           java.lang.String[] methodNames)

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

See Also:

getCause(Throwable)

getRootCause

public static java.lang.Throwable getRootCause(java.lang.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 java.lang.Throwable getCauseUsingWellKnownTypes(java.lang.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 java.lang.Throwable getCauseUsingMethodName(java.lang.Throwable t,
                                                           java.lang.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 java.lang.Throwable getCauseUsingFieldName(java.lang.Throwable t,
                                                          java.lang.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(java.lang.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 java.lang.Throwable[] getThrowables(java.lang.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(java.lang.Throwable t,
                                   java.lang.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(java.lang.Throwable t,
                                   java.lang.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 java.lang.String getStackTrace(java.lang.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 java.lang.String[] getStackFrames(java.lang.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 java.lang.String[] getStackFrames(java.lang.String stackTrace)

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