Package com.google.common.base

Class Throwables

  • 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

    • Method Summary

      All Methods Static Methods Concrete 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 java.lang.Throwable getRootCause​(java.lang.Throwable throwable)
      Returns the innermost cause of throwable.
      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.
      static java.lang.RuntimeException propagate​(java.lang.Throwable 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 then propagates.
      static <X extends java.lang.Throwable>
      void      		 propagateIfInstanceOf​(java.lang.Throwable throwable, java.lang.Class<X> declaredType)
      Propagates throwable exactly as-is, if and only if it is an instance of declaredType.
      static void propagateIfPossible​(java.lang.Throwable throwable)
      Propagates throwable exactly as-is, if and only if it is an instance of RuntimeException or Error.
      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.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • propagateIfInstanceOf

        public static <X extends java.lang.Throwable> void propagateIfInstanceOf​(@Nullable
                                                                         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 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

      • propagateIfPossible

        public static void propagateIfPossible​(@Nullable
                                       java.lang.Throwable throwable)
        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

        public static <X extends java.lang.Throwable> void propagateIfPossible​(@Nullable
                                                                       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

        public static <X1 extends java.lang.Throwable,​X2 extends java.lang.Throwable> void propagateIfPossible​(@Nullable
                                                                                                             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

        public static java.lang.RuntimeException propagate​(java.lang.Throwable 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 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);
        }
 }
        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());

      • 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

      • getStackTraceAsString

        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().