Java Doc for ExceptionUtils.java in  » Library » Apache-common-lang » org » apache » commons » lang » exception » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Provides utilities for manipulating and examining Throwable objects.

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

Introspects the Throwable to obtain the cause.

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

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.

Introspects the Throwable to obtain the root cause.

This method walks through the exception chain to the last element, "root" of the tree, using ExceptionUtils.getCause(Throwable) , and returns that exception.

From version 2.2, this method handles recursive cause structures that might otherwise cause infinite loops.

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

The output of this method is consistent across JDK versions. It consists of the root exception followed by each of its wrapping exceptions separated by '[wrapped]'.

Produces a List of stack frames - the message is not included.

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

The result of this method vary by JDK version as this method uses Throwable.printStackTrace(java.io.PrintWriter) .

Gets the stack trace from a Throwable as a String.

The result of this method vary by JDK version as this method uses Throwable.printStackTrace(java.io.PrintWriter) .

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.

From version 2.2, this method handles recursive cause structures that might otherwise cause infinite loops.

Returns the list of Throwable objects in the exception chain.

A throwable without cause will return a list containing one element - the input throwable. A throwable with one cause will return a list containing two elements.

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.

Returns the (zero based) index of the first Throwable that matches the specified class (exactly) in the exception chain.

Returns the (zero based) index of the first Throwable that matches the specified type in the exception chain from a specified index.

Returns the (zero based) index of the first Throwable that matches the specified class or subclass in the exception chain.

Returns the (zero based) index of the first Throwable that matches the specified type in the exception chain from a specified index.

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

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.

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.

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.

Used when printing stack frames to denote the start of a wrapped exception.

Package private for accessibility by test suite.

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

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

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 org.apache.commons.lang.exception.NestableException NestableException . The method names can be added to using ExceptionUtils.addCauseMethodName(String) .

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.

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.

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

The result of this method is highly dependent on the JDK version and whether the exceptions override printStackTrace or not.

The message returned is of the form {ClassNameWithoutPackage}: {ThrowableMessage}
Parameters:
  th - the throwable to get a message for, null returns empty string the message, non-null
since:
   Commons Lang 2.2

Introspects the Throwable to obtain the root cause.

This method walks through the exception chain to the last element, "root" of the tree, using ExceptionUtils.getCause(Throwable) , and returns that exception.

From version 2.2, this method handles recursive cause structures that might otherwise cause infinite loops. If the throwable parameter has a cause of itself, then null will be returned. If the throwable parameter cause chain loops, the last element in the chain before the loop is returned.

The message returned is of the form {ClassNameWithoutPackage}: {ThrowableMessage}
Parameters:
  th - the throwable to get a message for, null returns empty string the message, non-null
since:
   Commons Lang 2.2

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

The output of this method is consistent across JDK versions. It consists of the root exception followed by each of its wrapping exceptions separated by '[wrapped]'. Note that this is the opposite order to the JDK1.4 display.

Produces a List of stack frames - the message is not included. Only the trace of the specified exception is returned, any caused by trace is stripped.

This works in most cases - it will only fail if the exception message contains a line that starts with: "   at".

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

The result of this method vary by JDK version as this method uses Throwable.printStackTrace(java.io.PrintWriter) . On JDK1.3 and earlier, the cause exception will not be shown unless the specified throwable alters printStackTrace.

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 .

Functionality shared between the getStackFrames(Throwable) methods of this and the org.apache.commons.lang.exception.NestableDelegate classes.

Gets the stack trace from a Throwable as a String.

The result of this method vary by JDK version as this method uses Throwable.printStackTrace(java.io.PrintWriter) . On JDK1.3 and earlier, the cause exception will not be shown unless the specified throwable alters printStackTrace.

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.

From version 2.2, this method handles recursive cause structures that might otherwise cause infinite loops. The cause chain is processed until the end is reached, or until the next item in the chain is already in the result set.

Returns the list of Throwable objects in the exception chain.

A throwable without cause will return a list containing one element - the input throwable. A throwable with one cause will return a list containing two elements. - the input throwable and the cause throwable. A null throwable will return a list of size zero.

This method handles recursive cause structures that might otherwise cause infinite loops. The cause chain is processed until the end is reached, or until the next item in the chain is already in the result set.

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 of size zero.

From version 2.2, this method handles recursive cause structures that might otherwise cause infinite loops. The cause chain is processed until the end is reached, or until the next item in the chain is already in the result set.

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 ExceptionUtils.indexOfType(Throwable,Class) for the opposite.

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

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 ExceptionUtils.indexOfType(Throwable,Class,int) 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.

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 ExceptionUtils.indexOfThrowable(Throwable,Class) for the opposite.

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

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 ExceptionUtils.indexOfThrowable(Throwable,Class) 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.

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

Checks whether this Throwable class can store a cause.

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

Parameters:
  throwable - the Throwable to examine, may be null boolean true if nested otherwise false
since:
   2.0

Checks if the Throwable class has a getCause method.

This is true for JDK 1.4 and above.

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 output of this method is consistent across JDK versions. Note that this is the opposite order to the JDK1.4 display.

The method is equivalent to printStackTrace for throwables that don't have nested causes.

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 output of this method is consistent across JDK versions. Note that this is the opposite order to the JDK1.4 display.

The method is equivalent to printStackTrace for throwables that don't have nested causes.

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 output of this method is consistent across JDK versions. Note that this is the opposite order to the JDK1.4 display.

The method is equivalent to printStackTrace for throwables that don't have nested causes.

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

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

Sets the cause of a Throwable using introspection, allowing source code compatibility between pre-1.4 and post-1.4 Java releases.

The typical use of this method is inside a constructor as in the following example:

 import org.apache.commons.lang.exception.ExceptionUtils;
 public class MyException extends Exception {
 public MyException(String msg) {
 super(msg);
 }
 public MyException(String msg, Throwable cause) {
 super(msg);
 ExceptionUtils.setCause(this, cause);
 }
 }