Method Detail

• propagateIfInstanceOf

  public static <X extends Throwable> void propagateIfInstanceOf(@Nullable
                                                 Throwable throwable,
                                                 Class<X> declaredType)
                                    throws X extends 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 Throwable

• propagateIfPossible

  public static void propagateIfPossible(@Nullable
                         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 Throwable> void propagateIfPossible(@Nullable
                                               Throwable throwable,
                                               Class<X> declaredType)
                                  throws X extends 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 Throwable

• propagateIfPossible

  public static <X1 extends Throwable,X2 extends Throwable> void propagateIfPossible(@Nullable
                                                                     Throwable throwable,
                                                                     Class<X1> declaredType1,
                                                                     Class<X2> declaredType2)
                                  throws X1 extends Throwable,
                                         X2 extends 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 Throwable

• propagate

  public static RuntimeException propagate(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 Throwable getRootCause(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 List<Throwable> getCausalChain(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 String getStackTraceAsString(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 List<StackTraceElement> lazyStackTrace(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