public final class Throwables
extends java.lang.Object
Throwable
.
See the Guava User Guide entry on Throwables.
Modifier and Type | Field and Description |
---|---|
private static java.lang.reflect.Method |
getStackTraceDepthMethod
The "getStackTraceDepth" method, only available on some JDKs so we use reflection to find it
when available.
|
private static java.lang.reflect.Method |
getStackTraceElementMethod
The "getStackTraceElementMethod" method, only available on some JDKs so we use reflection to
find it when available.
|
private static java.lang.String |
JAVA_LANG_ACCESS_CLASSNAME
JavaLangAccess class name to load using reflection
|
private static java.lang.Object |
jla
Access to some fancy internal JVM internals.
|
(package private) static java.lang.String |
SHARED_SECRETS_CLASSNAME
SharedSecrets class name to load using reflection
|
Modifier | Constructor and Description |
---|---|
private |
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 <X extends java.lang.Throwable> |
getCauseAs(java.lang.Throwable throwable,
java.lang.Class<X> expectedCauseType)
Returns
throwable 's cause, cast to expectedCauseType . |
private static java.lang.reflect.Method |
getGetMethod()
Returns the Method that can be used to resolve an individual StackTraceElement, or null if that
method cannot be found (it is only to be found in fairly recent JDKs).
|
private static java.lang.Object |
getJLA()
Returns the JavaLangAccess class that is present in all Sun JDKs.
|
private static java.lang.reflect.Method |
getJlaMethod(java.lang.String name,
java.lang.Class<?>... parameterTypes) |
static java.lang.Throwable |
getRootCause(java.lang.Throwable throwable)
Returns the innermost cause of
throwable . |
private static java.lang.reflect.Method |
getSizeMethod(java.lang.Object jla)
Returns the Method that can be used to return the size of a stack, or null if that method
cannot be found (it is only to be found in fairly recent JDKs).
|
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 . |
private static java.lang.Object |
invokeAccessibleNonThrowingMethod(java.lang.reflect.Method method,
java.lang.Object receiver,
java.lang.Object... params) |
private static java.util.List<java.lang.StackTraceElement> |
jlaStackTrace(java.lang.Throwable t) |
static java.util.List<java.lang.StackTraceElement> |
lazyStackTrace(java.lang.Throwable throwable)
Deprecated.
This method is equivalent to
Throwable.getStackTrace() on JDK versions past
JDK 8 and on all Android versions. Use Throwable.getStackTrace() directly, or where
possible use the java.lang.StackWalker.walk method introduced in JDK 9. |
static boolean |
lazyStackTraceIsLazy()
Deprecated.
This method always returns false on JDK versions past JDK 8 and on all Android
versions.
|
static java.lang.RuntimeException |
propagate(java.lang.Throwable 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 Why we deprecated
Throwables.propagate . |
static <X extends java.lang.Throwable> |
propagateIfInstanceOf(java.lang.Throwable throwable,
java.lang.Class<X> declaredType)
Deprecated.
Use
throwIfInstanceOf(java.lang.Throwable, java.lang.Class<X>) , which has the same behavior but rejects null . |
static void |
propagateIfPossible(java.lang.Throwable throwable)
Deprecated.
Use
throwIfUnchecked(java.lang.Throwable) , which has the same behavior but rejects null . |
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 . |
static <X extends java.lang.Throwable> |
throwIfInstanceOf(java.lang.Throwable throwable,
java.lang.Class<X> declaredType)
Throws
throwable if it is an instance of declaredType . |
static void |
throwIfUnchecked(java.lang.Throwable throwable)
Throws
throwable if it is a RuntimeException or Error . |
private static final java.lang.String JAVA_LANG_ACCESS_CLASSNAME
static final java.lang.String SHARED_SECRETS_CLASSNAME
@CheckForNull private static final java.lang.Object jla
@CheckForNull private static final java.lang.reflect.Method getStackTraceElementMethod
@CheckForNull private static final java.lang.reflect.Method getStackTraceDepthMethod
public static <X extends java.lang.Throwable> void throwIfInstanceOf(java.lang.Throwable throwable, java.lang.Class<X> declaredType) throws X extends java.lang.Throwable
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); }
X extends java.lang.Throwable
@Deprecated public static <X extends java.lang.Throwable> void propagateIfInstanceOf(@CheckForNull java.lang.Throwable throwable, java.lang.Class<X> declaredType) throws X extends java.lang.Throwable
throwIfInstanceOf(java.lang.Throwable, java.lang.Class<X>)
, which has the same behavior but rejects null
.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 throwIfUnchecked(java.lang.Throwable throwable)
throwable
if it is a RuntimeException
or Error
. Example usage:
for (Foo foo : foos) { try { foo.bar(); } catch (RuntimeException | Error t) { failure = t; } } if (failure != null) { throwIfUnchecked(failure); throw new AssertionError(failure); }
@Deprecated public static void propagateIfPossible(@CheckForNull java.lang.Throwable throwable)
throwIfUnchecked(java.lang.Throwable)
, which has the same behavior but rejects null
.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(@CheckForNull 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(@CheckForNull 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
@Deprecated public static java.lang.RuntimeException propagate(java.lang.Throwable throwable)
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 Why we deprecated
Throwables.propagate
.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 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); } }
throwable
- the Throwable to propagatepublic 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());
java.lang.IllegalArgumentException
- if there is a loop in the causal chainpublic 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
java.lang.IllegalArgumentException
- if there is a loop in the causal chain@CheckForNull public static <X extends java.lang.Throwable> X getCauseAs(java.lang.Throwable throwable, java.lang.Class<X> expectedCauseType)
throwable
's cause, cast to expectedCauseType
.
Prefer this method instead of manually casting an exception's cause. For example, (IOException) e.getCause()
throws a ClassCastException
that discards the original
exception e
if the cause is not an IOException
, but Throwables.getCauseAs(e, IOException.class)
keeps e
as the ClassCastException
's cause.
java.lang.ClassCastException
- if the cause cannot be cast to the expected type. The ClassCastException
's cause is throwable
.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()
.@Deprecated public static java.util.List<java.lang.StackTraceElement> lazyStackTrace(java.lang.Throwable throwable)
Throwable.getStackTrace()
on JDK versions past
JDK 8 and on all Android versions. Use Throwable.getStackTrace()
directly, or where
possible use the java.lang.StackWalker.walk
method introduced in JDK 9.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.
@Deprecated public static boolean lazyStackTraceIsLazy()
lazyStackTrace(java.lang.Throwable)
will use the special implementation described in its
documentation.private static java.util.List<java.lang.StackTraceElement> jlaStackTrace(java.lang.Throwable t)
private static java.lang.Object invokeAccessibleNonThrowingMethod(java.lang.reflect.Method method, java.lang.Object receiver, java.lang.Object... params)
@CheckForNull private static java.lang.Object getJLA()
@CheckForNull private static java.lang.reflect.Method getGetMethod()
@CheckForNull private static java.lang.reflect.Method getSizeMethod(java.lang.Object jla)
JavaLangAccess.getStackTraceDepth(Throwable)
getStackTraceDepth} prior to return it
(might fail some JDKs).
See Throwables#lazyStackTrace throws UnsupportedOperationException.
@CheckForNull private static java.lang.reflect.Method getJlaMethod(java.lang.String name, java.lang.Class<?>... parameterTypes) throws java.lang.ThreadDeath
java.lang.ThreadDeath