Package com.google.common.base

Class Throwables

com.google.common.base.Throwables

@GwtCompatible(emulated=true)
public final class Throwables
extends 

Static utility methods pertaining to instances of .

See the Guava User Guide entry on .

Since:

1.0

Author:

Kevin Bourrillion, Ben Yu

Method Summary

Modifier and Type	Method	Description
static <>	throwable)	Gets a Throwable cause chain as a list.
static <X extends > X	throwable, <X> expectedCauseType)	Returns throwable's cause, cast to expectedCauseType.
static	throwable)	Returns the innermost cause of throwable.
static	throwable)	Returns a string containing the result of , followed by the full, recursive stack trace of throwable.
static <>	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	throwable)	Deprecated. Use throw e or throw new RuntimeException(e) directly, or use a combination of throwIfUnchecked(java.lang.Throwable) and throw new RuntimeException(e).
static <X extends > void	throwable, <X> declaredType)	Deprecated. Use throwIfInstanceOf(java.lang.Throwable, java.lang.Class<X>), which has the same behavior but rejects null.
static void	throwable)	Deprecated. Use throwIfUnchecked(java.lang.Throwable), which has the same behavior but rejects null.
static <X extends > void	throwable, <X> declaredType)	Propagates throwable exactly as-is, if and only if it is an instance of , , or declaredType.
static <X1 extends ,X2 extends > void	throwable, <X1> declaredType1, <X2> declaredType2)	Propagates throwable exactly as-is, if and only if it is an instance of , , declaredType1, or declaredType2.
static <X extends > void	throwable, <X> declaredType)	Throws throwable if it is an instance of declaredType.
static void	throwable)	Throws throwable if it is a or .

Methods inherited from class java.lang.

, , , , , , , , , ,

Method Detail

throwIfInstanceOf

@GwtIncompatible
public static <X extends > void  throwable,
                                                           <X> declaredType)
                                                    throws X extends 

Throws throwable if it is an instance of declaredType. Example usage:

 for (Foo foo : foos) {
   try {
     foo.bar();
   } catch (BarException | RuntimeException | Error t) {
     failure = t;
   }
 }
 if (failure != null) {
   throwIfInstanceOf(failure, BarException.class);
   throwIfUnchecked(failure);
   throw new AssertionError(failure);
 }
 

Throws:

X extends

Since:

20.0

propagateIfInstanceOf

@GwtIncompatible
public static <X extends > void   throwable,
                                                               <X> declaredType)
                                                        throws X extends 

Deprecated.

Use throwIfInstanceOf(java.lang.Throwable, java.lang.Class<X>), which has the same behavior but rejects null.

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

throwIfUnchecked

public static void  throwable)

Throws throwable if it is a or . Example usage:

 for (Foo foo : foos) {
   try {
     foo.bar();
   } catch (RuntimeException | Error t) {
     failure = t;
   }
 }
 if (failure != null) {
   throwIfUnchecked(failure);
   throw new AssertionError(failure);
 }
 

Since:

20.0

propagateIfPossible

@GwtIncompatible
public static void   throwable)

Deprecated.

Use throwIfUnchecked(java.lang.Throwable), which has the same behavior but rejects null.

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

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

propagateIfPossible

@GwtIncompatible
public static <X extends > void   throwable,
                                                             <X> declaredType)
                                                      throws X extends 

Propagates throwable exactly as-is, if and only if it is an instance of , , 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

propagateIfPossible

@GwtIncompatible
public static <X1 extends ,X2 extends > void   throwable,
                                                                                         <X1> declaredType1,
                                                                                         <X2> declaredType2)
                                                                                  throws X1 extends ,
                                                                                         X2 extends 

Propagates throwable exactly as-is, if and only if it is an instance of , , 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

propagate

@GwtIncompatible

public static   throwable)

Deprecated.

Use throw e or throw new RuntimeException(e) directly, or use a combination of throwIfUnchecked(java.lang.Throwable) and throw new RuntimeException(e). For background on the deprecation, read .

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

This method always throws an exception. The RuntimeException return type allows client code to signal to the compiler that statements after the call are unreachable. 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

public static   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());
 

Throws:

- if there is a loop in the causal chain

getCausalChain

@Beta
public static <>  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

Throws:

- if there is a loop in the causal chain

getCauseAs

@Beta
@GwtIncompatible
public static <X extends > X  throwable,
                                                 <X> expectedCauseType)

Returns throwable's cause, cast to expectedCauseType.

Prefer this method instead of manually casting an exception's cause. For example, (IOException) e.getCause() throws a that discards the original exception e if the cause is not an , but Throwables.getCauseAs(e, IOException.class) keeps e as the 's cause.

Throws:

- if the cause cannot be cast to the expected type. The ClassCastException's cause is throwable.

Since:

22.0

getStackTraceAsString

@GwtIncompatible
public static   throwable)

Returns a string containing the result of , 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 .

lazyStackTrace

@Beta
@GwtIncompatible
public static <>  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, . 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 . Instead, it always reflects the original stack trace from the exception's creation.

Since:

19.0

lazyStackTraceIsLazy

@Beta
@GwtIncompatible
public static boolean lazyStackTraceIsLazy()

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

Since:

19.0