From 7bd86a32f00ffbc22aea6bd20e85b905c82c5772 Mon Sep 17 00:00:00 2001 From: cpovirk Date: Mon, 25 Sep 2023 08:08:13 -0700 Subject: [PATCH] Remove suggestions to throw a plain `RuntimeException`, and discourage the remaining `propagateIfPossible` overloads, too. RELNOTES=n/a PiperOrigin-RevId: 568222002 --- .../com/google/common/base/Throwables.java | 44 ++++++------------- .../com/google/common/base/Throwables.java | 44 ++++++------------- 2 files changed, 26 insertions(+), 62 deletions(-) diff --git a/android/guava/src/com/google/common/base/Throwables.java b/android/guava/src/com/google/common/base/Throwables.java index 23936897d956..e37a3d99deb2 100644 --- a/android/guava/src/com/google/common/base/Throwables.java +++ b/android/guava/src/com/google/common/base/Throwables.java @@ -140,18 +140,7 @@ public static void throwIfUnchecked(Throwable throwable) { /** * Propagates {@code throwable} exactly as-is, if and only if it is an instance of {@link - * RuntimeException} or {@link Error}. Example usage: - * - * 
-   * try {
-   *   someMethodThatCouldThrowAnything();
-   * } catch (IKnowWhatToDoWithThisException e) {
-   *   handle(e);
-   * } catch (Throwable t) {
-   *   Throwables.propagateIfPossible(t);
-   *   throw new RuntimeException("unexpected", t);
-   * }
-   *
+ * RuntimeException} or {@link Error}. * * @deprecated Use {@link #throwIfUnchecked}, which has the same behavior but rejects {@code * null}. @@ -167,18 +156,10 @@ public static void propagateIfPossible(@CheckForNull Throwable throwable) { /** * Propagates {@code throwable} exactly as-is, if and only if it is an instance of {@link - * RuntimeException}, {@link Error}, or {@code declaredType}. Example usage: + * RuntimeException}, {@link Error}, or {@code declaredType}. * - * 
-   * try {
-   *   someMethodThatCouldThrowAnything();
-   * } catch (IKnowWhatToDoWithThisException e) {
-   *   handle(e);
-   * } catch (Throwable t) {
-   *   Throwables.propagateIfPossible(t, OtherException.class);
-   *   throw new RuntimeException("unexpected", t);
-   * }
-   *
+ *

Discouraged in favor of calling {@link #throwIfInstanceOf} and {@link + * #throwIfUnchecked}. * * @param throwable the Throwable to possibly propagate * @param declaredType the single checked exception type declared by the calling method @@ -193,10 +174,10 @@ public static void propagateIfPossible( /** * 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)}. + * RuntimeException}, {@link Error}, {@code declaredType1}, or {@code declaredType2}. + * + *

Discouraged in favor of calling {@link #throwIfInstanceOf} and {@link + * #throwIfUnchecked}. * * @param throwable the Throwable to possibly propagate * @param declaredType1 any checked exception type declared by the calling method @@ -235,10 +216,11 @@ public static void propagateIfPossi * @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 - * @deprecated Use {@code throw e} or {@code throw new RuntimeException(e)} directly, or use a - * combination of {@link #throwIfUnchecked} and {@code throw new RuntimeException(e)}. For - * background on the deprecation, read Why we deprecated - * {@code Throwables.propagate}. + * @deprecated To preserve behavior, use {@code throw e} or {@code throw new RuntimeException(e)} + * directly, or use a combination of {@link #throwIfUnchecked} and {@code throw new + * RuntimeException(e)}. But consider whether users would be better off if your API threw a + * different type of exception. For background on the deprecation, read Why we deprecated {@code Throwables.propagate}. */ @CanIgnoreReturnValue @J2ktIncompatible diff --git a/guava/src/com/google/common/base/Throwables.java b/guava/src/com/google/common/base/Throwables.java index 23936897d956..e37a3d99deb2 100644 --- a/guava/src/com/google/common/base/Throwables.java +++ b/guava/src/com/google/common/base/Throwables.java @@ -140,18 +140,7 @@ public static void throwIfUnchecked(Throwable throwable) { /** * Propagates {@code throwable} exactly as-is, if and only if it is an instance of {@link - * RuntimeException} or {@link Error}. Example usage: - * - * 

-   * try {
-   *   someMethodThatCouldThrowAnything();
-   * } catch (IKnowWhatToDoWithThisException e) {
-   *   handle(e);
-   * } catch (Throwable t) {
-   *   Throwables.propagateIfPossible(t);
-   *   throw new RuntimeException("unexpected", t);
-   * }
-   *
+ * RuntimeException} or {@link Error}. * * @deprecated Use {@link #throwIfUnchecked}, which has the same behavior but rejects {@code * null}. @@ -167,18 +156,10 @@ public static void propagateIfPossible(@CheckForNull Throwable throwable) { /** * Propagates {@code throwable} exactly as-is, if and only if it is an instance of {@link - * RuntimeException}, {@link Error}, or {@code declaredType}. Example usage: + * RuntimeException}, {@link Error}, or {@code declaredType}. * - * 
-   * try {
-   *   someMethodThatCouldThrowAnything();
-   * } catch (IKnowWhatToDoWithThisException e) {
-   *   handle(e);
-   * } catch (Throwable t) {
-   *   Throwables.propagateIfPossible(t, OtherException.class);
-   *   throw new RuntimeException("unexpected", t);
-   * }
-   *
+ *

Discouraged in favor of calling {@link #throwIfInstanceOf} and {@link + * #throwIfUnchecked}. * * @param throwable the Throwable to possibly propagate * @param declaredType the single checked exception type declared by the calling method @@ -193,10 +174,10 @@ public static void propagateIfPossible( /** * 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)}. + * RuntimeException}, {@link Error}, {@code declaredType1}, or {@code declaredType2}. + * + *

Discouraged in favor of calling {@link #throwIfInstanceOf} and {@link + * #throwIfUnchecked}. * * @param throwable the Throwable to possibly propagate * @param declaredType1 any checked exception type declared by the calling method @@ -235,10 +216,11 @@ public static void propagateIfPossi * @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 - * @deprecated Use {@code throw e} or {@code throw new RuntimeException(e)} directly, or use a - * combination of {@link #throwIfUnchecked} and {@code throw new RuntimeException(e)}. For - * background on the deprecation, read Why we deprecated - * {@code Throwables.propagate}. + * @deprecated To preserve behavior, use {@code throw e} or {@code throw new RuntimeException(e)} + * directly, or use a combination of {@link #throwIfUnchecked} and {@code throw new + * RuntimeException(e)}. But consider whether users would be better off if your API threw a + * different type of exception. For background on the deprecation, read Why we deprecated {@code Throwables.propagate}. */ @CanIgnoreReturnValue @J2ktIncompatible