Skip to content

Commit

Permalink
Remove suggestions to throw a plain RuntimeException, and discourag…
Browse files Browse the repository at this point in the history 
…e the remaining `propagateIfPossible` overloads, too.

RELNOTES=n/a
PiperOrigin-RevId: 568222002
  • Loading branch information
@cpovirk
cpovirk authored and Google Java Core Libraries committed Sep 25, 2023
1 parent 4478b7f commit 7bd86a3
Show file tree
Hide file tree
Showing 2 changed files with 26 additions and 62 deletions.
44 changes: 13 additions & 31 deletions android/guava/src/com/google/common/base/Throwables.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
*
* <pre>
* try {
* someMethodThatCouldThrowAnything();
* } catch (IKnowWhatToDoWithThisException e) {
* handle(e);
* } catch (Throwable t) {
* Throwables.propagateIfPossible(t);
* throw new RuntimeException("unexpected", t);
* }
* </pre>
* RuntimeException} or {@link Error}.
*
* @deprecated Use {@link #throwIfUnchecked}, which has the same behavior but rejects {@code
* null}.
Expand All @@ -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}.
*
* <pre>
* try {
* someMethodThatCouldThrowAnything();
* } catch (IKnowWhatToDoWithThisException e) {
* handle(e);
* } catch (Throwable t) {
* Throwables.propagateIfPossible(t, OtherException.class);
* throw new RuntimeException("unexpected", t);
* }
* </pre>
* <p><b>Discouraged</b> 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
Expand All @@ -193,10 +174,10 @@ public static <X extends Throwable> 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}.
*
* <p><b>Discouraged</b> 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
Expand Down Expand Up @@ -235,10 +216,11 @@ public static <X1 extends Throwable, X2 extends Throwable> 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 <a href="https://goo.gl/Ivn2kc">Why we deprecated
* {@code Throwables.propagate}</a>.
* @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 <a
* href="https://goo.gl/Ivn2kc">Why we deprecated {@code Throwables.propagate}</a>.
*/
@CanIgnoreReturnValue
@J2ktIncompatible
Expand Down
44 changes: 13 additions & 31 deletions guava/src/com/google/common/base/Throwables.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
*
* <pre>
* try {
* someMethodThatCouldThrowAnything();
* } catch (IKnowWhatToDoWithThisException e) {
* handle(e);
* } catch (Throwable t) {
* Throwables.propagateIfPossible(t);
* throw new RuntimeException("unexpected", t);
* }
* </pre>
* RuntimeException} or {@link Error}.
*
* @deprecated Use {@link #throwIfUnchecked}, which has the same behavior but rejects {@code
* null}.
Expand All @@ -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}.
*
* <pre>
* try {
* someMethodThatCouldThrowAnything();
* } catch (IKnowWhatToDoWithThisException e) {
* handle(e);
* } catch (Throwable t) {
* Throwables.propagateIfPossible(t, OtherException.class);
* throw new RuntimeException("unexpected", t);
* }
* </pre>
* <p><b>Discouraged</b> 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
Expand All @@ -193,10 +174,10 @@ public static <X extends Throwable> 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}.
*
* <p><b>Discouraged</b> 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
Expand Down Expand Up @@ -235,10 +216,11 @@ public static <X1 extends Throwable, X2 extends Throwable> 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 <a href="https://goo.gl/Ivn2kc">Why we deprecated
* {@code Throwables.propagate}</a>.
* @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 <a
* href="https://goo.gl/Ivn2kc">Why we deprecated {@code Throwables.propagate}</a>.
*/
@CanIgnoreReturnValue
@J2ktIncompatible
Expand Down

0 comments on commit 7bd86a3

Please sign in to comment.