Package com.google.common.base

Class Throwables

  • @GwtCompatible(emulated=true)
public final class Throwables
extends java.lang.Object
    Static utility methods pertaining to instances of Throwable.

    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 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

    • 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 a Throwable cause chain as a list.
      static <X extends java.lang.Throwable>
      X      		 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()
      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)
      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)
      Deprecated.
      Use throw e or throw new RuntimeException(e) directly, or use a combination of throwIfUnchecked(java.lang.Throwable) and throw new RuntimeException(e).
      static <X extends java.lang.Throwable>
      void      		 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>
      void      		 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>
      void      		 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>
      void      		 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.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • 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

      • 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.

    • Constructor Detail

      • Throwables

        private Throwables()

    • 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
        Throws 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);
 }
        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.
        Use throwIfInstanceOf(java.lang.Throwable, java.lang.Class<X>), which has the same behavior but rejects null.
        Propagates 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);
 }
        Throws:
        X extends java.lang.Throwable

      • throwIfUnchecked

        public static void throwIfUnchecked​(java.lang.Throwable throwable)
        Throws 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);
 }
        Since:
        20.0

      • propagateIfPossible

        @Deprecated
@GwtIncompatible
public static void propagateIfPossible​(java.lang.Throwable throwable)
        Deprecated.
        Use throwIfUnchecked(java.lang.Throwable), which has the same behavior but rejects null.
        Propagates 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);
 }

      • 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
        Propagates 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);
 }
        Parameters:
        throwable - the Throwable to possibly propagate
        declaredType - 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
        Propagates 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).
        Parameters:
        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
        Throws:
        X1 extends java.lang.Throwable

      • propagate

        @GwtIncompatible
@Deprecated
public 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.
        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.

        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 of 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());
        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 a 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));
        Parameters:
        throwable - the non-null Throwable 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)
        Returns 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.

        Throws:
        java.lang.ClassCastException - if the cause cannot be cast to the expected type. The ClassCastException's cause is throwable.
        Since:
        22.0

      • getStackTraceAsString

        @GwtIncompatible
public 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. 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().

      • lazyStackTrace

        @Beta
@GwtIncompatible
public 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. 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.

        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 method sun.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