Class Throwables
- java.lang.Object
-
- com.google.common.base.Throwables
-
@GwtCompatible(emulated=true) public final class Throwables extends java.lang.Object
Static utility methods pertaining to instances ofThrowable
.See the Guava User Guide entry on Throwables.
- Since:
- 1.0
-
-
Field Summary
Fields Modifier and Type Field 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 reflectionprivate 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
-
Constructor Summary
Constructors Modifier Constructor Description private
Throwables()
-
Method Summary
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static java.util.List<java.lang.Throwable>
getCausalChain(java.lang.Throwable throwable)
Gets aThrowable
cause chain as a list.static <X extends java.lang.Throwable>
XgetCauseAs(java.lang.Throwable throwable, java.lang.Class<X> expectedCauseType)
Returnsthrowable
's cause, cast toexpectedCauseType
.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 ofthrowable
.private static java.lang.reflect.Method
getSizeMethod()
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 oftoString()
, followed by the full, recursive stack trace ofthrowable
.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)
Returns the stack trace ofthrowable
, possibly providing slower iteration over the full trace but faster iteration over parts of the trace.static boolean
lazyStackTraceIsLazy()
Returns whetherlazyStackTrace(java.lang.Throwable)
will use the special implementation described in its documentation.static java.lang.RuntimeException
propagate(java.lang.Throwable throwable)
Deprecated.Usethrow e
orthrow new RuntimeException(e)
directly, or use a combination ofthrowIfUnchecked(java.lang.Throwable)
andthrow new RuntimeException(e)
.static <X extends java.lang.Throwable>
voidpropagateIfInstanceOf(java.lang.Throwable throwable, java.lang.Class<X> declaredType)
Deprecated.UsethrowIfInstanceOf(java.lang.Throwable, java.lang.Class<X>)
, which has the same behavior but rejectsnull
.static void
propagateIfPossible(java.lang.Throwable throwable)
Deprecated.UsethrowIfUnchecked(java.lang.Throwable)
, which has the same behavior but rejectsnull
.static <X extends java.lang.Throwable>
voidpropagateIfPossible(java.lang.Throwable throwable, java.lang.Class<X> declaredType)
Propagatesthrowable
exactly as-is, if and only if it is an instance ofRuntimeException
,Error
, ordeclaredType
.static <X1 extends java.lang.Throwable,X2 extends java.lang.Throwable>
voidpropagateIfPossible(java.lang.Throwable throwable, java.lang.Class<X1> declaredType1, java.lang.Class<X2> declaredType2)
Propagatesthrowable
exactly as-is, if and only if it is an instance ofRuntimeException
,Error
,declaredType1
, ordeclaredType2
.static <X extends java.lang.Throwable>
voidthrowIfInstanceOf(java.lang.Throwable throwable, java.lang.Class<X> declaredType)
Throwsthrowable
if it is an instance ofdeclaredType
.static void
throwIfUnchecked(java.lang.Throwable throwable)
Throwsthrowable
if it is aRuntimeException
orError
.
-
-
-
Field Detail
-
JAVA_LANG_ACCESS_CLASSNAME
@GwtIncompatible private static final java.lang.String JAVA_LANG_ACCESS_CLASSNAME
JavaLangAccess class name to load using reflection- See Also:
- Constant Field Values
-
SHARED_SECRETS_CLASSNAME
@GwtIncompatible static final java.lang.String SHARED_SECRETS_CLASSNAME
SharedSecrets class name to load using reflection- See Also:
- Constant Field Values
-
jla
@GwtIncompatible private static final java.lang.Object jla
Access to some fancy internal JVM internals.
-
getStackTraceElementMethod
@GwtIncompatible private static final java.lang.reflect.Method getStackTraceElementMethod
The "getStackTraceElementMethod" method, only available on some JDKs so we use reflection to find it when available. When this is null, use the slow way.
-
getStackTraceDepthMethod
@GwtIncompatible private static final java.lang.reflect.Method getStackTraceDepthMethod
The "getStackTraceDepth" method, only available on some JDKs so we use reflection to find it when available. When this is null, use the slow way.
-
-
Method Detail
-
throwIfInstanceOf
@GwtIncompatible public static <X extends java.lang.Throwable> void throwIfInstanceOf(java.lang.Throwable throwable, java.lang.Class<X> declaredType) throws X extends java.lang.Throwable
Throwsthrowable
if it is an instance ofdeclaredType
. 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 java.lang.Throwable
- Since:
- 20.0
-
propagateIfInstanceOf
@Deprecated @GwtIncompatible public static <X extends java.lang.Throwable> void propagateIfInstanceOf(java.lang.Throwable throwable, java.lang.Class<X> declaredType) throws X extends java.lang.Throwable
Deprecated.UsethrowIfInstanceOf(java.lang.Throwable, java.lang.Class<X>)
, which has the same behavior but rejectsnull
.Propagatesthrowable
exactly as-is, if and only if it is an instance ofdeclaredType
. 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 java.lang.Throwable
-
throwIfUnchecked
public static void throwIfUnchecked(java.lang.Throwable throwable)
Throwsthrowable
if it is aRuntimeException
orError
. 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
@Deprecated @GwtIncompatible public static void propagateIfPossible(java.lang.Throwable throwable)
Deprecated.UsethrowIfUnchecked(java.lang.Throwable)
, which has the same behavior but rejectsnull
.Propagatesthrowable
exactly as-is, if and only if it is an instance ofRuntimeException
orError
. 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 java.lang.Throwable> void propagateIfPossible(java.lang.Throwable throwable, java.lang.Class<X> declaredType) throws X extends java.lang.Throwable
Propagatesthrowable
exactly as-is, if and only if it is an instance ofRuntimeException
,Error
, ordeclaredType
. 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 propagatedeclaredType
- the single checked exception type declared by the calling method- Throws:
X extends java.lang.Throwable
-
propagateIfPossible
@GwtIncompatible public static <X1 extends java.lang.Throwable,X2 extends java.lang.Throwable> void propagateIfPossible(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
Propagatesthrowable
exactly as-is, if and only if it is an instance ofRuntimeException
,Error
,declaredType1
, ordeclaredType2
. 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 inpropagateIfPossible(Throwable, Class)
.- Parameters:
throwable
- the Throwable to possibly propagatedeclaredType1
- any checked exception type declared by the calling methoddeclaredType2
- any other checked exception type declared by the calling method- Throws:
X1 extends java.lang.Throwable
-
propagate
@GwtIncompatible @Deprecated public static java.lang.RuntimeException propagate(java.lang.Throwable throwable)
Deprecated.Usethrow e
orthrow new RuntimeException(e)
directly, or use a combination ofthrowIfUnchecked(java.lang.Throwable)
andthrow new RuntimeException(e)
. For background on the deprecation, read Why we deprecatedThrowables.propagate
.Propagatesthrowable
as-is if it is an instance ofRuntimeException
orError
, or else as a last resort, wraps it in aRuntimeException
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 java.lang.Throwable getRootCause(java.lang.Throwable throwable)
Returns the innermost cause ofthrowable
. 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:
java.lang.IllegalArgumentException
- if there is a loop in the causal chain
-
getCausalChain
@Beta public static java.util.List<java.lang.Throwable> getCausalChain(java.lang.Throwable throwable)
Gets aThrowable
cause chain as a list. The first entry in the list will bethrowable
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-nullThrowable
to extract causes from- Returns:
- an unmodifiable list containing the cause chain starting with
throwable
- Throws:
java.lang.IllegalArgumentException
- if there is a loop in the causal chain
-
getCauseAs
@Beta @GwtIncompatible public static <X extends java.lang.Throwable> X getCauseAs(java.lang.Throwable throwable, java.lang.Class<X> expectedCauseType)
Returnsthrowable
's cause, cast toexpectedCauseType
.Prefer this method instead of manually casting an exception's cause. For example,
(IOException) e.getCause()
throws aClassCastException
that discards the original exceptione
if the cause is not anIOException
, butThrowables.getCauseAs(e, IOException.class)
keepse
as theClassCastException
's cause.- Throws:
java.lang.ClassCastException
- if the cause cannot be cast to the expected type. TheClassCastException
's cause isthrowable
.- Since:
- 22.0
-
getStackTraceAsString
@GwtIncompatible public static java.lang.String getStackTraceAsString(java.lang.Throwable throwable)
Returns a string containing the result oftoString()
, followed by the full, recursive stack trace ofthrowable
. Note that you probably should not be parsing the resulting string; if you need programmatic access to the stack frames, you can callThrowable.getStackTrace()
.
-
lazyStackTrace
@Beta @GwtIncompatible public static java.util.List<java.lang.StackTraceElement> lazyStackTrace(java.lang.Throwable throwable)
Returns the stack trace ofthrowable
, 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 togetStackTrace
. Callers that require the special implementation can check its availability withlazyStackTraceIsLazy()
.The expected (but not guaranteed) performance of the special implementation differs from
getStackTrace
in one main way: ThelazyStackTrace
call itself returns quickly by delaying the per-stack-frame work until each element is accessed. Roughly speaking:getStackTrace
takesstackSize
time to return but then negligible time to retrieve each element of the returned list.lazyStackTrace
takes negligible time to return but then1/stackSize
time to retrieve each element of the returned list (probably slightly more than1/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 @GwtIncompatible public static boolean lazyStackTraceIsLazy()
Returns whetherlazyStackTrace(java.lang.Throwable)
will use the special implementation described in its documentation.- Since:
- 19.0
-
jlaStackTrace
@GwtIncompatible private static java.util.List<java.lang.StackTraceElement> jlaStackTrace(java.lang.Throwable t)
-
invokeAccessibleNonThrowingMethod
@GwtIncompatible private static java.lang.Object invokeAccessibleNonThrowingMethod(java.lang.reflect.Method method, java.lang.Object receiver, java.lang.Object... params)
-
getJLA
@GwtIncompatible private static java.lang.Object getJLA()
Returns the JavaLangAccess class that is present in all Sun JDKs. It is not allowed in AppEngine, and not present in non-Sun JDKs.
-
getGetMethod
@GwtIncompatible 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).
-
getSizeMethod
@GwtIncompatible private static java.lang.reflect.Method getSizeMethod()
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). Tries to test methodsun.misc.JavaLangAccess#getStackTraceDepth(Throwable)
getStackTraceDepth} prior to return it (might fail some JDKs).See Throwables#lazyStackTrace throws UnsupportedOperationException.
-
getJlaMethod
@GwtIncompatible private static java.lang.reflect.Method getJlaMethod(java.lang.String name, java.lang.Class<?>... parameterTypes) throws java.lang.ThreadDeath
- Throws:
java.lang.ThreadDeath
-
-