public final class Throwables extends Object
Throwable
.
See the Guava User Guide entry on Throwables.
Modifier and Type | Method and Description |
---|---|
static List |
getCausalChain(Throwable
Gets a
Throwable cause chain as a list.
|
static Throwable |
getRootCause(Throwable
Returns the innermost cause of
throwable .
|
static String |
getStackTraceAsString(Throwable
Returns a string containing the result of
toString() , followed by the full, recursive stack trace of
throwable .
|
static List |
lazyStackTrace(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 RuntimeException |
propagate(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 Throwable |
propagateIfInstanceOf(Throwable
Propagates
throwable exactly as-is, if and only if it is an instance of
declaredType .
|
static void |
propagateIfPossible(Throwable
|
static <X extends Throwable |
propagateIfPossible(Throwable
Propagates
throwable exactly as-is, if and only if it is an instance of
RuntimeException ,
Error , or
declaredType .
|
static <X1 extends Throwable |
propagateIfPossible(Throwable
Propagates
throwable exactly as-is, if and only if it is an instance of
RuntimeException ,
Error ,
declaredType1 , or
declaredType2 .
|
public static <X extends Throwable> void propagateIfInstanceOf(Throwable throwable, Class <X> declaredType) throws X extends 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 Throwable
public static void propagateIfPossible(Throwablethrowable)
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 Throwable> void propagateIfPossible(Throwable throwable, Class <X> declaredType) throws X extends 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 propagate
declaredType
- the single checked exception type declared by the calling method
X extends Throwable
public static <X1 extends Throwable,X2 extends Throwable > void propagateIfPossible(Throwable throwable, Class <X1> declaredType1, Class <X2> declaredType2) throws X1 extends Throwable, X2 extends 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 propagate
declaredType1
- any checked exception type declared by the calling method
declaredType2
- any other checked exception type declared by the calling method
X1 extends Throwable
public static RuntimeExceptionpropagate(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
public static ThrowablegetRootCause(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 public static List<Throwable > getCausalChain(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 from
throwable
public static StringgetStackTraceAsString(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 public static List<StackTraceElement > lazyStackTrace(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 public static boolean lazyStackTraceIsLazy()
lazyStackTrace(java.lang.Throwable)
will use the special implementation described in its documentation.