Class Throwables
Throwable.
See the Guava User Guide entry on Throwables.
- Since:
- 1.0
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final MethodThe "getStackTraceDepth" method, only available on some JDKs so we use reflection to find it when available.private static final MethodThe "getStackTraceElementMethod" method, only available on some JDKs so we use reflection to find it when available.private static final StringJavaLangAccess class name to load using reflectionprivate static final ObjectAccess to some fancy internal JVM internals.(package private) static final StringSharedSecrets class name to load using reflection -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptiongetCausalChain(Throwable throwable) Gets aThrowablecause chain as a list.static <X extends Throwable>
XgetCauseAs(Throwable throwable, Class<X> expectedCauseType) Returnsthrowable's cause, cast toexpectedCauseType.private static MethodReturns 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 ObjectgetJLA()Returns the JavaLangAccess class that is present in all Sun JDKs.private static MethodgetJlaMethod(String name, Class<?>... parameterTypes) static ThrowablegetRootCause(Throwable throwable) Returns the innermost cause ofthrowable.private static MethodgetSizeMethod(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 StringgetStackTraceAsString(Throwable throwable) Returns a string containing the result oftoString(), followed by the full, recursive stack trace ofthrowable.private static ObjectinvokeAccessibleNonThrowingMethod(Method method, Object receiver, Object... params) private static List<StackTraceElement>static List<StackTraceElement>lazyStackTrace(Throwable throwable) Deprecated.static booleanDeprecated.This method always returns false on JDK versions past JDK 8 and on all Android versions.static RuntimeExceptionDeprecated.To preserve behavior, usethrow eorthrow new RuntimeException(e)directly, or use a combination ofthrowIfUnchecked(java.lang.Throwable)andthrow new RuntimeException(e).static <X extends Throwable>
voidpropagateIfInstanceOf(Throwable throwable, Class<X> declaredType) Deprecated.UsethrowIfInstanceOf(java.lang.Throwable, java.lang.Class<X>), which has the same behavior but rejectsnull.static voidpropagateIfPossible(Throwable throwable) Deprecated.UsethrowIfUnchecked(java.lang.Throwable), which has the same behavior but rejectsnull.static <X extends Throwable>
voidpropagateIfPossible(Throwable throwable, Class<X> declaredType) Propagatesthrowableexactly as-is, if and only if it is an instance ofRuntimeException,Error, ordeclaredType.propagateIfPossible(Throwable throwable, Class<X1> declaredType1, Class<X2> declaredType2) Propagatesthrowableexactly as-is, if and only if it is an instance ofRuntimeException,Error,declaredType1, ordeclaredType2.static <X extends Throwable>
voidthrowIfInstanceOf(Throwable throwable, Class<X> declaredType) Throwsthrowableif it is an instance ofdeclaredType.static voidthrowIfUnchecked(Throwable throwable)
-
Field Details
-
JAVA_LANG_ACCESS_CLASSNAME
JavaLangAccess class name to load using reflection- See Also:
-
SHARED_SECRETS_CLASSNAME
SharedSecrets class name to load using reflection- See Also:
-
jla
Access to some fancy internal JVM internals. -
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
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.
-
-
Constructor Details
-
Throwables
private Throwables()
-
-
Method Details
-
throwIfInstanceOf
public static <X extends Throwable> void throwIfInstanceOf(Throwable throwable, Class<X> declaredType) throws X Throwsthrowableif 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 Throwable- Since:
- 20.0
-
propagateIfInstanceOf
@Deprecated public static <X extends Throwable> void propagateIfInstanceOf(@CheckForNull Throwable throwable, Class<X> declaredType) throws X Deprecated.UsethrowIfInstanceOf(java.lang.Throwable, java.lang.Class<X>), which has the same behavior but rejectsnull.Propagatesthrowableexactly 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 Throwable
-
throwIfUnchecked
Throwsthrowableif it is aRuntimeExceptionorError. 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.UsethrowIfUnchecked(java.lang.Throwable), which has the same behavior but rejectsnull. -
propagateIfPossible
public static <X extends Throwable> void propagateIfPossible(@CheckForNull Throwable throwable, Class<X> declaredType) throws X Propagatesthrowableexactly as-is, if and only if it is an instance ofRuntimeException,Error, ordeclaredType.Discouraged in favor of calling
throwIfInstanceOf(java.lang.Throwable, java.lang.Class<X>)andthrowIfUnchecked(java.lang.Throwable).- Parameters:
throwable- the Throwable to possibly propagatedeclaredType- the single checked exception type declared by the calling method- Throws:
X extends Throwable
-
propagateIfPossible
public static <X1 extends Throwable,X2 extends Throwable> void propagateIfPossible(@CheckForNull Throwable throwable, Class<X1> declaredType1, Class<X2> declaredType2) throws X1, X2 Propagatesthrowableexactly as-is, if and only if it is an instance ofRuntimeException,Error,declaredType1, ordeclaredType2.Discouraged in favor of calling
throwIfInstanceOf(java.lang.Throwable, java.lang.Class<X>)andthrowIfUnchecked(java.lang.Throwable). -
propagate
Deprecated.To preserve behavior, usethrow eorthrow new RuntimeException(e)directly, or use a combination ofthrowIfUnchecked(java.lang.Throwable)andthrow new RuntimeException(e). But consider whether users would be better off if your API threw a different type of exception. For background on the deprecation, read Why we deprecatedThrowables.propagate.Propagatesthrowableas-is if it is an instance ofRuntimeExceptionorError, or else as a last resort, wraps it in aRuntimeExceptionand then propagates.This method always throws an exception. The
RuntimeExceptionreturn 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
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:
IllegalArgumentException- if there is a loop in the causal chain
-
getCausalChain
Gets aThrowablecause chain as a list. The first entry in the list will bethrowablefollowed 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-nullThrowableto extract causes from- Returns:
- an unmodifiable list containing the cause chain starting with
throwable - Throws:
IllegalArgumentException- if there is a loop in the causal chain
-
getCauseAs
@CheckForNull public static <X extends Throwable> X getCauseAs(Throwable throwable, 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 aClassCastExceptionthat discards the original exceptioneif the cause is not anIOException, butThrowables.getCauseAs(e, IOException.class)keepseas theClassCastException's cause.- Throws:
ClassCastException- if the cause cannot be cast to the expected type. TheClassCastException's cause isthrowable.- Since:
- 22.0
-
getStackTraceAsString
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
Deprecated.This method is equivalent toThrowable.getStackTrace()on JDK versions past JDK 8 and on all Android versions. UseThrowable.getStackTrace()directly, or where possible use thejava.lang.StackWalker.walkmethod introduced in JDK 9.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
getStackTracein one main way: ThelazyStackTracecall itself returns quickly by delaying the per-stack-frame work until each element is accessed. Roughly speaking:getStackTracetakesstackSizetime to return but then negligible time to retrieve each element of the returned list.lazyStackTracetakes negligible time to return but then1/stackSizetime 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
Deprecated.This method always returns false on JDK versions past JDK 8 and on all Android versions.Returns whetherlazyStackTrace(java.lang.Throwable)will use the special implementation described in its documentation.- Since:
- 19.0
-
jlaStackTrace
-
invokeAccessibleNonThrowingMethod
-
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
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
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 methodgetStackTraceDepthprior to return it (might fail some JDKs).See Throwables#lazyStackTrace throws UnsupportedOperationException.
-
getJlaMethod
@CheckForNull private static Method getJlaMethod(String name, Class<?>... parameterTypes) throws ThreadDeath - Throws:
ThreadDeath
-
Throwable.getStackTrace()on JDK versions past JDK 8 and on all Android versions.