org.codehaus.plexus.util

Class ExceptionUtils

public class ExceptionUtils extends Object

ExceptionUtils provides utilities for manipulating Throwable objects.

Since: 1.0

Version: $Id: ExceptionUtils.java 5958 2007-02-28 10:29:55Z olamy $

Author: Daniel Rall Dmitri Plotnikov Stephen Colebourne

Field Summary
protected static String[]CAUSE_METHOD_NAMES
The names of methods commonly used to access a wrapped exception.
Constructor Summary
protected ExceptionUtils()
Constructs a new ExceptionUtils.
Method Summary
static voidaddCauseMethodName(String methodName)

Adds to the list of method names used in the search for Throwable objects.

static ThrowablegetCause(Throwable throwable)

Introspects the specified Throwable to obtain the cause.

The method searches for methods with specific names that return a Throwable object.

static ThrowablegetCause(Throwable throwable, String[] methodNames)

Introspects the specified Throwable to obtain the cause using a supplied array of method names.

static StringgetFullStackTrace(Throwable t)
A way to get the entire nested stack-trace of an throwable.
static ThrowablegetRootCause(Throwable throwable)

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

static String[]getRootCauseStackTrace(Throwable t)
Creates a compact stack trace for the root cause of the supplied throwable.
static String[]getStackFrames(Throwable t)
Captures the stack trace associated with the specified Throwable object, decomposing it into a list of stack frames.
static StringgetStackTrace(Throwable t)
A convenient way of extracting the stack trace from an exception.
static intgetThrowableCount(Throwable throwable)

Returns the number of Throwable objects in the exception chain.

static Throwable[]getThrowables(Throwable throwable)

Returns the list of Throwable objects in the exception chain.

static intindexOfThrowable(Throwable throwable, Class type)

Delegates to ExceptionUtils, starting the search at the beginning of the exception chain.

static intindexOfThrowable(Throwable throwable, 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.

static booleanisNestedThrowable(Throwable throwable)
Whether an Throwable is considered nested or not.
static voidprintRootCauseStackTrace(Throwable t, PrintStream stream)
Prints a compact stack trace for the root cause of a throwable.
static voidprintRootCauseStackTrace(Throwable t)
Equivalent to printRootCauseStackTrace(t, System.err)
static voidprintRootCauseStackTrace(Throwable t, PrintWriter writer)
Same as printRootCauseStackTrace(t, stream), except it takes a PrintWriter as an argument.

Field Detail

CAUSE_METHOD_NAMES

protected static String[] CAUSE_METHOD_NAMES
The names of methods commonly used to access a wrapped exception.

Constructor Detail

ExceptionUtils

protected ExceptionUtils()
Constructs a new ExceptionUtils. Protected to discourage instantiation.

Method Detail

addCauseMethodName

public static void addCauseMethodName(String methodName)

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

getCause

public static Throwable getCause(Throwable throwable)

Introspects the specified 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. The default list searched for are:

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: throwable The exception to introspect for a cause.

Returns: The cause of the Throwable.

Throws: NullPointerException if the throwable is null

getCause

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

Introspects the specified Throwable to obtain the cause using a supplied array of method names.

Parameters: throwable The exception to introspect for a cause.

Returns: The cause of the Throwable.

Throws: NullPointerException if the method names array is null or contains null NullPointerException if the throwable is null

getFullStackTrace

public static String getFullStackTrace(Throwable t)
A way to get the entire nested stack-trace of an throwable.

Parameters: t The Throwable.

Returns: The nested stack trace, with the root cause first.

getRootCause

public static Throwable getRootCause(Throwable throwable)

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

Parameters: throwable the throwable to get the root cause for

Returns: The root cause of the Throwable.

getRootCauseStackTrace

public static String[] getRootCauseStackTrace(Throwable t)
Creates a compact stack trace for the root cause of the supplied throwable. See printRootCauseStackTrace(Throwable t, PrintStream s)

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.

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.

getThrowableCount

public static int getThrowableCount(Throwable throwable)

Returns the number of Throwable objects in the exception chain.

Parameters: throwable the exception to inspect

Returns: The throwable count.

getThrowables

public static Throwable[] getThrowables(Throwable throwable)

Returns the list of Throwable objects in the exception chain.

Parameters: throwable the exception to inspect

Returns: The list of Throwable objects.

indexOfThrowable

public static int indexOfThrowable(Throwable throwable, Class type)

Delegates to ExceptionUtils, starting the search at the beginning of the exception chain.

See Also: ExceptionUtils

indexOfThrowable

public static int indexOfThrowable(Throwable throwable, 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: throwable 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: 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.

isNestedThrowable

public static boolean isNestedThrowable(Throwable throwable)
Whether an Throwable is considered nested or not.

Parameters: throwable The Throwable.

Returns: boolean true/false

printRootCauseStackTrace

public static void printRootCauseStackTrace(Throwable t, 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 method is equivalent to t.printStackTrace() for throwables that don't have nested causes.

printRootCauseStackTrace

public static void printRootCauseStackTrace(Throwable t)
Equivalent to printRootCauseStackTrace(t, System.err)

printRootCauseStackTrace

public static void printRootCauseStackTrace(Throwable t, PrintWriter writer)
Same as printRootCauseStackTrace(t, stream), except it takes a PrintWriter as an argument.
Copyright © 2001-2010 Codehaus. All Rights Reserved.