001/*
002 * Copyright (C) 2007 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.base;
016
017import static com.google.common.base.Preconditions.checkNotNull;
018import static java.util.Arrays.asList;
019import static java.util.Collections.unmodifiableList;
020import static java.util.Objects.requireNonNull;
021
022import com.google.common.annotations.GwtCompatible;
023import com.google.common.annotations.GwtIncompatible;
024import com.google.common.annotations.J2ktIncompatible;
025import com.google.common.annotations.VisibleForTesting;
026import com.google.errorprone.annotations.CanIgnoreReturnValue;
027import java.io.IOException;
028import java.io.PrintWriter;
029import java.io.StringWriter;
030import java.lang.reflect.InvocationTargetException;
031import java.lang.reflect.Method;
032import java.util.AbstractList;
033import java.util.ArrayList;
034import java.util.Collections;
035import java.util.List;
036import javax.annotation.CheckForNull;
037
038/**
039 * Static utility methods pertaining to instances of {@link Throwable}.
040 *
041 * <p>See the Guava User Guide entry on <a
042 * href="https://github.com/google/guava/wiki/ThrowablesExplained">Throwables</a>.
043 *
044 * @author Kevin Bourrillion
045 * @author Ben Yu
046 * @since 1.0
047 */
048@GwtCompatible(emulated = true)
049@ElementTypesAreNonnullByDefault
050public final class Throwables {
051  private Throwables() {}
052
053  /**
054   * Throws {@code throwable} if it is an instance of {@code declaredType}. Example usage:
055   *
056   * <pre>
057   * for (Foo foo : foos) {
058   *   try {
059   *     foo.bar();
060   *   } catch (BarException | RuntimeException | Error t) {
061   *     failure = t;
062   *   }
063   * }
064   * if (failure != null) {
065   *   throwIfInstanceOf(failure, BarException.class);
066   *   throwIfUnchecked(failure);
067   *   throw new AssertionError(failure);
068   * }
069   * </pre>
070   *
071   * @since 20.0
072   */
073  @GwtIncompatible // Class.cast, Class.isInstance
074  public static <X extends Throwable> void throwIfInstanceOf(
075      Throwable throwable, Class<X> declaredType) throws X {
076    checkNotNull(throwable);
077    if (declaredType.isInstance(throwable)) {
078      throw declaredType.cast(throwable);
079    }
080  }
081
082  /**
083   * Propagates {@code throwable} exactly as-is, if and only if it is an instance of {@code
084   * declaredType}. Example usage:
085   *
086   * <pre>
087   * try {
088   *   someMethodThatCouldThrowAnything();
089   * } catch (IKnowWhatToDoWithThisException e) {
090   *   handle(e);
091   * } catch (Throwable t) {
092   *   Throwables.propagateIfInstanceOf(t, IOException.class);
093   *   Throwables.propagateIfInstanceOf(t, SQLException.class);
094   *   throw Throwables.propagate(t);
095   * }
096   * </pre>
097   *
098   * @deprecated Use {@link #throwIfInstanceOf}, which has the same behavior but rejects {@code
099   *     null}.
100   */
101  @Deprecated
102  @J2ktIncompatible
103  @GwtIncompatible // throwIfInstanceOf
104  public static <X extends Throwable> void propagateIfInstanceOf(
105      @CheckForNull Throwable throwable, Class<X> declaredType) throws X {
106    if (throwable != null) {
107      throwIfInstanceOf(throwable, declaredType);
108    }
109  }
110
111  /**
112   * Throws {@code throwable} if it is a {@link RuntimeException} or {@link Error}. Example usage:
113   *
114   * <pre>
115   * for (Foo foo : foos) {
116   *   try {
117   *     foo.bar();
118   *   } catch (RuntimeException | Error t) {
119   *     failure = t;
120   *   }
121   * }
122   * if (failure != null) {
123   *   throwIfUnchecked(failure);
124   *   throw new AssertionError(failure);
125   * }
126   * </pre>
127   *
128   * @since 20.0
129   */
130  public static void throwIfUnchecked(Throwable throwable) {
131    checkNotNull(throwable);
132    if (throwable instanceof RuntimeException) {
133      throw (RuntimeException) throwable;
134    }
135    if (throwable instanceof Error) {
136      throw (Error) throwable;
137    }
138  }
139
140  /**
141   * Propagates {@code throwable} exactly as-is, if and only if it is an instance of {@link
142   * RuntimeException} or {@link Error}.
143   *
144   * @deprecated Use {@link #throwIfUnchecked}, which has the same behavior but rejects {@code
145   *     null}.
146   */
147  @Deprecated
148  @J2ktIncompatible
149  @GwtIncompatible
150  public static void propagateIfPossible(@CheckForNull Throwable throwable) {
151    if (throwable != null) {
152      throwIfUnchecked(throwable);
153    }
154  }
155
156  /**
157   * Propagates {@code throwable} exactly as-is, if and only if it is an instance of {@link
158   * RuntimeException}, {@link Error}, or {@code declaredType}.
159   *
160   * <p><b>Discouraged</b> in favor of calling {@link #throwIfInstanceOf} and {@link
161   * #throwIfUnchecked}.
162   *
163   * @param throwable the Throwable to possibly propagate
164   * @param declaredType the single checked exception type declared by the calling method
165   * @deprecated Use a combination of {@link #throwIfInstanceOf} and {@link #throwIfUnchecked},
166   *     which togther provide the same behavior except that they reject {@code null}.
167   */
168  @Deprecated
169  @J2ktIncompatible
170  @GwtIncompatible // propagateIfInstanceOf
171  public static <X extends Throwable> void propagateIfPossible(
172      @CheckForNull Throwable throwable, Class<X> declaredType) throws X {
173    propagateIfInstanceOf(throwable, declaredType);
174    propagateIfPossible(throwable);
175  }
176
177  /**
178   * Propagates {@code throwable} exactly as-is, if and only if it is an instance of {@link
179   * RuntimeException}, {@link Error}, {@code declaredType1}, or {@code declaredType2}.
180   *
181   * @param throwable the Throwable to possibly propagate
182   * @param declaredType1 any checked exception type declared by the calling method
183   * @param declaredType2 any other checked exception type declared by the calling method
184   * @deprecated Use a combination of two calls to {@link #throwIfInstanceOf} and one call to {@link
185   *     #throwIfUnchecked}, which togther provide the same behavior except that they reject {@code
186   *     null}.
187   */
188  @Deprecated
189  @J2ktIncompatible
190  @GwtIncompatible // propagateIfInstanceOf
191  public static <X1 extends Throwable, X2 extends Throwable> void propagateIfPossible(
192      @CheckForNull Throwable throwable, Class<X1> declaredType1, Class<X2> declaredType2)
193      throws X1, X2 {
194    checkNotNull(declaredType2);
195    propagateIfInstanceOf(throwable, declaredType1);
196    propagateIfPossible(throwable, declaredType2);
197  }
198
199  /**
200   * Propagates {@code throwable} as-is if it is an instance of {@link RuntimeException} or {@link
201   * Error}, or else as a last resort, wraps it in a {@code RuntimeException} and then propagates.
202   *
203   * <p>This method always throws an exception. The {@code RuntimeException} return type allows
204   * client code to signal to the compiler that statements after the call are unreachable. Example
205   * usage:
206   *
207   * <pre>
208   * T doSomething() {
209   *   try {
210   *     return someMethodThatCouldThrowAnything();
211   *   } catch (IKnowWhatToDoWithThisException e) {
212   *     return handle(e);
213   *   } catch (Throwable t) {
214   *     throw Throwables.propagate(t);
215   *   }
216   * }
217   * </pre>
218   *
219   * @param throwable the Throwable to propagate
220   * @return nothing will ever be returned; this return type is only for your convenience, as
221   *     illustrated in the example above
222   * @deprecated To preserve behavior, use {@code throw e} or {@code throw new RuntimeException(e)}
223   *     directly, or use a combination of {@link #throwIfUnchecked} and {@code throw new
224   *     RuntimeException(e)}. But consider whether users would be better off if your API threw a
225   *     different type of exception. For background on the deprecation, read <a
226   *     href="https://goo.gl/Ivn2kc">Why we deprecated {@code Throwables.propagate}</a>.
227   */
228  @CanIgnoreReturnValue
229  @J2ktIncompatible
230  @GwtIncompatible
231  @Deprecated
232  public static RuntimeException propagate(Throwable throwable) {
233    throwIfUnchecked(throwable);
234    throw new RuntimeException(throwable);
235  }
236
237  /**
238   * Returns the innermost cause of {@code throwable}. The first throwable in a chain provides
239   * context from when the error or exception was initially detected. Example usage:
240   *
241   * <pre>
242   * assertEquals("Unable to assign a customer id", Throwables.getRootCause(e).getMessage());
243   * </pre>
244   *
245   * @throws IllegalArgumentException if there is a loop in the causal chain
246   */
247  public static Throwable getRootCause(Throwable throwable) {
248    // Keep a second pointer that slowly walks the causal chain. If the fast pointer ever catches
249    // the slower pointer, then there's a loop.
250    Throwable slowPointer = throwable;
251    boolean advanceSlowPointer = false;
252
253    Throwable cause;
254    while ((cause = throwable.getCause()) != null) {
255      throwable = cause;
256
257      if (throwable == slowPointer) {
258        throw new IllegalArgumentException("Loop in causal chain detected.", throwable);
259      }
260      if (advanceSlowPointer) {
261        slowPointer = slowPointer.getCause();
262      }
263      advanceSlowPointer = !advanceSlowPointer; // only advance every other iteration
264    }
265    return throwable;
266  }
267
268  /**
269   * Gets a {@code Throwable} cause chain as a list. The first entry in the list will be {@code
270   * throwable} followed by its cause hierarchy. Note that this is a snapshot of the cause chain and
271   * will not reflect any subsequent changes to the cause chain.
272   *
273   * <p>Here's an example of how it can be used to find specific types of exceptions in the cause
274   * chain:
275   *
276   * <pre>
277   * Iterables.filter(Throwables.getCausalChain(e), IOException.class));
278   * </pre>
279   *
280   * @param throwable the non-null {@code Throwable} to extract causes from
281   * @return an unmodifiable list containing the cause chain starting with {@code throwable}
282   * @throws IllegalArgumentException if there is a loop in the causal chain
283   */
284  public static List<Throwable> getCausalChain(Throwable throwable) {
285    checkNotNull(throwable);
286    List<Throwable> causes = new ArrayList<>(4);
287    causes.add(throwable);
288
289    // Keep a second pointer that slowly walks the causal chain. If the fast pointer ever catches
290    // the slower pointer, then there's a loop.
291    Throwable slowPointer = throwable;
292    boolean advanceSlowPointer = false;
293
294    Throwable cause;
295    while ((cause = throwable.getCause()) != null) {
296      throwable = cause;
297      causes.add(throwable);
298
299      if (throwable == slowPointer) {
300        throw new IllegalArgumentException("Loop in causal chain detected.", throwable);
301      }
302      if (advanceSlowPointer) {
303        slowPointer = slowPointer.getCause();
304      }
305      advanceSlowPointer = !advanceSlowPointer; // only advance every other iteration
306    }
307    return Collections.unmodifiableList(causes);
308  }
309
310  /**
311   * Returns {@code throwable}'s cause, cast to {@code expectedCauseType}.
312   *
313   * <p>Prefer this method instead of manually casting an exception's cause. For example, {@code
314   * (IOException) e.getCause()} throws a {@link ClassCastException} that discards the original
315   * exception {@code e} if the cause is not an {@link IOException}, but {@code
316   * Throwables.getCauseAs(e, IOException.class)} keeps {@code e} as the {@link
317   * ClassCastException}'s cause.
318   *
319   * @throws ClassCastException if the cause cannot be cast to the expected type. The {@code
320   *     ClassCastException}'s cause is {@code throwable}.
321   * @since 22.0
322   */
323  @GwtIncompatible // Class.cast(Object)
324  @CheckForNull
325  public static <X extends Throwable> X getCauseAs(
326      Throwable throwable, Class<X> expectedCauseType) {
327    try {
328      return expectedCauseType.cast(throwable.getCause());
329    } catch (ClassCastException e) {
330      e.initCause(throwable);
331      throw e;
332    }
333  }
334
335  /**
336   * Returns a string containing the result of {@link Throwable#toString() toString()}, followed by
337   * the full, recursive stack trace of {@code throwable}. Note that you probably should not be
338   * parsing the resulting string; if you need programmatic access to the stack frames, you can call
339   * {@link Throwable#getStackTrace()}.
340   */
341  @GwtIncompatible // java.io.PrintWriter, java.io.StringWriter
342  public static String getStackTraceAsString(Throwable throwable) {
343    StringWriter stringWriter = new StringWriter();
344    throwable.printStackTrace(new PrintWriter(stringWriter));
345    return stringWriter.toString();
346  }
347
348  /**
349   * Returns the stack trace of {@code throwable}, possibly providing slower iteration over the full
350   * trace but faster iteration over parts of the trace. Here, "slower" and "faster" are defined in
351   * comparison to the normal way to access the stack trace, {@link Throwable#getStackTrace()
352   * throwable.getStackTrace()}. Note, however, that this method's special implementation is not
353   * available for all platforms and configurations. If that implementation is unavailable, this
354   * method falls back to {@code getStackTrace}. Callers that require the special implementation can
355   * check its availability with {@link #lazyStackTraceIsLazy()}.
356   *
357   * <p>The expected (but not guaranteed) performance of the special implementation differs from
358   * {@code getStackTrace} in one main way: The {@code lazyStackTrace} call itself returns quickly
359   * by delaying the per-stack-frame work until each element is accessed. Roughly speaking:
360   *
361   * <ul>
362   *   <li>{@code getStackTrace} takes {@code stackSize} time to return but then negligible time to
363   *       retrieve each element of the returned list.
364   *   <li>{@code lazyStackTrace} takes negligible time to return but then {@code 1/stackSize} time
365   *       to retrieve each element of the returned list (probably slightly more than {@code
366   *       1/stackSize}).
367   * </ul>
368   *
369   * <p>Note: The special implementation does not respect calls to {@link Throwable#setStackTrace
370   * throwable.setStackTrace}. Instead, it always reflects the original stack trace from the
371   * exception's creation.
372   *
373   * @since 19.0
374   * @deprecated This method is equivalent to {@link Throwable#getStackTrace()} on JDK versions past
375   *     JDK 8 and on all Android versions. Use {@link Throwable#getStackTrace()} directly, or where
376   *     possible use the {@code java.lang.StackWalker.walk} method introduced in JDK 9.
377   */
378  @Deprecated
379  @J2ktIncompatible
380  @GwtIncompatible // lazyStackTraceIsLazy, jlaStackTrace
381  public static List<StackTraceElement> lazyStackTrace(Throwable throwable) {
382    return lazyStackTraceIsLazy()
383        ? jlaStackTrace(throwable)
384        : unmodifiableList(asList(throwable.getStackTrace()));
385  }
386
387  /**
388   * Returns whether {@link #lazyStackTrace} will use the special implementation described in its
389   * documentation.
390   *
391   * @since 19.0
392   * @deprecated This method always returns false on JDK versions past JDK 8 and on all Android
393   *     versions.
394   */
395  @Deprecated
396  @J2ktIncompatible
397  @GwtIncompatible // getStackTraceElementMethod
398  public static boolean lazyStackTraceIsLazy() {
399    return getStackTraceElementMethod != null && getStackTraceDepthMethod != null;
400  }
401
402  @J2ktIncompatible
403  @GwtIncompatible // invokeAccessibleNonThrowingMethod
404  private static List<StackTraceElement> jlaStackTrace(Throwable t) {
405    checkNotNull(t);
406    /*
407     * TODO(cpovirk): Consider optimizing iterator() to catch IOOBE instead of doing bounds checks.
408     *
409     * TODO(cpovirk): Consider the UnsignedBytes pattern if it performs faster and doesn't cause
410     * AOSP grief.
411     */
412    return new AbstractList<StackTraceElement>() {
413      /*
414       * The following requireNonNull calls are safe because we use jlaStackTrace() only if
415       * lazyStackTraceIsLazy() returns true.
416       */
417      @Override
418      public StackTraceElement get(int n) {
419        return (StackTraceElement)
420            invokeAccessibleNonThrowingMethod(
421                requireNonNull(getStackTraceElementMethod), requireNonNull(jla), t, n);
422      }
423
424      @Override
425      public int size() {
426        return (Integer)
427            invokeAccessibleNonThrowingMethod(
428                requireNonNull(getStackTraceDepthMethod), requireNonNull(jla), t);
429      }
430    };
431  }
432
433  @J2ktIncompatible
434  @GwtIncompatible // java.lang.reflect
435  private static Object invokeAccessibleNonThrowingMethod(
436      Method method, Object receiver, Object... params) {
437    try {
438      return method.invoke(receiver, params);
439    } catch (IllegalAccessException e) {
440      throw new RuntimeException(e);
441    } catch (InvocationTargetException e) {
442      throw propagate(e.getCause());
443    }
444  }
445
446  /** JavaLangAccess class name to load using reflection */
447  @J2ktIncompatible @GwtIncompatible // not used by GWT emulation
448  private static final String JAVA_LANG_ACCESS_CLASSNAME = "sun.misc.JavaLangAccess";
449
450  /** SharedSecrets class name to load using reflection */
451  @J2ktIncompatible
452  @GwtIncompatible // not used by GWT emulation
453  @VisibleForTesting
454  static final String SHARED_SECRETS_CLASSNAME = "sun.misc.SharedSecrets";
455
456  /** Access to some fancy internal JVM internals. */
457  @J2ktIncompatible
458  @GwtIncompatible // java.lang.reflect
459  @CheckForNull
460  private static final Object jla = getJLA();
461
462  /**
463   * The "getStackTraceElementMethod" method, only available on some JDKs so we use reflection to
464   * find it when available. When this is null, use the slow way.
465   */
466  @J2ktIncompatible
467  @GwtIncompatible // java.lang.reflect
468  @CheckForNull
469  private static final Method getStackTraceElementMethod = (jla == null) ? null : getGetMethod();
470
471  /**
472   * The "getStackTraceDepth" method, only available on some JDKs so we use reflection to find it
473   * when available. When this is null, use the slow way.
474   */
475  @J2ktIncompatible
476  @GwtIncompatible // java.lang.reflect
477  @CheckForNull
478  private static final Method getStackTraceDepthMethod = (jla == null) ? null : getSizeMethod(jla);
479
480  /**
481   * Returns the JavaLangAccess class that is present in all Sun JDKs. It is not allowed in
482   * AppEngine, and not present in non-Sun JDKs.
483   */
484  @SuppressWarnings("removal") // b/318391980
485  @J2ktIncompatible
486  @GwtIncompatible // java.lang.reflect
487  @CheckForNull
488  private static Object getJLA() {
489    try {
490      /*
491       * We load sun.misc.* classes using reflection since Android doesn't support these classes and
492       * would result in compilation failure if we directly refer to these classes.
493       */
494      Class<?> sharedSecrets = Class.forName(SHARED_SECRETS_CLASSNAME, false, null);
495      Method langAccess = sharedSecrets.getMethod("getJavaLangAccess");
496      return langAccess.invoke(null);
497    } catch (ThreadDeath death) {
498      throw death;
499    } catch (Throwable t) {
500      /*
501       * This is not one of AppEngine's allowed classes, so even in Sun JDKs, this can fail with
502       * a NoClassDefFoundError. Other apps might deny access to sun.misc packages.
503       */
504      return null;
505    }
506  }
507
508  /**
509   * Returns the Method that can be used to resolve an individual StackTraceElement, or null if that
510   * method cannot be found (it is only to be found in fairly recent JDKs).
511   */
512  @J2ktIncompatible
513  @GwtIncompatible // java.lang.reflect
514  @CheckForNull
515  private static Method getGetMethod() {
516    return getJlaMethod("getStackTraceElement", Throwable.class, int.class);
517  }
518
519  /**
520   * Returns the Method that can be used to return the size of a stack, or null if that method
521   * cannot be found (it is only to be found in fairly recent JDKs). Tries to test method {@link
522   * sun.misc.JavaLangAccess#getStackTraceDepth(Throwable) getStackTraceDepth} prior to return it
523   * (might fail some JDKs).
524   *
525   * <p>See <a href="https://github.com/google/guava/issues/2887">Throwables#lazyStackTrace throws
526   * UnsupportedOperationException</a>.
527   */
528  @J2ktIncompatible
529  @GwtIncompatible // java.lang.reflect
530  @CheckForNull
531  private static Method getSizeMethod(Object jla) {
532    try {
533      Method getStackTraceDepth = getJlaMethod("getStackTraceDepth", Throwable.class);
534      if (getStackTraceDepth == null) {
535        return null;
536      }
537      getStackTraceDepth.invoke(jla, new Throwable());
538      return getStackTraceDepth;
539    } catch (UnsupportedOperationException | IllegalAccessException | InvocationTargetException e) {
540      return null;
541    }
542  }
543
544  @SuppressWarnings("removal") // b/318391980
545  @J2ktIncompatible
546  @GwtIncompatible // java.lang.reflect
547  @CheckForNull
548  private static Method getJlaMethod(String name, Class<?>... parameterTypes) throws ThreadDeath {
549    try {
550      return Class.forName(JAVA_LANG_ACCESS_CLASSNAME, false, null).getMethod(name, parameterTypes);
551    } catch (ThreadDeath death) {
552      throw death;
553    } catch (Throwable t) {
554      /*
555       * Either the JavaLangAccess class itself is not found, or the method is not supported on the
556       * JVM.
557       */
558      return null;
559    }
560  }
561}