ExceptionUtils (Apache Commons Lang 3.20.0 API)
Description: declaration: package: org.apache.commons.lang3.exception, class: ExceptionUtils

# Class ExceptionUtils

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

public class ExceptionUtils extends Object
Provides utilities for manipulating and examining `Throwable` objects.

Since:
  1.0

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ExceptionUtils()`
  Deprecated.
  TODO Make private in 4.0.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T extends RuntimeException>
  T`
  `asRuntimeException(Throwable throwable)`
  Throws the given (usually checked) exception without adding the exception to the throws clause of the calling method.
  `static void`
  `forEach(Throwable throwable, Consumer<Throwable> consumer)`
  Performs an action for each Throwable causes of the given Throwable.
  `static Throwable`
  `getCause(Throwable throwable)`
  Deprecated.
  This feature will be removed in Lang 4, use `Throwable.getCause()` instead.
  `static Throwable`
  `getCause(Throwable throwable, String[] methodNames)`
  Deprecated.
  This feature will be removed in Lang 4, use `Throwable.getCause()` instead.
  `static String[]`
  `getDefaultCauseMethodNames()`
  Deprecated.
  This feature will be removed in Lang 4.
  `static String`
  `getMessage(Throwable th)`
  Gets a short message summarizing the exception.
  `static Throwable`
  `getRootCause(Throwable throwable)`
  Walks the `Throwable` to obtain its root cause.
  `static String`
  `getRootCauseMessage(Throwable throwable)`
  Gets a short message summarizing the root cause exception.
  `static String[]`
  `getRootCauseStackTrace(Throwable throwable)`
  Gets a compact stack trace for the root cause of the supplied `Throwable`.
  `static List<String>`
  `getRootCauseStackTraceList(Throwable throwable)`
  Gets a compact stack trace for the root cause of the supplied `Throwable`.
  `static String[]`
  `getStackFrames(Throwable throwable)`
  Gets the stack trace associated with the specified `Throwable` object, decomposing it into a list of stack frames.
  `static String`
  `getStackTrace(Throwable throwable)`
  Gets the stack trace from a Throwable as a String, including suppressed and cause exceptions.
  `static int`
  `getThrowableCount(Throwable throwable)`
  Gets a count of the number of `Throwable` objects in the exception chain.
  `static List<Throwable>`
  `getThrowableList(Throwable throwable)`
  Gets the list of `Throwable` objects in the exception chain.
  `static Throwable[]`
  `getThrowables(Throwable throwable)`
  Gets the list of `Throwable` objects in the exception chain.
  `static boolean`
  `hasCause(Throwable chain, Class<? extends Throwable> type)`
  Tests if the throwable's causal chain have an immediate or wrapped exception of the given type?
  `static int`
  `indexOfThrowable(Throwable throwable, Class<? extends Throwable> 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<? extends Throwable> 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<? extends Throwable> 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<? extends Throwable> 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`
  `isChecked(Throwable throwable)`
  Checks if a throwable represents a checked exception
  `static boolean`
  `isUnchecked(Throwable throwable)`
  Checks if a throwable represents an unchecked exception
  `static void`
  `printRootCauseStackTrace(Throwable throwable)`
  Prints a compact stack trace for the root cause of a throwable to `System.err`.
  `static void`
  `printRootCauseStackTrace(Throwable throwable, PrintStream printStream)`
  Prints a compact stack trace for the root cause of a throwable.
  `static void`
  `printRootCauseStackTrace(Throwable throwable, PrintWriter printWriter)`
  Prints a compact stack trace for the root cause of a throwable.
  `static void`
  `removeCommonFrames(List<String> causeFrames, List<String> wrapperFrames)`
  Removes common frames from the cause trace given the two stack traces.
  `static <T> T`
  `rethrow(Throwable throwable)`
  Throws the given (usually checked) exception without adding the exception to the throws clause of the calling method.
  `static Stream<Throwable>`
  `stream(Throwable throwable)`
  Streams causes of a Throwable.
  `static <T extends Throwable>
  T`
  `throwableOfThrowable(Throwable throwable, Class<T> clazz)`
  Returns the first `Throwable` that matches the specified class (exactly) in the exception chain.
  `static <T extends Throwable>
  T`
  `throwableOfThrowable(Throwable throwable, Class<T> clazz, int fromIndex)`
  Returns the first `Throwable` that matches the specified type in the exception chain from a specified index.
  `static <T extends Throwable>
  T`
  `throwableOfType(Throwable throwable, Class<T> type)`
  Returns the throwable of the first `Throwable` that matches the specified class or subclass in the exception chain.
  `static <T extends Throwable>
  T`
  `throwableOfType(Throwable throwable, Class<T> type, int fromIndex)`
  Returns the first `Throwable` that matches the specified type in the exception chain from a specified index.
  `static <T> T`
  `throwUnchecked(T throwable)`
  Deprecated.
  Use `throwUnchecked(Throwable)`.
  `static <T extends Throwable>
  T`
  `throwUnchecked(T throwable)`
  Tests whether the specified `Throwable` is unchecked and throws it if so.
  `static <R> R`
  `wrapAndThrow(Throwable throwable)`
  Throws a checked exception without adding the exception to the throws clause of the calling method.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### ExceptionUtils

    @Deprecated public ExceptionUtils()
    Deprecated.
    TODO Make private in 4.0.
    Public constructor allows an instance of `ExceptionUtils` to be created, although that is not normally necessary.

