    001    /*
    002     * Copyright (C) 2007 The Guava Authors
    003     *
    004     * Licensed under the Apache License, Version 2.0 (the "License");
    005     * you may not use this file except in compliance with the License.
    006     * You may obtain a copy of the License at
    007     *
    008     * http://www.apache.org/licenses/LICENSE-2.0
    009     *
    010     * Unless required by applicable law or agreed to in writing, software
    011     * distributed under the License is distributed on an "AS IS" BASIS,
    012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    013     * See the License for the specific language governing permissions and
    014     * limitations under the License.
    015     */
    016
    017    package com.google.common.base;
    018
    019    import static com.google.common.base.Preconditions.checkNotNull;
    020
    021    import com.google.common.annotations.Beta;
    022
    023    import java.io.PrintWriter;
    024    import java.io.StringWriter;
    025    import java.util.ArrayList;
    026    import java.util.Collections;
    027    import java.util.List;
    028
    029    import javax.annotation.Nullable;
    030
    031    /**
    032     * Static utility methods pertaining to instances of {@link Throwable}.
    033     *
    034     * <p>See the Guava User Guide entry on <a href=
    035     * "http://code.google.com/p/guava-libraries/wiki/ThrowablesExplained">
    036     * Throwables</a>.
    037     *
    038     * @author Kevin Bourrillion
    039     * @author Ben Yu
    040     * @since 1.0
    041     */
    042    public final class Throwables {
    043      private Throwables() {}
    044
    045      /**
    046       * Propagates {@code throwable} exactly as-is, if and only if it is an
    047       * instance of {@code declaredType}.  Example usage:
    048       * <pre>
    049       *   try {
    050       *     someMethodThatCouldThrowAnything();
    051       *   } catch (IKnowWhatToDoWithThisException e) {
    052       *     handle(e);
    053       *   } catch (Throwable t) {
    054       *     Throwables.propagateIfInstanceOf(t, IOException.class);
    055       *     Throwables.propagateIfInstanceOf(t, SQLException.class);
    056       *     throw Throwables.propagate(t);
    057       *   }
    058       * </pre>
    059       */
    060      public static <X extends Throwable> void propagateIfInstanceOf(
    061          @Nullable Throwable throwable, Class<X> declaredType) throws X {
    062        // Check for null is needed to avoid frequent JNI calls to isInstance().
    063        if (throwable != null && declaredType.isInstance(throwable)) {
    064          throw declaredType.cast(throwable);
    065        }
    066      }
    067
    068      /**
    069       * Propagates {@code throwable} exactly as-is, if and only if it is an
    070       * instance of {@link RuntimeException} or {@link Error}.  Example usage:
    071       * <pre>
    072       *   try {
    073       *     someMethodThatCouldThrowAnything();
    074       *   } catch (IKnowWhatToDoWithThisException e) {
    075       *     handle(e);
    076       *   } catch (Throwable t) {
    077       *     Throwables.propagateIfPossible(t);
    078       *     throw new RuntimeException("unexpected", t);
    079       *   }
    080       * </pre>
    081       */
    082      public static void propagateIfPossible(@Nullable Throwable throwable) {
    083        propagateIfInstanceOf(throwable, Error.class);
    084        propagateIfInstanceOf(throwable, RuntimeException.class);
    085      }
    086
    087      /**
    088       * Propagates {@code throwable} exactly as-is, if and only if it is an
    089       * instance of {@link RuntimeException}, {@link Error}, or
    090       * {@code declaredType}. Example usage:
    091       * <pre>
    092       *   try {
    093       *     someMethodThatCouldThrowAnything();
    094       *   } catch (IKnowWhatToDoWithThisException e) {
    095       *     handle(e);
    096       *   } catch (Throwable t) {
    097       *     Throwables.propagateIfPossible(t, OtherException.class);
    098       *     throw new RuntimeException("unexpected", t);
    099       *   }
    100       * </pre>
    101       *
    102       * @param throwable the Throwable to possibly propagate
    103       * @param declaredType the single checked exception type declared by the
    104       *     calling method
    105       */
    106      public static <X extends Throwable> void propagateIfPossible(
    107          @Nullable Throwable throwable, Class<X> declaredType) throws X {
    108        propagateIfInstanceOf(throwable, declaredType);
    109        propagateIfPossible(throwable);
    110      }
    111
    112      /**
    113       * Propagates {@code throwable} exactly as-is, if and only if it is an
    114       * instance of {@link RuntimeException}, {@link Error}, {@code declaredType1},
    115       * or {@code declaredType2}.  In the unlikely case that you have three or more
    116       * declared checked exception types, you can handle them all by invoking these
    117       * methods repeatedly. See usage example in {@link
    118       * #propagateIfPossible(Throwable, Class)}.
    119       *
    120       * @param throwable the Throwable to possibly propagate
    121       * @param declaredType1 any checked exception type declared by the calling
    122       *     method
    123       * @param declaredType2 any other checked exception type declared by the
    124       *     calling method
    125       */
    126      public static <X1 extends Throwable, X2 extends Throwable>
    127          void propagateIfPossible(@Nullable Throwable throwable,
    128              Class<X1> declaredType1, Class<X2> declaredType2) throws X1, X2 {
    129        checkNotNull(declaredType2);
    130        propagateIfInstanceOf(throwable, declaredType1);
    131        propagateIfPossible(throwable, declaredType2);
    132      }
    133
    134      /**
    135       * Propagates {@code throwable} as-is if it is an instance of
    136       * {@link RuntimeException} or {@link Error}, or else as a last resort, wraps
    137       * it in a {@code RuntimeException} then propagates.
    138       * <p>
    139       * This method always throws an exception. The {@code RuntimeException} return
    140       * type is only for client code to make Java type system happy in case a
    141       * return value is required by the enclosing method. Example usage:
    142       * <pre>
    143       *   T doSomething() {
    144       *     try {
    145       *       return someMethodThatCouldThrowAnything();
    146       *     } catch (IKnowWhatToDoWithThisException e) {
    147       *       return handle(e);
    148       *     } catch (Throwable t) {
    149       *       throw Throwables.propagate(t);
    150       *     }
    151       *   }
    152       * </pre>
    153       *
    154       * @param throwable the Throwable to propagate
    155       * @return nothing will ever be returned; this return type is only for your
    156       *     convenience, as illustrated in the example above
    157       */
    158      public static RuntimeException propagate(Throwable throwable) {
    159        propagateIfPossible(checkNotNull(throwable));
    160        throw new RuntimeException(throwable);
    161      }
    162
    163      /**
    164       * Returns the innermost cause of {@code throwable}. The first throwable in a
    165       * chain provides context from when the error or exception was initially
    166       * detected. Example usage:
    167       * <pre>
    168       *   assertEquals("Unable to assign a customer id",
    169       *       Throwables.getRootCause(e).getMessage());
    170       * </pre>
    171       */
    172      public static Throwable getRootCause(Throwable throwable) {
    173        Throwable cause;
    174        while ((cause = throwable.getCause()) != null) {
    175          throwable = cause;
    176        }
    177        return throwable;
    178      }
    179
    180      /**
    181       * Gets a {@code Throwable} cause chain as a list.  The first entry in the
    182       * list will be {@code throwable} followed by its cause hierarchy.  Note
    183       * that this is a snapshot of the cause chain and will not reflect
    184       * any subsequent changes to the cause chain.
    185       *
    186       * <p>Here's an example of how it can be used to find specific types
    187       * of exceptions in the cause chain:
    188       *
    189       * <pre>
    190       * Iterables.filter(Throwables.getCausalChain(e), IOException.class));
    191       * </pre>
    192       *
    193       * @param throwable the non-null {@code Throwable} to extract causes from
    194       * @return an unmodifiable list containing the cause chain starting with
    195       *     {@code throwable}
    196       */
    197      @Beta // TODO(kevinb): decide best return type
    198      public static List<Throwable> getCausalChain(Throwable throwable) {
    199        checkNotNull(throwable);
    200        List<Throwable> causes = new ArrayList<Throwable>(4);
    201        while (throwable != null) {
    202          causes.add(throwable);
    203          throwable = throwable.getCause();
    204        }
    205        return Collections.unmodifiableList(causes);
    206      }
    207
    208      /**
    209       * Returns a string containing the result of
    210       * {@link Throwable#toString() toString()}, followed by the full, recursive
    211       * stack trace of {@code throwable}. Note that you probably should not be
    212       * parsing the resulting string; if you need programmatic access to the stack
    213       * frames, you can call {@link Throwable#getStackTrace()}.
    214       */
    215      public static String getStackTraceAsString(Throwable throwable) {
    216        StringWriter stringWriter = new StringWriter();
    217        throwable.printStackTrace(new PrintWriter(stringWriter));
    218        return stringWriter.toString();
    219      }
    220    }