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}