co.aikar.commands.apachecommonslang

## Class ApacheCommonsExceptionUtil

- java.lang.Object
- - co.aikar.commands.apachecommonslang.ApacheCommonsExceptionUtil

    public class ApacheCommonsExceptionUtil
    extends Object

Provides utilities for manipulating and examining `Throwable` objects.

Since:
  1.0
Version:
  $Id$
Author:
  Daniel Rall, Dmitri Plotnikov, Stephen Colebourne, Gary Gregory, Pete Gieser

### Nested Class Summary

Nested Classes
`static interface` `ApacheCommonsExceptionUtil.Nestable` An interface to be implemented by `Throwable` extensions which would like to be able to nest root exceptions inside themselves.

### Constructor Summary

Constructors
Constructor and Description
`ApacheCommonsExceptionUtil()` Public constructor allows an instance of `ExceptionUtils` to be created, although that is not normally necessary.

### Method Summary

All Methods Static Methods Concrete Methods
`static void` `addCauseMethodName(String methodName)` Adds to the list of method names used in the search for `Throwable` objects.
`static Throwable` `getCause(Throwable throwable)` Introspects the `Throwable` to obtain the cause.
`static Throwable` `getCause(Throwable throwable, String[] methodNames)` Introspects the `Throwable` to obtain the cause.
`static String` `getFullStackTrace(Throwable throwable)` A way to get the entire nested stack-trace of an throwable.
`static Throwable` `getRootCause(Throwable throwable)` Introspects the `Throwable` to obtain the root cause.
`static String` `getStackTrace(Throwable throwable)` Gets the stack trace from a Throwable as a String.
`static int` `getThrowableCount(Throwable throwable)` Counts the number of `Throwable` objects in the exception chain.
`static List` `getThrowableList(Throwable throwable)` Returns the list of `Throwable` objects in the exception chain.
`static Throwable[]` `getThrowables(Throwable throwable)` Returns the list of `Throwable` objects in the exception chain.
`static int` `indexOfThrowable(Throwable throwable, Class clazz)` Returns the (zero based) index of the first `Throwable` that matches the specified class (exactly) in the exception chain.
`static int` `indexOfThrowable(Throwable throwable, 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(Throwable throwable, 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(Throwable throwable, 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(String methodName)` Tests if the list of method names used in the search for `Throwable` objects include the given name.
`static boolean` `isNestedThrowable(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` `removeCauseMethodName(String methodName)` Removes from the list of method names used in the search for `Throwable` objects.
`static void` `removeCommonFrames(List causeFrames, List wrapperFrames)` Removes common frames from the cause trace given the two stack traces.
`static boolean` `setCause(Throwable target, Throwable cause)` Sets the cause of a `Throwable` using introspection, allowing source code compatibility between pre-1.4 and post-1.4 Java releases.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### ApacheCommonsExceptionUtil

    public ApacheCommonsExceptionUtil()

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

### 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
Since:
  2.0

#### removeCauseMethodName

    public static void removeCauseMethodName(String methodName)

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

Parameters:
  `methodName` - the methodName to remove from the list, `null` and empty strings are ignored
Since:
  2.1

#### setCause

    public static boolean setCause(Throwable target,
                                   Throwable cause)

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);
        }
     }

Parameters:
  `target` - the target `Throwable`
  `cause` - the `Throwable` to set in the target
Returns:
  a `true` if the target has been modified
Since:
  2.2

#### isCauseMethodName

    public static boolean isCauseMethodName(String methodName)

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

Parameters:
  `methodName` - the methodName to search in the list.
Returns:
  if the list of method names used in the search for `Throwable` objects include the given name.
Since:
  2.1

#### getCause

    public static Throwable getCause(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 The method names can be added to using `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`.

Parameters:
  `throwable` - the throwable to introspect for a cause, may be null
Returns:
  the cause of the `Throwable`, `null` if none found or null throwable input
Since:
  1.0

#### getCause

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

Parameters:
  `throwable` - the throwable to introspect for a cause, may be null
  `methodNames` - the method names, null treated as default set
Returns:
  the cause of the `Throwable`, `null` if none found or null throwable input
Since:
  1.0

#### getRootCause

    public static Throwable getRootCause(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)`, 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.

Parameters:
  `throwable` - the throwable to get the root cause for, may be null
Returns:
  the root cause of the `Throwable`, `null` if none found or null throwable input

#### isThrowableNested

    public static boolean isThrowableNested()

Checks if the Throwable class has a `getCause` method.

This is true for JDK 1.4 and above.

Returns:
  true if Throwable is nestable
Since:
  2.0

#### isNestedThrowable

    public static boolean isNestedThrowable(Throwable throwable)

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
Returns:
  boolean `true` if nested otherwise `false`
Since:
  2.0

#### getThrowableCount

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

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.

Parameters:
  `throwable` - the throwable to inspect, may be null
Returns:
  the count of throwables, zero if null input

#### getThrowables

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

Parameters:
  `throwable` - the throwable to inspect, may be null
Returns:
  the array of throwables, never null
See Also:
  `getThrowableList(Throwable)`

#### getThrowableList

    public static List getThrowableList(Throwable throwable)

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.

Parameters:
  `throwable` - the throwable to inspect, may be null
Returns:
  the list of throwables, never null
Since:
  Commons Lang 2.2

#### indexOfThrowable

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

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

Parameters:
  `throwable` - the throwable to inspect, may be null
  `clazz` - the class to search for, subclasses do not match, null returns -1
Returns:
  the index into the throwable chain, -1 if no match or null input

#### indexOfThrowable

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

Parameters:
  `throwable` - the throwable to inspect, may be null
  `clazz` - the class to search for, subclasses do not match, null returns -1
  `fromIndex` - the (zero based) index of the starting position, negative treated as zero, larger than chain size returns -1
Returns:
  the index into the throwable chain, -1 if no match or null input

#### indexOfType

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

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

Parameters:
  `throwable` - the throwable to inspect, may be null
  `type` - the type to search for, subclasses match, null returns -1
Returns:
  the index into the throwable chain, -1 if no match or null input
Since:
  2.1

#### indexOfType

    public static int indexOfType(Throwable throwable,
                                  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)` 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`.

Parameters:
  `throwable` - the throwable to inspect, may be null
  `type` - the type to search for, subclasses match, null returns -1
  `fromIndex` - the (zero based) index of the starting position, negative treated as zero, larger than chain size returns -1
Returns:
  the index into the throwable chain, -1 if no match or null input
Since:
  2.1

#### removeCommonFrames

    public static void removeCommonFrames(List causeFrames,
                                          List wrapperFrames)

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

Parameters:
  `causeFrames` - stack trace of a cause throwable
  `wrapperFrames` - stack trace of a wrapper throwable
Throws:
  `IllegalArgumentException` - if either argument is null
Since:
  2.0

#### getFullStackTrace

    public static String getFullStackTrace(Throwable throwable)

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.

Parameters:
  `throwable` - the `Throwable` to be examined
Returns:
  the nested stack trace, with the root cause first
Since:
  2.0

#### getStackTrace

    public static String getStackTrace(Throwable throwable)

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.

Parameters:
  `throwable` - the `Throwable` to be examined
Returns:
  the stack trace as generated by the exception's `printStackTrace(PrintWriter)` method