ExceptionUtils
Date: 2017-02-08

org.apache.commons.lang3.exception

## Class ExceptionUtils

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

-     public class ExceptionUtils
      extends java.lang.Object

  Provides utilities for manipulating and examining `Throwable` objects.

  Since:
    1.0

- - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.Throwable` | `getCause(java.lang.Throwable throwable)` Deprecated. This feature will be removed in Lang 4.0, use `Throwable.getCause()` instead
    `static java.lang.Throwable` | `getCause(java.lang.Throwable throwable, java.lang.String[] methodNames)` Deprecated. This feature will be removed in Lang 4.0, use `Throwable.getCause()` instead
    `static java.lang.String[]` | `getDefaultCauseMethodNames()` Deprecated. This feature will be removed in Lang 4.0
    `static java.lang.String` | `getMessage(java.lang.Throwable th)` Gets a short message summarising the exception.
    `static java.lang.Throwable` | `getRootCause(java.lang.Throwable throwable)` Introspects the `Throwable` to obtain the root cause.
    `static java.lang.String` | `getRootCauseMessage(java.lang.Throwable th)` Gets a short message summarising the root cause exception.
    `static java.lang.String[]` | `getRootCauseStackTrace(java.lang.Throwable throwable)` Creates a compact stack trace for the root cause of the supplied `Throwable`.
    `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.util.List<java.lang.Throwable>` | `getThrowableList(java.lang.Throwable throwable)` Returns the list 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 boolean` | `hasCause(java.lang.Throwable chain, java.lang.Class<? extends java.lang.Throwable> type)` Does the throwable's causal chain have an immediate or wrapped exception of the given type?
    `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 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` | `removeCommonFrames(java.util.List<java.lang.String> causeFrames, java.util.List<java.lang.String> wrapperFrames)` Removes common frames from the cause trace given the two stack traces.
    `static <R> R` | `rethrow(java.lang.Throwable throwable)` Throw a checked exception without adding the exception to the throws clause of the calling method.
    `static <R> R` | `wrapAndThrow(java.lang.Throwable throwable)` Throw a checked exception without adding the exception to the throws clause of the calling method.

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

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