- ## Method Details

  - ### asRuntimeException

    public static <T extends RuntimeException> T asRuntimeException(Throwable throwable)
    Throws the given (usually checked) exception without adding the exception to the throws clause of the calling method. This method prevents throws clause inflation and reduces the clutter of "Caused by" exceptions in the stack trace.

    The use of this technique may be controversial, but useful.

         // There is no throws clause in the method signature.
         public int propagateExample {
             try {
                 // Throws IOException
                 invocation();
             } catch (Exception e) {
                 // Propagates a checked exception.
                 throw ExceptionUtils.asRuntimeException(e);
             }
             // more processing
             ...
             return value;
         }

    This is an alternative to the more conservative approach of wrapping the checked exception in a RuntimeException:

         // There is no throws clause in the method signature.
         public int wrapExample() {
             try {
                 // throws IOException.
                 invocation();
             } catch (Error e) {
                 throw e;
             } catch (RuntimeException e) {
                 // Throws an unchecked exception.
                 throw e;
             } catch (Exception e) {
                 // Wraps a checked exception.
                 throw new UndeclaredThrowableException(e);
             }
             // more processing
             ...
             return value;
         }

    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 Jython, Scala, or Groovy, since these languages do not consider any exceptions as checked.

    Type Parameters:
      `T` - 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.14.0
    See Also:
      - `wrapAndThrow(Throwable)`

  - ### forEach

    public static void forEach(Throwable throwable, Consumer<Throwable> consumer)
    Performs an action for each Throwable causes of the given Throwable.

    A throwable without cause will return a stream containing one element - the input throwable. A throwable with one cause will return a stream containing two elements. - the input throwable and the cause throwable. A `null` throwable will return a stream of count 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 traverse.
      `consumer` - a non-interfering action to perform on the elements.
    Since:
      3.13.0

  - ### getCause

    @Deprecated public static Throwable getCause(Throwable throwable)
    Deprecated.
    This feature will be removed in Lang 4, 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 Throwable getCause(Throwable throwable, String[] methodNames)
    Deprecated.
    This feature will be removed in Lang 4, 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

  - ### getDefaultCauseMethodNames

    @Deprecated public static String[] getDefaultCauseMethodNames()
    Deprecated.
    This feature will be removed in Lang 4.
    Gets 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

  - ### getMessage

    public static String getMessage(Throwable th)
    Gets a short message summarizing 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:
      2.2

  - ### getRootCause

    public static Throwable getRootCause(Throwable throwable)
    Walks the `Throwable` to obtain its root cause.

    This method walks through the exception chain until the last element, the root cause of the chain, using `Throwable.getCause()`, and returns that exception.

    This method handles recursive cause chains that might otherwise cause infinite loops. The cause chain is processed until the end, or until the next item in the chain is already processed. If we detect a loop, then return the element before the loop.

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

  - ### getRootCauseMessage

    public static String getRootCauseMessage(Throwable throwable)
    Gets a short message summarizing the root cause exception.

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

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

  - ### getRootCauseStackTrace

    public static String[] getRootCauseStackTrace(Throwable throwable)
    Gets 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

  - ### getRootCauseStackTraceList

    public static List<String> getRootCauseStackTraceList(Throwable throwable)
    Gets 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:
      a list of stack trace frames, never null.
    Since:
      3.13.0

  - ### getStackFrames

    public static String[] getStackFrames(Throwable throwable)
    Gets 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)`.

    Parameters:
      `throwable` - the `Throwable` to examine, may be null.
    Returns:
      an array of strings describing each stack frame, never null.

  - ### getStackTrace

    public static String getStackTrace(Throwable throwable)
    Gets the stack trace from a Throwable as a String, including suppressed and cause exceptions.

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

    Parameters:
      `throwable` - the `Throwable` to be examined, may be null.
    Returns:
      the stack trace as generated by the exception's `printStackTrace(PrintWriter)` method, or an empty String if `null` input.

  - ### getThrowableCount

    public static int getThrowableCount(Throwable throwable)
    Gets a count of 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`.

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

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

  - ### getThrowableList

    public static List<Throwable> getThrowableList(Throwable throwable)
    Gets 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 chains that might otherwise cause infinite loops. The cause chain is processed until the end, or until the next item in the chain is already in the result list.

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

  - ### getThrowables

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

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

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

  - ### hasCause

    public static boolean hasCause(Throwable chain, Class<? extends Throwable> type)
    Tests if 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)`

  - ### indexOfThrowable

    public static int indexOfThrowable(Throwable throwable, Class<? extends Throwable> 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<? extends Throwable> 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<? extends Throwable> 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<? extends Throwable> 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

  - ### isChecked

    public static boolean isChecked(Throwable throwable)
    Checks if a throwable represents a checked exception
    Parameters:
      `throwable` - The throwable to check.
    Returns:
      True if the given Throwable is a checked exception.
    Since:
      3.13.0

  - ### isUnchecked

    public static boolean isUnchecked(Throwable throwable)
    Checks if a throwable represents an unchecked exception
    Parameters:
      `throwable` - The throwable to check.
    Returns:
      True if the given Throwable is an unchecked exception.
    Since:
      3.13.0

  - ### printRootCauseStackTrace

    public static void printRootCauseStackTrace(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.

    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(Throwable throwable, PrintStream printStream)
    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.
      `printStream` - the stream to output to, may not be null.
    Throws:
      `NullPointerException` - if the printStream is `null`.
    Since:
      2.0

  - ### printRootCauseStackTrace

    public static void printRootCauseStackTrace(Throwable throwable, PrintWriter printWriter)
    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.
      `printWriter` - the writer to output to, may not be null.
    Throws:
      `NullPointerException` - if the printWriter is `null`.
    Since:
      2.0

  - ### removeCommonFrames

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

  - ### rethrow

    public static <T> T rethrow(Throwable throwable)
    Throws the given (usually checked) exception without adding the exception to the throws clause of the calling method. This method prevents throws clause inflation and reduces the clutter of "Caused by" exceptions in the stack trace.

    The use of this technique may be controversial, but useful.

         // There is no throws clause in the method signature.
         public int propagateExample() {
             try {
                 // throws SomeCheckedException.
                 return invocation();
             } catch (SomeCheckedException e) {
                 // Propagates a checked exception and compiles to return an int.
                 return ExceptionUtils.rethrow(e);
             }
         }

    This is an alternative to the more conservative approach of wrapping the checked exception in a RuntimeException:

         // There is no throws clause in the method signature.
         public int wrapExample() {
             try {
                 // throws IOException.
                 return invocation();
             } catch (Error e) {
                 throw e;
             } catch (RuntimeException e) {
                 // Throws an unchecked exception.
                 throw e;
             } catch (Exception e) {
                 // wraps a checked exception.
                 throw new UndeclaredThrowableException(e);
             }
         }

    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 Jython, Scala, or Groovy, since these languages do not consider any exceptions as checked.

    Type Parameters:
      `T` - The type of the return value.
    Parameters:
      `throwable` - The throwable to rethrow.
    Returns:
      Never actually returns, 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)`

  - ### stream

    public static Stream<Throwable> stream(Throwable throwable)
    Streams causes of a Throwable.

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

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

    Parameters:
      `throwable` - The Throwable to traverse.
    Returns:
      A new Stream of Throwable causes.
    Since:
      3.13.0

  - ### throwableOfThrowable

    public static <T extends Throwable> T throwableOfThrowable(Throwable throwable, Class<T> clazz)
    Returns the first `Throwable` that matches the specified class (exactly) in the exception chain. Subclasses of the specified class do not match - see `throwableOfType(Throwable, Class)` for the opposite.

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

    Type Parameters:
      `T` - the type of Throwable you are searching.
    Parameters:
      `throwable` - the throwable to inspect, may be null.
      `clazz` - the class to search for, subclasses do not match, null returns null.
    Returns:
      the first matching throwable from the throwable chain, null if no match or null input.
    Since:
      3.10

  - ### throwableOfThrowable

    public static <T extends Throwable> T throwableOfThrowable(Throwable throwable, Class<T> clazz, int fromIndex)
    Returns 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 `throwableOfType(Throwable, Class, int)` for the opposite.

    A `null` throwable returns `null`. A `null` type returns `null`. No match in the chain returns `null`. A negative start index is treated as zero. A start index greater than the number of throwables returns `null`.

    Type Parameters:
      `T` - the type of Throwable you are searching.
    Parameters:
      `throwable` - the throwable to inspect, may be null.
      `clazz` - the class to search for, subclasses do not match, null returns null.
      `fromIndex` - the (zero-based) index of the starting position, negative treated as zero, larger than chain size returns null.
    Returns:
      the first matching throwable from the throwable chain, null if no match or null input.
    Since:
      3.10

  - ### throwableOfType

    public static <T extends Throwable> T throwableOfType(Throwable throwable, Class<T> type)
    Returns the throwable of the first `Throwable` that matches the specified class or subclass in the exception chain. Subclasses of the specified class do match - see `throwableOfThrowable(Throwable, Class)` for the opposite.

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

    Type Parameters:
      `T` - the type of Throwable you are searching.
    Parameters:
      `throwable` - the throwable to inspect, may be null.
      `type` - the type to search for, subclasses match, null returns null.
    Returns:
      the first matching throwable from the throwable chain, null if no match or null input.
    Since:
      3.10

  - ### throwableOfType

    public static <T extends Throwable> T throwableOfType(Throwable throwable, Class<T> type, int fromIndex)
    Returns the first `Throwable` that matches the specified type in the exception chain from a specified index. Subclasses of the specified class do match - see `throwableOfThrowable(Throwable, Class)` for the opposite.

    A `null` throwable returns `null`. A `null` type returns `null`. No match in the chain returns `null`. A negative start index is treated as zero. A start index greater than the number of throwables returns `null`.

    Type Parameters:
      `T` - the type of Throwable you are searching.
    Parameters:
      `throwable` - the throwable to inspect, may be null.
      `type` - the type to search for, subclasses match, null returns null.
      `fromIndex` - the (zero-based) index of the starting position, negative treated as zero, larger than chain size returns null.
    Returns:
      the first matching throwable from the throwable chain, null if no match or null input.
    Since:
      3.10

  - ### throwUnchecked

    @Deprecated public static <T> T throwUnchecked(T throwable)
    Deprecated.
    Use `throwUnchecked(Throwable)`.
    Tests whether the specified `Throwable` is unchecked and throws it if so.
    Type Parameters:
      `T` - The Throwable type.
    Parameters:
      `throwable` - the throwable to test and throw or return.
    Returns:
      the given throwable.
    Since:
      3.13.0

  - ### throwUnchecked

    public static <T extends Throwable> T throwUnchecked(T throwable)
    Tests whether the specified `Throwable` is unchecked and throws it if so.
    Type Parameters:
      `T` - The Throwable type.
    Parameters:
      `throwable` - the throwable to test and throw or return.
    Returns:
      the given throwable.
    Since:
      3.14.0

  - ### wrapAndThrow

    public static <R> R wrapAndThrow(Throwable throwable)
    Throws 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:
      - `asRuntimeException(Throwable)`
      - `hasCause(Throwable, Class)`