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     * @author Kevin Bourrillion
035     * @author Ben Yu
036     * @since 1.0
037     */
038    public final class Throwables {
039      private Throwables() {}
040    
041      /**
042       * Propagates {@code throwable} exactly as-is, if and only if it is an
043       * instance of {@code declaredType}.  Example usage:
044       * <pre>
045       *   try {
046       *     someMethodThatCouldThrowAnything();
047       *   } catch (IKnowWhatToDoWithThisException e) {
048       *     handle(e);
049       *   } catch (Throwable t) {
050       *     Throwables.propagateIfInstanceOf(t, IOException.class);
051       *     Throwables.propagateIfInstanceOf(t, SQLException.class);
052       *     throw Throwables.propagate(t);
053       *   }
054       * </pre>
055       */
056      public static <X extends Throwable> void propagateIfInstanceOf(
057          @Nullable Throwable throwable, Class<X> declaredType) throws X {
058        // Check for null is needed to avoid frequent JNI calls to isInstance().
059        if (throwable != null && declaredType.isInstance(throwable)) {
060          throw declaredType.cast(throwable);
061        }
062      }
063    
064      /**
065       * Propagates {@code throwable} exactly as-is, if and only if it is an
066       * instance of {@link RuntimeException} or {@link Error}.  Example usage:
067       * <pre>
068       *   try {
069       *     someMethodThatCouldThrowAnything();
070       *   } catch (IKnowWhatToDoWithThisException e) {
071       *     handle(e);
072       *   } catch (Throwable t) {
073       *     Throwables.propagateIfPossible(t);
074       *     throw new RuntimeException("unexpected", t);
075       *   }
076       * </pre>
077       */
078      public static void propagateIfPossible(@Nullable Throwable throwable) {
079        propagateIfInstanceOf(throwable, Error.class);
080        propagateIfInstanceOf(throwable, RuntimeException.class);
081      }
082    
083      /**
084       * Propagates {@code throwable} exactly as-is, if and only if it is an
085       * instance of {@link RuntimeException}, {@link Error}, or
086       * {@code declaredType}. Example usage:
087       * <pre>
088       *   try {
089       *     someMethodThatCouldThrowAnything();
090       *   } catch (IKnowWhatToDoWithThisException e) {
091       *     handle(e);
092       *   } catch (Throwable t) {
093       *     Throwables.propagateIfPossible(t, OtherException.class);
094       *     throw new RuntimeException("unexpected", t);
095       *   }
096       * </pre>
097       *
098       * @param throwable the Throwable to possibly propagate
099       * @param declaredType the single checked exception type declared by the
100       *     calling method
101       */
102      public static <X extends Throwable> void propagateIfPossible(
103          @Nullable Throwable throwable, Class<X> declaredType) throws X {
104        propagateIfInstanceOf(throwable, declaredType);
105        propagateIfPossible(throwable);
106      }
107    
108      /**
109       * Propagates {@code throwable} exactly as-is, if and only if it is an
110       * instance of {@link RuntimeException}, {@link Error}, {@code declaredType1},
111       * or {@code declaredType2}.  In the unlikely case that you have three or more
112       * declared checked exception types, you can handle them all by invoking these
113       * methods repeatedly. See usage example in {@link
114       * #propagateIfPossible(Throwable, Class)}.
115       *
116       * @param throwable the Throwable to possibly propagate
117       * @param declaredType1 any checked exception type declared by the calling
118       *     method
119       * @param declaredType2 any other checked exception type declared by the
120       *     calling method
121       */
122      public static <X1 extends Throwable, X2 extends Throwable>
123          void propagateIfPossible(@Nullable Throwable throwable,
124              Class<X1> declaredType1, Class<X2> declaredType2) throws X1, X2 {
125        checkNotNull(declaredType2);
126        propagateIfInstanceOf(throwable, declaredType1);
127        propagateIfPossible(throwable, declaredType2);
128      }
129    
130      /**
131       * Propagates {@code throwable} as-is if it is an instance of
132       * {@link RuntimeException} or {@link Error}, or else as a last resort, wraps
133       * it in a {@code RuntimeException} then propagates.
134       * <p>
135       * This method always throws an exception. The {@code RuntimeException} return
136       * type is only for client code to make Java type system happy in case a
137       * return value is required by the enclosing method. Example usage:
138       * <pre>
139       *   T doSomething() {
140       *     try {
141       *       return someMethodThatCouldThrowAnything();
142       *     } catch (IKnowWhatToDoWithThisException e) {
143       *       return handle(e);
144       *     } catch (Throwable t) {
145       *       throw Throwables.propagate(t);
146       *     }
147       *   }
148       * </pre>
149       *
150       * @param throwable the Throwable to propagate
151       * @return nothing will ever be returned; this return type is only for your
152       *     convenience, as illustrated in the example above
153       */
154      public static RuntimeException propagate(Throwable throwable) {
155        propagateIfPossible(checkNotNull(throwable));
156        throw new RuntimeException(throwable);
157      }
158    
159      /**
160       * Returns the innermost cause of {@code throwable}. The first throwable in a
161       * chain provides context from when the error or exception was initially
162       * detected. Example usage:
163       * <pre>
164       *   assertEquals("Unable to assign a customer id",
165       *       Throwables.getRootCause(e).getMessage());
166       * </pre>
167       */
168      public static Throwable getRootCause(Throwable throwable) {
169        Throwable cause;
170        while ((cause = throwable.getCause()) != null) {
171          throwable = cause;
172        }
173        return throwable;
174      }
175    
176      /**
177       * Gets a {@code Throwable} cause chain as a list.  The first entry in the
178       * list will be {@code throwable} followed by its cause hierarchy.  Note
179       * that this is a snapshot of the cause chain and will not reflect
180       * any subsequent changes to the cause chain.
181       *
182       * <p>Here's an example of how it can be used to find specific types
183       * of exceptions in the cause chain:
184       *
185       * <pre>
186       * Iterables.filter(Throwables.getCausalChain(e), IOException.class));
187       * </pre>
188       *
189       * @param throwable the non-null {@code Throwable} to extract causes from
190       * @return an unmodifiable list containing the cause chain starting with
191       *     {@code throwable}
192       */
193      @Beta // TODO(kevinb): decide best return type
194      public static List<Throwable> getCausalChain(Throwable throwable) {
195        checkNotNull(throwable);
196        List<Throwable> causes = new ArrayList<Throwable>(4);
197        while (throwable != null) {
198          causes.add(throwable);
199          throwable = throwable.getCause();
200        }
201        return Collections.unmodifiableList(causes);
202      }
203    
204      /**
205       * Returns a string containing the result of
206       * {@link Throwable#toString() toString()}, followed by the full, recursive
207       * stack trace of {@code throwable}. Note that you probably should not be
208       * parsing the resulting string; if you need programmatic access to the stack
209       * frames, you can call {@link Throwable#getStackTrace()}.
210       */
211      public static String getStackTraceAsString(Throwable throwable) {
212        StringWriter stringWriter = new StringWriter();
213        throwable.printStackTrace(new PrintWriter(stringWriter));
214        return stringWriter.toString();
215      }
216    
217      /**
218       * Rethrows the cause exception of a given throwable, discarding the original
219       * throwable. Optionally, the stack frames of the cause and the outer
220       * exception are combined and the stack trace of the cause is set to this
221       * combined trace. If there is no cause the original exception is rethrown
222       * unchanged in all cases.
223       *
224       * @param exception the exception from which to extract the cause
225       * @param combineStackTraces if true the stack trace of the cause will be
226       *     replaced by the concatenation of the trace from the exception and the
227       *     trace from the cause.
228       * @deprecated For {@code throwCause(e, false)}, use {@code
229       *     propagateIfPossible(e.getCause(), Exception.class); throw e;}. For
230       *     {@code throwCause(e, true)}, there is no exact equivalent. Callers are
231       *     encouraged to consider whether the cause contains all useful stack
232       *     trace context. (It usually does if it comes from within the thread,
233       *     e.g., for an {@code InvocationTargetException}, and it usually does not
234       *     otherwise, e.g., for an {@code ExecutionException}.) If the cause
235       *     contains all useful context, consider throwing it directly if your
236       *     method signature permits or wrapping it in an appropriate exception if
237       *     not. If the cause does not contain all useful context, consider
238       *     propagating the wrapper exception or rewrapping the cause in an
239       *     appropriate exception. For the particular case of exceptions thrown by
240       *     {@code Future.get}, consider {@link
241       *     com.google.common.util.concurrent.Futures#get(java.util.concurrent.Future,
242       *     Class)}. This method will be removed from Guava in Guava release 11.0.
243       */
244      @Beta
245      @Deprecated
246      public static Exception throwCause(Exception exception,
247          boolean combineStackTraces) throws Exception {
248        Throwable cause = exception.getCause();
249        if (cause == null) {
250          throw exception;
251        }
252        if (combineStackTraces) {
253          StackTraceElement[] causeTrace = cause.getStackTrace();
254          StackTraceElement[] outerTrace = exception.getStackTrace();
255          StackTraceElement[] combined =
256              new StackTraceElement[causeTrace.length + outerTrace.length];
257          System.arraycopy(causeTrace, 0, combined, 0, causeTrace.length);
258          System.arraycopy(outerTrace, 0, combined,
259              causeTrace.length, outerTrace.length);
260          cause.setStackTrace(combined);
261        }
262        if (cause instanceof Exception) {
263          throw (Exception) cause;
264        }
265        if (cause instanceof Error) {
266          throw (Error) cause;
267        }
268        // The cause is a weird kind of Throwable, so throw the outer exception
269        throw exception;
270      }
271    }