Overview  Package   Class  Use  Deprecated  Index
Home >> All >> org >> apache >> commons >> lang >> [ exception overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

org.apache.commons.lang.exception
Class ExceptionUtils  

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

---

public class ExceptionUtils

extends java.lang.Object

Provides utilities for manipulating and examining Throwable objects.

Since:

1.0

Version:

$Id: ExceptionUtils.java 161243 2005-04-14 04:30:28Z ggregory $

---

Field Summary
private static java.lang.String[]	CAUSE_METHOD_NAMES           The names of methods commonly used to access a wrapped exception.
private static java.lang.reflect.Method	THROWABLE_CAUSE_METHOD           The Method object for JDK1.4 getCause.
(package private) static java.lang.String	WRAPPED_MARKER           Used when printing stack frames to denote the start of a wrapped exception.

 

Constructor Summary

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

 

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 Throwable to obtain the cause.
static java.lang.Throwable	getCause(java.lang.Throwable throwable, java.lang.String[] methodNames)           Introspects the Throwable to obtain the cause.
private static java.util.ArrayList	getCauseMethodNameList()           Returns CAUSE_METHOD_NAMES 55 as a List.
private static java.lang.Throwable	getCauseUsingFieldName(java.lang.Throwable throwable, java.lang.String fieldName)           Finds a Throwable by field name.
private static java.lang.Throwable	getCauseUsingMethodName(java.lang.Throwable throwable, java.lang.String methodName)           Finds a Throwable by method name.
private static java.lang.Throwable	getCauseUsingWellKnownTypes(java.lang.Throwable throwable)           Finds a Throwable for known types.
static java.lang.String	getFullStackTrace(java.lang.Throwable throwable)           A way to get the entire nested stack-trace of an throwable.
static java.lang.Throwable	getRootCause(java.lang.Throwable throwable)           Introspects the Throwable to obtain the root cause.
static java.lang.String[]	getRootCauseStackTrace(java.lang.Throwable throwable)           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)           Returns an array where each element is a line from the argument.
static java.lang.String[]	getStackFrames(java.lang.Throwable throwable)           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 throwable)           Gets the stack trace from a Throwable as a String.
static int	getThrowableCount(java.lang.Throwable throwable)           Counts 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.
private static int	indexOf(java.lang.Throwable throwable, java.lang.Class type, int fromIndex, boolean subclass)
static int	indexOfThrowable(java.lang.Throwable throwable, java.lang.Class clazz)           Returns the (zero based) index of the first Throwable that matches the specified class (exactly) in the exception chain.
static int	indexOfThrowable(java.lang.Throwable throwable, java.lang.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(java.lang.Throwable throwable, java.lang.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(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 from a specified index.
static boolean	isCauseMethodName(java.lang.String methodName)           Tests if the list of method names used in the search for Throwable objects include the given name.
static boolean	isNestedThrowable(java.lang.Throwable throwable)           Checks whether this Throwable class can store a cause.
static boolean	isThrowableNested()           Checks if the Throwable class has a getCause method.
static void	printRootCauseStackTrace(java.lang.Throwable throwable)           Prints a compact stack trace for the root cause of a throwable to System.err.
static void	printRootCauseStackTrace(java.lang.Throwable throwable, java.io.PrintStream stream)           Prints a compact stack trace for the root cause of a throwable.
static void	printRootCauseStackTrace(java.lang.Throwable throwable, java.io.PrintWriter writer)           Prints a compact stack trace for the root cause of a throwable.
static void	removeCauseMethodName(java.lang.String methodName)           Removes from the list of method names used in the search for Throwable objects.
static void	removeCommonFrames(java.util.List causeFrames, java.util.List wrapperFrames)           Removes common frames from the cause trace given the two stack traces.
private static java.lang.String[]	toArray(java.util.List list)           Returns the given list as a String[].

 

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

private static java.lang.String[] CAUSE_METHOD_NAMES

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

---

THROWABLE_CAUSE_METHOD

private static final java.lang.reflect.Method THROWABLE_CAUSE_METHOD

The Method object for JDK1.4 getCause.

Constructor Detail

ExceptionUtils

public ExceptionUtils()

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

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.

Since:

2.0

---

removeCauseMethodName

public static void removeCauseMethodName(java.lang.String methodName)

Removes from the list of method names used in the search for Throwable objects.

Since:

2.1

---

toArray

private static java.lang.String[] toArray(java.util.List list)

Returns the given list as a String[].

---

getCauseMethodNameList

private static java.util.ArrayList getCauseMethodNameList()

Returns CAUSE_METHOD_NAMES 55 as a List.

---

isCauseMethodName

public static boolean isCauseMethodName(java.lang.String methodName)

Tests if the list of method names used in the search for Throwable objects include the given name.

Since:

2.1

---

getCause

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

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, and NestableException. The method names can be added to using addCauseMethodName(String) 55 .

The default list searched for are:

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

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.

Since:

1.0

---

getCause

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

Introspects the Throwable to obtain the cause.

1. Try known exception types.
2. Try the supplied array of method names.
3. Try the field 'detail'.

A null set of method names means use the default set. A null in the set of method names will be ignored.

Since:

1.0

---

getRootCause

public static java.lang.Throwable getRootCause(java.lang.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) 55 , and returns that exception.

---

getCauseUsingWellKnownTypes

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

Finds a Throwable for known types.

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

---

getCauseUsingMethodName

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

Finds a Throwable by method name.

---

getCauseUsingFieldName

private static java.lang.Throwable getCauseUsingFieldName(java.lang.Throwable throwable,
                                                          java.lang.String fieldName)

Finds a Throwable by field name.

---

isThrowableNested

public static boolean isThrowableNested()

Checks if the Throwable class has a getCause method.

This is true for JDK 1.4 and above.

Since:

2.0

---

isNestedThrowable

public static boolean isNestedThrowable(java.lang.Throwable throwable)

Checks whether this Throwable class can store a cause.

This method does not check whether it actually does store a cause.

Since:

2.0

---

getThrowableCount

public static int getThrowableCount(java.lang.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.

---

getThrowables

public static java.lang.Throwable[] getThrowables(java.lang.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 size zero.

---

indexOfThrowable

public static int indexOfThrowable(java.lang.Throwable throwable,
                                   java.lang.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) 55 for the opposite.

A null throwable returns -1. A null type returns -1. No match in the chain returns -1.

---

indexOfThrowable

public static int indexOfThrowable(java.lang.Throwable throwable,
                                   java.lang.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) 55 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.

---

indexOfType

public static int indexOfType(java.lang.Throwable throwable,
                              java.lang.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) 55 for the opposite.

A null throwable returns -1. A null type returns -1. No match in the chain returns -1.

Since:

2.1

---

indexOfType

public static int indexOfType(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 from a specified index. Subclasses of the specified class do match - see indexOfThrowable(Throwable, Class) 55 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.

Since:

2.1

---

indexOf

private static int indexOf(java.lang.Throwable throwable,
                           java.lang.Class type,
                           int fromIndex,
                           boolean subclass)

---

printRootCauseStackTrace

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

Since:

2.0

---

printRootCauseStackTrace

public static void printRootCauseStackTrace(java.lang.Throwable throwable,
                                            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 printStackTrace for throwables that don't have nested causes.

Since:

2.0

---

printRootCauseStackTrace

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

Since:

2.0

---

getRootCauseStackTrace

public static java.lang.String[] getRootCauseStackTrace(java.lang.Throwable throwable)

Creates a compact stack trace for the root cause of the supplied Throwable.

Since:

2.0

---

removeCommonFrames

public static void removeCommonFrames(java.util.List causeFrames,
                                      java.util.List wrapperFrames)

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

Since:

2.0

---

getStackTrace

public static java.lang.String getStackTrace(java.lang.Throwable throwable)

Gets the stack trace from a Throwable as a String.

---

getFullStackTrace

public static java.lang.String getFullStackTrace(java.lang.Throwable throwable)

A way to get the entire nested stack-trace of an throwable.

Since:

2.0

---

getStackFrames

public static java.lang.String[] getStackFrames(java.lang.Throwable throwable)

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

---

getStackFrames

static java.lang.String[] getStackFrames(java.lang.String stackTrace)

Returns an array where each element is a line from the argument.

The end of line is determined by the value of SystemUtils.LINE_SEPARATOR>SystemUtils.LINE_SEPARATOR 55 .

Functionality shared between the getStackFrames(Throwable) methods of this and the NestableDelegate 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".

---

Overview  Package   Class  Use  Deprecated  Index
Home >> All >> org >> apache >> commons >> lang >> [ exception overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---