public final class Throwables
extends java.lang.Object
Throwable
.
See the Guava User Guide entry on Throwables.
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> |
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> |
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> |
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 . |
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
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); }
X extends java.lang.Throwable
public static void propagateIfPossible(@Nullable java.lang.Throwable throwable)
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); }
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
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); }
throwable
- the Throwable to possibly propagatedeclaredType
- the single checked exception type declared by the calling methodX extends java.lang.Throwable
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
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)
.throwable
- the Throwable to possibly propagatedeclaredType1
- any checked exception type declared by the calling methoddeclaredType2
- any other checked exception type declared by the calling methodX1 extends java.lang.Throwable
public static java.lang.RuntimeException propagate(java.lang.Throwable throwable)
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); } }
throwable
- the Throwable to propagate@CheckReturnValue public static java.lang.Throwable getRootCause(java.lang.Throwable throwable)
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());
@Beta @CheckReturnValue public static java.util.List<java.lang.Throwable> getCausalChain(java.lang.Throwable throwable)
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));
throwable
- the non-null Throwable
to extract causes fromthrowable
@CheckReturnValue public static java.lang.String getStackTraceAsString(java.lang.Throwable throwable)
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()
.@Beta @CheckReturnValue public static java.util.List<java.lang.StackTraceElement> lazyStackTrace(java.lang.Throwable throwable)
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.
@Beta @CheckReturnValue public static boolean lazyStackTraceIsLazy()
lazyStackTrace(java.lang.Throwable)
will use the special implementation described in its
documentation.