com.google.common.base
Class Throwables

java.lang.Object
  extended by com.google.common.base.Throwables

public final class Throwables
extends Object

Static utility methods pertaining to instances of Throwable.

Since:
1.0
Author:
Kevin Bourrillion, Ben Yu

Method Summary
static List<Throwable> getCausalChain(Throwable throwable)
          Gets a Throwable cause chain as a list.
static Throwable getRootCause(Throwable throwable)
          Returns the innermost cause of throwable.
static String getStackTraceAsString(Throwable throwable)
          Returns a string containing the result of toString(), followed by the full, recursive stack trace of throwable.
static RuntimeException propagate(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 Throwable>
void
propagateIfInstanceOf(Throwable throwable, Class<X> declaredType)
          Propagates throwable exactly as-is, if and only if it is an instance of declaredType.
static void propagateIfPossible(Throwable throwable)
          Propagates throwable exactly as-is, if and only if it is an instance of RuntimeException or Error.
static
<X extends Throwable>
void
propagateIfPossible(Throwable throwable, Class<X> declaredType)
          Propagates throwable exactly as-is, if and only if it is an instance of RuntimeException, Error, or declaredType.
static
<X1 extends Throwable,X2 extends Throwable>
void
propagateIfPossible(Throwable throwable, Class<X1> declaredType1, Class<X2> declaredType2)
          Propagates throwable exactly as-is, if and only if it is an instance of RuntimeException, Error, declaredType1, or declaredType2.
static Exception throwCause(Exception exception, boolean combineStackTraces)
          Deprecated. For throwCause(e, false), use propagateIfPossible(e.getCause(), Exception.class); throw e;. For throwCause(e, true), there is no exact equivalent. Callers are encouraged to consider whether the cause contains all useful stack trace context. (It usually does if it comes from within the thread, e.g., for an InvocationTargetException, and it usually does not otherwise, e.g., for an ExecutionException.) If the cause contains all useful context, consider throwing it directly if your method signature permits or wrapping it in an appropriate exception if not. If the cause does not contain all useful context, consider propagating the wrapper exception or rewrapping the cause in an appropriate exception. For the particular case of exceptions thrown by Future.get, consider Futures.get(java.util.concurrent.Future, Class). This method will be removed from Guava in Guava release 11.0.
 
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 Throwable> void propagateIfInstanceOf(@Nullable
                                                               Throwable throwable,
                                                               Class<X> declaredType)
                                  throws X extends 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 Throwable

propagateIfPossible

public static void propagateIfPossible(@Nullable
                                       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 Throwable> void propagateIfPossible(@Nullable
                                                             Throwable throwable,
                                                             Class<X> declaredType)
                                throws X extends 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 Throwable

propagateIfPossible

public static <X1 extends Throwable,X2 extends Throwable> void propagateIfPossible(@Nullable
                                                                                   Throwable throwable,
                                                                                   Class<X1> declaredType1,
                                                                                   Class<X2> declaredType2)
                                throws X1 extends Throwable,
                                       X2 extends 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 Throwable

propagate

public static RuntimeException propagate(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 Throwable getRootCause(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 List<Throwable> getCausalChain(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 String getStackTraceAsString(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().


throwCause

@Beta
@Deprecated
public static Exception throwCause(Exception exception,
                                                   boolean combineStackTraces)
                            throws Exception
Deprecated. For throwCause(e, false), use propagateIfPossible(e.getCause(), Exception.class); throw e;. For throwCause(e, true), there is no exact equivalent. Callers are encouraged to consider whether the cause contains all useful stack trace context. (It usually does if it comes from within the thread, e.g., for an InvocationTargetException, and it usually does not otherwise, e.g., for an ExecutionException.) If the cause contains all useful context, consider throwing it directly if your method signature permits or wrapping it in an appropriate exception if not. If the cause does not contain all useful context, consider propagating the wrapper exception or rewrapping the cause in an appropriate exception. For the particular case of exceptions thrown by Future.get, consider Futures.get(java.util.concurrent.Future, Class). This method will be removed from Guava in Guava release 11.0.

Rethrows the cause exception of a given throwable, discarding the original throwable. Optionally, the stack frames of the cause and the outer exception are combined and the stack trace of the cause is set to this combined trace. If there is no cause the original exception is rethrown unchanged in all cases.

Parameters:
exception - the exception from which to extract the cause
combineStackTraces - if true the stack trace of the cause will be replaced by the concatenation of the trace from the exception and the trace from the cause.
Throws:
Exception


Copyright © 2010-2011. All Rights Reserved.