org.codehaus.plexus.util
Class ExceptionUtils

java.lang.Object
  extended by org.codehaus.plexus.util.ExceptionUtils

public class ExceptionUtils
extends java.lang.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 java.lang.String[] CAUSE_METHOD_NAMES
          The names of methods commonly used to access a wrapped exception.
(package private) static java.lang.String WRAPPED_MARKER
          Used when printing stack frames to denote the start of a wrapped exception.
 
Constructor Summary
protected ExceptionUtils()
          Constructs a new ExceptionUtils.
 
Method Summary
static void addCauseMethodName(java.lang.String methodName)
          Adds to the list of method names used in the search for Throwable objects.
static java.lang.Throwable getCause(java.lang.Throwable throwable)
          Introspects the specified Throwable to obtain the cause.
static java.lang.Throwable getCause(java.lang.Throwable throwable, java.lang.String[] methodNames)
          Introspects the specified Throwable to obtain the cause using a supplied array of method names.
private static java.lang.Throwable getCauseUsingFieldName(java.lang.Throwable throwable, java.lang.String fieldName)
          Find a throwable by field name.
private static java.lang.Throwable getCauseUsingMethodName(java.lang.Throwable throwable, java.lang.String methodName)
          Find a throwable by method name.
private static java.lang.Throwable getCauseUsingWellKnownTypes(java.lang.Throwable throwable)
          Uses instanceof checks to examine the exception, looking for well known types which could contain chained or wrapped exceptions.
static java.lang.String getFullStackTrace(java.lang.Throwable t)
          A way to get the entire nested stack-trace of an throwable.
static java.lang.Throwable getRootCause(java.lang.Throwable throwable)
          Walks through the exception chain to the last element -- the "root" of the tree -- using getCause(Throwable), and returns that exception.
static java.lang.String[] getRootCauseStackTrace(java.lang.Throwable t)
          Creates a compact stack trace for the root cause of the supplied throwable.
(package private) static java.util.List getStackFrameList(java.lang.Throwable t)
          Produces a List of stack frames - the message is not included.
(package private) static java.lang.String[] getStackFrames(java.lang.String stackTrace)
          Functionality shared between the getStackFrames(Throwable) methods of this and the 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 throwable)
          Returns the number of Throwable objects in the exception chain.
static java.lang.Throwable[] getThrowables(java.lang.Throwable throwable)
          Returns the list of Throwable objects in the exception chain.
static int indexOfThrowable(java.lang.Throwable throwable, 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 throwable, 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.
static boolean isNestedThrowable(java.lang.Throwable throwable)
          Whether an Throwable is considered nested or not.
static void printRootCauseStackTrace(java.lang.Throwable t)
          Equivalent to printRootCauseStackTrace(t, System.err)
static void printRootCauseStackTrace(java.lang.Throwable t, java.io.PrintStream stream)
          Prints a compact stack trace for the root cause of a throwable.
static void printRootCauseStackTrace(java.lang.Throwable t, java.io.PrintWriter writer)
          Same as printRootCauseStackTrace(t, stream), except it takes a PrintWriter as an argument.
private static void removeCommonFrames(java.util.List causeFrames, java.util.List wrapperFrames)
          Given two stack traces, removes common frames from the cause trace.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

WRAPPED_MARKER

static final java.lang.String WRAPPED_MARKER
Used when printing stack frames to denote the start of a wrapped exception. Package private for accessibility by test suite.

See Also:
Constant Field Values

CAUSE_METHOD_NAMES

protected static java.lang.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(java.lang.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 java.lang.Throwable getCause(java.lang.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(String). 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:
java.lang.NullPointerException - if the throwable is null

getCause

public static java.lang.Throwable getCause(java.lang.Throwable throwable,
                                           java.lang.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:
java.lang.NullPointerException - if the method names array is null or contains null
java.lang.NullPointerException - if the throwable is null

getRootCause

public static java.lang.Throwable getRootCause(java.lang.Throwable throwable)

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

Parameters:
throwable - the throwable to get the root cause for
Returns:
The root cause of the Throwable.

getCauseUsingWellKnownTypes

private static java.lang.Throwable getCauseUsingWellKnownTypes(java.lang.Throwable throwable)

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

Parameters:
throwable - the exception to examine
Returns:
The wrapped exception, or null if not found.

getCauseUsingMethodName

private static java.lang.Throwable getCauseUsingMethodName(java.lang.Throwable throwable,
                                                           java.lang.String methodName)

Find a throwable by method name.

Parameters:
throwable - 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 throwable,
                                                          java.lang.String fieldName)

Find a throwable by field name.

Parameters:
throwable - 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 throwable)

Returns the number of Throwable objects in the exception chain.

Parameters:
throwable - the exception to inspect
Returns:
The throwable count.

getThrowables

public static java.lang.Throwable[] getThrowables(java.lang.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(java.lang.Throwable throwable,
                                   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 throwable,
                                   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:
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:
java.lang.IndexOutOfBoundsException - If the fromIndex argument is negative or not less than the count of Throwables in the chain.

printRootCauseStackTrace

public static void printRootCauseStackTrace(java.lang.Throwable t,
                                            java.io.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(java.lang.Throwable t)
Equivalent to printRootCauseStackTrace(t, System.err)


printRootCauseStackTrace

public static void printRootCauseStackTrace(java.lang.Throwable t,
                                            java.io.PrintWriter writer)
Same as printRootCauseStackTrace(t, stream), except it takes a PrintWriter as an argument.


getRootCauseStackTrace

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


removeCommonFrames

private static void removeCommonFrames(java.util.List causeFrames,
                                       java.util.List wrapperFrames)
Given two stack traces, removes common frames from the cause trace.

Parameters:
causeFrames - stack trace of a cause throwable
wrapperFrames - stack trace of a wrapper throwable

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.

getFullStackTrace

public static java.lang.String getFullStackTrace(java.lang.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.

isNestedThrowable

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

Parameters:
throwable - The Throwable.
Returns:
boolean true/false

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


getStackFrameList

static java.util.List getStackFrameList(java.lang.Throwable t)
Produces a List of stack frames - the message is not included. This works in most cases - it will only fail if the exception message contains a line that starts with: " at".

Parameters:
t - is any throwable
Returns:
List of stack frames