Open Source Repository

Home /guava/guava-10.0 | Repository Home


com/google/common/base/Throwables.java
/*
 * Copyright (C) 2007 The Guava Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.common.base;

import static com.google.common.base.Preconditions.checkNotNull;

import com.google.common.annotations.Beta;

import java.io.PrintWriter;
import java.io.StringWriter;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

import javax.annotation.Nullable;

/**
 * Static utility methods pertaining to instances of {@link Throwable}.
 *
 @author Kevin Bourrillion
 @author Ben Yu
 @since 1.0
 */
public final class Throwables {
  private Throwables() {}

  /**
   * Propagates {@code throwable} exactly as-is, if and only if it is an
   * instance of {@code declaredType}.  Example usage:
   <pre>
   *   try {
   *     someMethodThatCouldThrowAnything();
   *   } catch (IKnowWhatToDoWithThisException e) {
   *     handle(e);
   *   } catch (Throwable t) {
   *     Throwables.propagateIfInstanceOf(t, IOException.class);
   *     Throwables.propagateIfInstanceOf(t, SQLException.class);
   *     throw Throwables.propagate(t);
   *   }
   </pre>
   */
  public static <X extends Throwable> void propagateIfInstanceOf(
      @Nullable Throwable throwable, Class<X> declaredTypethrows {
    // Check for null is needed to avoid frequent JNI calls to isInstance().
    if (throwable != null && declaredType.isInstance(throwable)) {
      throw declaredType.cast(throwable);
    }
  }

  /**
   * Propagates {@code throwable} exactly as-is, if and only if it is an
   * instance of {@link RuntimeException} or {@link Error}.  Example usage:
   <pre>
   *   try {
   *     someMethodThatCouldThrowAnything();
   *   } catch (IKnowWhatToDoWithThisException e) {
   *     handle(e);
   *   } catch (Throwable t) {
   *     Throwables.propagateIfPossible(t);
   *     throw new RuntimeException("unexpected", t);
   *   }
   </pre>
   */
  public static void propagateIfPossible(@Nullable Throwable throwable) {
    propagateIfInstanceOf(throwable, Error.class);
    propagateIfInstanceOf(throwable, RuntimeException.class);
  }

  /**
   * Propagates {@code throwable} exactly as-is, if and only if it is an
   * instance of {@link RuntimeException}{@link Error}, or
   * {@code declaredType}. Example usage:
   <pre>
   *   try {
   *     someMethodThatCouldThrowAnything();
   *   } catch (IKnowWhatToDoWithThisException e) {
   *     handle(e);
   *   } catch (Throwable t) {
   *     Throwables.propagateIfPossible(t, OtherException.class);
   *     throw new RuntimeException("unexpected", t);
   *   }
   </pre>
   *
   @param throwable the Throwable to possibly propagate
   @param declaredType the single checked exception type declared by the
   *     calling method
   */
  public static <X extends Throwable> void propagateIfPossible(
      @Nullable Throwable throwable, Class<X> declaredTypethrows {
    propagateIfInstanceOf(throwable, declaredType);
    propagateIfPossible(throwable);
  }

  /**
   * Propagates {@code throwable} exactly as-is, if and only if it is an
   * instance of {@link RuntimeException}{@link Error}, {@code declaredType1},
   * or {@code 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 {@link
   * #propagateIfPossible(Throwable, Class)}.
   *
   @param throwable the Throwable to possibly propagate
   @param declaredType1 any checked exception type declared by the calling
   *     method
   @param declaredType2 any other checked exception type declared by the
   *     calling method
   */
  public static <X1 extends Throwable, X2 extends Throwable>
      void propagateIfPossible(@Nullable Throwable throwable,
          Class<X1> declaredType1, Class<X2> declaredType2throws X1, X2 {
    checkNotNull(declaredType2);
    propagateIfInstanceOf(throwable, declaredType1);
    propagateIfPossible(throwable, declaredType2);
  }

  /**
   * Propagates {@code throwable} as-is if it is an instance of
   {@link RuntimeException} or {@link Error}, or else as a last resort, wraps
   * it in a {@code RuntimeException} then propagates.
   <p>
   * This method always throws an exception. The {@code 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:
   <pre>
   *   T doSomething() {
   *     try {
   *       return someMethodThatCouldThrowAnything();
   *     } catch (IKnowWhatToDoWithThisException e) {
   *       return handle(e);
   *     } catch (Throwable t) {
   *       throw Throwables.propagate(t);
   *     }
   *   }
   </pre>
   *
   @param throwable the Throwable to propagate
   @return nothing will ever be returned; this return type is only for your
   *     convenience, as illustrated in the example above
   */
  public static RuntimeException propagate(Throwable throwable) {
    propagateIfPossible(checkNotNull(throwable));
    throw new RuntimeException(throwable);
  }

  /**
   * Returns the innermost cause of {@code throwable}. The first throwable in a
   * chain provides context from when the error or exception was initially
   * detected. Example usage:
   <pre>
   *   assertEquals("Unable to assign a customer id",
   *       Throwables.getRootCause(e).getMessage());
   </pre>
   */
  public static Throwable getRootCause(Throwable throwable) {
    Throwable cause;
    while ((cause = throwable.getCause()) != null) {
      throwable = cause;
    }
    return throwable;
  }

  /**
   * Gets a {@code Throwable} cause chain as a list.  The first entry in the
   * list will be {@code 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.
   *
   <p>Here's an example of how it can be used to find specific types
   * of exceptions in the cause chain:
   *
   <pre>
   * Iterables.filter(Throwables.getCausalChain(e), IOException.class));
   </pre>
   *
   @param throwable the non-null {@code Throwable} to extract causes from
   @return an unmodifiable list containing the cause chain starting with
   *     {@code throwable}
   */
  @Beta // TODO(kevinb): decide best return type
  public static List<Throwable> getCausalChain(Throwable throwable) {
    checkNotNull(throwable);
    List<Throwable> causes = new ArrayList<Throwable>(4);
    while (throwable != null) {
      causes.add(throwable);
      throwable = throwable.getCause();
    }
    return Collections.unmodifiableList(causes);
  }

  /**
   * Returns a string containing the result of
   {@link Throwable#toString() toString()}, followed by the full, recursive
   * stack trace of {@code throwable}. Note that you probably should not be
   * parsing the resulting string; if you need programmatic access to the stack
   * frames, you can call {@link Throwable#getStackTrace()}.
   */
  public static String getStackTraceAsString(Throwable throwable) {
    StringWriter stringWriter = new StringWriter();
    throwable.printStackTrace(new PrintWriter(stringWriter));
    return stringWriter.toString();
  }

  /**
   * 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.
   *
   @param exception the exception from which to extract the cause
   @param 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.
   @deprecated For {@code throwCause(e, false)}, use {@code
   *     propagateIfPossible(e.getCause(), Exception.class); throw e;}. For
   *     {@code 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 {@code InvocationTargetException}, and it usually does not
   *     otherwise, e.g., for an {@code 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
   *     {@code Future.get}, consider {@link
   *     com.google.common.util.concurrent.Futures#get(java.util.concurrent.Future,
   *     Class)}. This method will be removed from Guava in Guava release 11.0.
   */
  @Beta
  @Deprecated
  public static Exception throwCause(Exception exception,
      boolean combineStackTracesthrows Exception {
    Throwable cause = exception.getCause();
    if (cause == null) {
      throw exception;
    }
    if (combineStackTraces) {
      StackTraceElement[] causeTrace = cause.getStackTrace();
      StackTraceElement[] outerTrace = exception.getStackTrace();
      StackTraceElement[] combined =
          new StackTraceElement[causeTrace.length + outerTrace.length];
      System.arraycopy(causeTrace, 0, combined, 0, causeTrace.length);
      System.arraycopy(outerTrace, 0, combined,
          causeTrace.length, outerTrace.length);
      cause.setStackTrace(combined);
    }
    if (cause instanceof Exception) {
      throw (Exceptioncause;
    }
    if (cause instanceof Error) {
      throw (Errorcause;
    }
    // The cause is a weird kind of Throwable, so throw the outer exception
    throw exception;
  }
}