- - ### Constructor Detail

    - #### ExceptionUtils

          public ExceptionUtils()

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

  - ### Method Detail

    - #### getDefaultCauseMethodNames

          @Deprecated
          public static java.lang.String[] getDefaultCauseMethodNames()

      Deprecated. This feature will be removed in Lang 4.0

      Returns the default names used when searching for the cause of an exception.

      This may be modified and used in the overloaded getCause(Throwable, String[]) method.

      Returns:
        cloned array of the default method names
      Since:
        3.0

    - #### getCause

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

      Deprecated. This feature will be removed in Lang 4.0, use `Throwable.getCause()` instead

      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.

      The default list searched for are:

      - `getCause()`
      - `getNextException()`
      - `getTargetException()`
      - `getException()`
      - `getSourceException()`
      - `getRootCause()`
      - `getCausedByException()`
      - `getNested()`

      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

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

      Deprecated. This feature will be removed in Lang 4.0, use `Throwable.getCause()` instead

      Introspects the `Throwable` to obtain the cause.

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

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

      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 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 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 java.util.List<java.lang.Throwable> getThrowableList(java.lang.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(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)` 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(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)` 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(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)` 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(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)` 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

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

      Parameters:
        `throwable` - the throwable to output
      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 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.

      Parameters:
        `throwable` - the throwable to output, may be null
        `stream` - the stream to output to, may not be null
      Throws:
        `java.lang.IllegalArgumentException` - if the stream is `null`
      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 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.

      Parameters:
        `throwable` - the throwable to output, may be null
        `writer` - the writer to output to, may not be null
      Throws:
        `java.lang.IllegalArgumentException` - if the writer is `null`
      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`.

      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.

      Parameters:
        `throwable` - the throwable to examine, may be null
      Returns:
        an array of stack trace frames, never null
      Since:
        2.0

    - #### removeCommonFrames

          public static void removeCommonFrames(java.util.List<java.lang.String> causeFrames,
                                java.util.List<java.lang.String> 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:
        `java.lang.IllegalArgumentException` - if either argument is null
      Since:
        2.0

    - #### getStackTrace

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

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

      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 examine, may be null
      Returns:
        an array of strings describing each stack frame, never null

    - #### getMessage

          public static java.lang.String getMessage(java.lang.Throwable th)

      Gets a short message summarising the exception.

      The message returned is of the form {ClassNameWithoutPackage}: {ThrowableMessage}

      Parameters:
        `th` - the throwable to get a message for, null returns empty string
      Returns:
        the message, non-null
      Since:
        Commons Lang 2.2

    - #### getRootCauseMessage

          public static java.lang.String getRootCauseMessage(java.lang.Throwable th)

      Gets a short message summarising the root cause exception.

      The message returned is of the form {ClassNameWithoutPackage}: {ThrowableMessage}

      Parameters:
        `th` - the throwable to get a message for, null returns empty string
      Returns:
        the message, non-null
      Since:
        Commons Lang 2.2

    - #### rethrow

          public static <R> R rethrow(java.lang.Throwable throwable)

      Throw a checked exception without adding the exception to the throws clause of the calling method. This method prevents throws clause pollution and reduces the clutter of "Caused by" exceptions in the stacktrace.

      The use of this technique may be controversial, but exceedingly useful to library developers. `public int propagateExample { // note that there is no throws clause try { return invocation(); // throws IOException } catch (Exception e) { return ExceptionUtils.rethrow(e); // propagates a checked exception } }`

      This is an alternative to the more conservative approach of wrapping the checked exception in a RuntimeException: `public int wrapExample { // note that there is no throws clause try { return invocation(); // throws IOException } catch (Error e) { throw e; } catch (RuntimeException e) { throw e; // wraps a checked exception } catch (Exception e) { throw new UndeclaredThrowableException(e); // wraps a checked exception } }`

      One downside to using this approach is that the java compiler will not allow invoking code to specify a checked exception in a catch clause unless there is some code path within the try block that has invoked a method declared with that checked exception. If the invoking site wishes to catch the shaded checked exception, it must either invoke the shaded code through a method re-declaring the desired checked exception, or catch Exception and use the instanceof operator. Either of these techniques are required when interacting with non-java jvm code such as Jyton, Scala, or Groovy, since these languages do not consider any exceptions as checked.

      Type Parameters:
        `R` - The type of the returned value.
      Parameters:
        `throwable` - The throwable to rethrow.
      Returns:
        Never actually returned, this generic type matches any type which the calling site requires. "Returning" the results of this method, as done in the propagateExample above, will satisfy the java compiler requirement that all code paths return a value.
      Since:
        3.5
      See Also:
        `wrapAndThrow(Throwable)`

    - #### wrapAndThrow

          public static <R> R wrapAndThrow(java.lang.Throwable throwable)

      Throw a checked exception without adding the exception to the throws clause of the calling method. For checked exceptions, this method throws an UndeclaredThrowableException wrapping the checked exception. For Errors and RuntimeExceptions, the original exception is rethrown.

      The downside to using this approach is that invoking code which needs to handle specific checked exceptions must sniff up the exception chain to determine if the caught exception was caused by the checked exception.

      Type Parameters:
        `R` - The type of the returned value.
      Parameters:
        `throwable` - The throwable to rethrow.
      Returns:
        Never actually returned, this generic type matches any type which the calling site requires. "Returning" the results of this method will satisfy the java compiler requirement that all code paths return a value.
      Since:
        3.5
      See Also:
        `rethrow(Throwable)`, `hasCause(Throwable, Class)`

    - #### hasCause

          public static boolean hasCause(java.lang.Throwable chain,
                         java.lang.Class<? extends java.lang.Throwable> type)

      Does the throwable's causal chain have an immediate or wrapped exception of the given type?
      Parameters:
        `chain` - The root of a Throwable causal chain.
        `type` - The exception type to test.
      Returns:
        true, if chain is an instance of type or is an UndeclaredThrowableException wrapping a cause.
      Since:
        3.5
      See Also:
        `wrapAndThrow(Throwable)`