org.codehaus.plexus.util

## Class ExceptionUtils

- java.lang.Object
- - org.codehaus.plexus.util.ExceptionUtils

-     public class ExceptionUtils
      extends Object

  `ExceptionUtils` provides utilities for manipulating `Throwable` objects.

  Since:
    1.0
  Version:
    $Id$
  Author:
    Daniel Rall, Dmitri Plotnikov, Stephen Colebourne

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static String[]` | `CAUSE_METHOD_NAMES` The names of methods commonly used to access a wrapped exception.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `ExceptionUtils()` Constructs a new `ExceptionUtils`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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 specified `Throwable` to obtain the cause.
    `static Throwable` | `getCause(Throwable throwable, String[] methodNames)` Introspects the specified `Throwable` to obtain the cause using a supplied array of method names.
    `static String` | `getFullStackTrace(Throwable t)` A way to get the entire nested stack-trace of an throwable.
    `static Throwable` | `getRootCause(Throwable throwable)` Walks through the exception chain to the last element -- the "root" of the tree -- using `getCause(Throwable)`, 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 String` | `getStackTrace(Throwable t)` A convenient way of extracting the stack trace from an exception.
    `static int` | `getThrowableCount(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 int` | `indexOfThrowable(Throwable throwable, Class type)` Delegates to `indexOfThrowable(Throwable, Class, int)`, starting the search at the beginning of the exception chain.
    `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.
    `static boolean` | `isNestedThrowable(Throwable throwable)` Whether an Throwable is considered nested or not.
    `static void` | `printRootCauseStackTrace(Throwable t)` Equivalent to printRootCauseStackTrace(t, System.err)
    `static void` | `printRootCauseStackTrace(Throwable t, PrintStream stream)` Prints a compact stack trace for the root cause of a throwable.
    `static void` | `printRootCauseStackTrace(Throwable t, PrintWriter writer)` Same as printRootCauseStackTrace(t, stream), except it takes a PrintWriter as an argument.

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

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

- - ### 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(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 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

    - #### getRootCause

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

    - #### 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 `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(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 `Throwable`s in the chain.

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

    - #### 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)`

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

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

    - #### isNestedThrowable

          public static boolean isNestedThrowable(Throwable throwable)

      Whether an Throwable is considered nested or not.
      Parameters:
        `throwable` - The `Throwable`.
      Returns:
        boolean true/false

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

Copyright © 2015. All rights reserved.