Throwables
Date: 2016-05-24

com.google.common.base

## Class Throwables

- java.lang.Object
- - com.google.common.base.Throwables

-     public final class Throwables
      extends java.lang.Object

  Static utility methods pertaining to instances of `Throwable`.

  See the Guava User Guide entry on Throwables.

  Since:
    1.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.util.List<java.lang.Throwable>` | `getCausalChain(java.lang.Throwable throwable)` Gets a `Throwable` cause chain as a list.
    `static java.lang.Throwable` | `getRootCause(java.lang.Throwable throwable)` Returns the innermost cause of `throwable`.
    `static java.lang.String` | `getStackTraceAsString(java.lang.Throwable throwable)` Returns a string containing the result of `toString()`, followed by the full, recursive stack trace of `throwable`.
    `static java.util.List<java.lang.StackTraceElement>` | `lazyStackTrace(java.lang.Throwable throwable)` Returns the stack trace of `throwable`, possibly providing slower iteration over the full trace but faster iteration over parts of the trace.
    `static boolean` | `lazyStackTraceIsLazy()` Returns whether `lazyStackTrace(java.lang.Throwable)` will use the special implementation described in its documentation.
    `static java.lang.RuntimeException` | `propagate(java.lang.Throwable throwable)` Propagates `throwable` as-is if it is an instance of `RuntimeException` or `Error`, or else as a last resort, wraps it in a `RuntimeException` and then propagates.
    `static <X extends java.lang.Throwable> void` | `propagateIfInstanceOf(java.lang.Throwable throwable, java.lang.Class<X> declaredType)` Propagates `throwable` exactly as-is, if and only if it is an instance of `declaredType`.
    `static void` | `propagateIfPossible(java.lang.Throwable throwable)` Propagates `throwable` exactly as-is, if and only if it is an instance of `RuntimeException` or `Error`.
    `static <X extends java.lang.Throwable> void` | `propagateIfPossible(java.lang.Throwable throwable, java.lang.Class<X> declaredType)` Propagates `throwable` exactly as-is, if and only if it is an instance of `RuntimeException`, `Error`, or `declaredType`.
    `static <X1 extends java.lang.Throwable,X2 extends java.lang.Throwable> void` | `propagateIfPossible(java.lang.Throwable throwable, java.lang.Class<X1> declaredType1, java.lang.Class<X2> declaredType2)` Propagates `throwable` exactly as-is, if and only if it is an instance of `RuntimeException`, `Error`, `declaredType1`, or `declaredType2`.

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

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

- - ### Method Detail

    - #### propagateIfInstanceOf

          public static <X extends java.lang.Throwable> void propagateIfInstanceOf(@Nullable
                                                                   java.lang.Throwable throwable,
                                                                   java.lang.Class<X> declaredType)
                                            throws X extends java.lang.Throwable

      Propagates `throwable` exactly as-is, if and only if it is an instance of `declaredType`. Example usage:

             try {
               someMethodThatCouldThrowAnything();
             } catch (IKnowWhatToDoWithThisException e) {
               handle(e);
             } catch (Throwable t) {
               Throwables.propagateIfInstanceOf(t, IOException.class);
               Throwables.propagateIfInstanceOf(t, SQLException.class);
               throw Throwables.propagate(t);
             }

      Throws:
        `X extends java.lang.Throwable`

    - #### propagateIfPossible

          public static void propagateIfPossible(@Nullable
                                 java.lang.Throwable throwable)

      Propagates `throwable` exactly as-is, if and only if it is an instance of `RuntimeException` or `Error`. Example usage:

             try {
               someMethodThatCouldThrowAnything();
             } catch (IKnowWhatToDoWithThisException e) {
               handle(e);
             } catch (Throwable t) {
               Throwables.propagateIfPossible(t);
               throw new RuntimeException("unexpected", t);
             }

    - #### propagateIfPossible

          public static <X extends java.lang.Throwable> void propagateIfPossible(@Nullable
                                                                 java.lang.Throwable throwable,
                                                                 java.lang.Class<X> declaredType)
                                          throws X extends java.lang.Throwable

      Propagates `throwable` exactly as-is, if and only if it is an instance of `RuntimeException`, `Error`, or `declaredType`. Example usage:

             try {
               someMethodThatCouldThrowAnything();
             } catch (IKnowWhatToDoWithThisException e) {
               handle(e);
             } catch (Throwable t) {
               Throwables.propagateIfPossible(t, OtherException.class);
               throw new RuntimeException("unexpected", t);
             }

      Parameters:
        `throwable` - the Throwable to possibly propagate
        `declaredType` - the single checked exception type declared by the calling method
      Throws:
        `X extends java.lang.Throwable`

    - #### propagateIfPossible

          public static <X1 extends java.lang.Throwable,X2 extends java.lang.Throwable> void propagateIfPossible(@Nullable
                                                                                                 java.lang.Throwable throwable,
                                                                                                 java.lang.Class<X1> declaredType1,
                                                                                                 java.lang.Class<X2> declaredType2)
                                          throws X1 extends java.lang.Throwable,
                                                 X2 extends java.lang.Throwable

      Propagates `throwable` exactly as-is, if and only if it is an instance of `RuntimeException`, `Error`, `declaredType1`, or `declaredType2`. In the unlikely case that you have three or more declared checked exception types, you can handle them all by invoking these methods repeatedly. See usage example in `propagateIfPossible(Throwable, Class)`.
      Parameters:
        `throwable` - the Throwable to possibly propagate
        `declaredType1` - any checked exception type declared by the calling method
        `declaredType2` - any other checked exception type declared by the calling method
      Throws:
        `X1 extends java.lang.Throwable`

    - #### propagate

          public static java.lang.RuntimeException propagate(java.lang.Throwable throwable)

      Propagates `throwable` as-is if it is an instance of `RuntimeException` or `Error`, or else as a last resort, wraps it in a `RuntimeException` and then propagates.

      This method always throws an exception. The `RuntimeException` return type is only for client code to make Java type system happy in case a return value is required by the enclosing method. Example usage:

             T doSomething() {
               try {
                 return someMethodThatCouldThrowAnything();
               } catch (IKnowWhatToDoWithThisException e) {
                 return handle(e);
               } catch (Throwable t) {
                 throw Throwables.propagate(t);
               }
             }

      Parameters:
        `throwable` - the Throwable to propagate
      Returns:
        nothing will ever be returned; this return type is only for your convenience, as illustrated in the example above

    - #### getRootCause

          @CheckReturnValue
          public static java.lang.Throwable getRootCause(java.lang.Throwable throwable)

      Returns the innermost cause of `throwable`. The first throwable in a chain provides context from when the error or exception was initially detected. Example usage:

             assertEquals("Unable to assign a customer id", Throwables.getRootCause(e).getMessage());

    - #### getCausalChain

          @Beta
          @CheckReturnValue
          public static java.util.List<java.lang.Throwable> getCausalChain(java.lang.Throwable throwable)

      Gets a `Throwable` cause chain as a list. The first entry in the list will be `throwable` followed by its cause hierarchy. Note that this is a snapshot of the cause chain and will not reflect any subsequent changes to the cause chain.

      Here's an example of how it can be used to find specific types of exceptions in the cause chain:

           Iterables.filter(Throwables.getCausalChain(e), IOException.class));

      Parameters:
        `throwable` - the non-null `Throwable` to extract causes from
      Returns:
        an unmodifiable list containing the cause chain starting with `throwable`

    - #### getStackTraceAsString

          @CheckReturnValue
          public static java.lang.String getStackTraceAsString(java.lang.Throwable throwable)

      Returns a string containing the result of `toString()`, followed by the full, recursive stack trace of `throwable`. Note that you probably should not be parsing the resulting string; if you need programmatic access to the stack frames, you can call `Throwable.getStackTrace()`.

    - #### lazyStackTrace

          @Beta
          @CheckReturnValue
          public static java.util.List<java.lang.StackTraceElement> lazyStackTrace(java.lang.Throwable throwable)

      Returns the stack trace of `throwable`, possibly providing slower iteration over the full trace but faster iteration over parts of the trace. Here, "slower" and "faster" are defined in comparison to the normal way to access the stack trace, `throwable.getStackTrace()`. Note, however, that this method's special implementation is not available for all platforms and configurations. If that implementation is unavailable, this method falls back to `getStackTrace`. Callers that require the special implementation can check its availability with `lazyStackTraceIsLazy()`.

      The expected (but not guaranteed) performance of the special implementation differs from `getStackTrace` in one main way: The `lazyStackTrace` call itself returns quickly by delaying the per-stack-frame work until each element is accessed. Roughly speaking:

      - `getStackTrace` takes `stackSize` time to return but then negligible time to retrieve each element of the returned list.
      - `lazyStackTrace` takes negligible time to return but then `1/stackSize` time to retrieve each element of the returned list (probably slightly more than `1/stackSize`).

      Note: The special implementation does not respect calls to `throwable.setStackTrace`. Instead, it always reflects the original stack trace from the exception's creation.

      Since:
        19.0

    - #### lazyStackTraceIsLazy

          @Beta
          @CheckReturnValue
          public static boolean lazyStackTraceIsLazy()

      Returns whether `lazyStackTrace(java.lang.Throwable)` will use the special implementation described in its documentation.
      Since:
        19.0