diff --git a/android/guava/src/com/google/common/util/concurrent/Futures.java b/android/guava/src/com/google/common/util/concurrent/Futures.java index c1e410c2dbd6..2de96be203f0 100644 --- a/android/guava/src/com/google/common/util/concurrent/Futures.java +++ b/android/guava/src/com/google/common/util/concurrent/Futures.java @@ -33,7 +33,6 @@ import com.google.common.util.concurrent.ImmediateFuture.ImmediateSuccessfulCheckedFuture; import com.google.common.util.concurrent.ImmediateFuture.ImmediateSuccessfulFuture; import com.google.errorprone.annotations.CanIgnoreReturnValue; -import com.google.errorprone.annotations.DoNotCall; import java.util.Collection; import java.util.List; import java.util.concurrent.Callable; @@ -280,58 +279,6 @@ public void run() { return task; } - /** - * Returns a {@code Future} whose result is taken from the given primary {@code input} or, if the - * primary input fails with the given {@code exceptionType}, from the result provided by the - * {@code fallback}. {@link Function#apply} is not invoked until the primary input has failed, so - * if the primary input succeeds, it is never invoked. If, during the invocation of {@code - * fallback}, an exception is thrown, this exception is used as the result of the output {@code - * Future}. - * - *
Usage example: - * - *
{@code - * ListenableFuture- * - *fetchCounterFuture = ...; - * - * // Falling back to a zero counter in case an exception happens when - * // processing the RPC to fetch counters. - * ListenableFuture faultTolerantFuture = Futures.catching( - * fetchCounterFuture, FetchException.class, x -> 0); - * }
This overload, which does not accept an executor, uses {@code directExecutor}, a dangerous
- * choice in some cases. See the discussion in the {@link ListenableFuture#addListener
- * ListenableFuture.addListener} documentation. All its warnings about heavyweight listeners are
- * also applicable to heavyweight functions passed to this method.
- *
- * @param input the primary input {@code Future}
- * @param exceptionType the exception type that triggers use of {@code fallback}. The exception
- * type is matched against the input's exception. "The input's exception" means the cause of
- * the {@link ExecutionException} thrown by {@code input.get()} or, if {@code get()} throws a
- * different kind of exception, that exception itself. To avoid hiding bugs and other
- * unrecoverable errors, callers should prefer more specific types, avoiding {@code
- * Throwable.class} in particular.
- * @param fallback the {@link Function} to be called if {@code input} fails with the expected
- * exception type. The function's argument is the input's exception. "The input's exception"
- * means the cause of the {@link ExecutionException} thrown by {@code input.get()} or, if
- * {@code get()} throws a different kind of exception, that exception itself.
- * @since 19.0
- * @deprecated Use {@linkplain #catching(ListenableFuture, Class, Function, Executor) the overload
- * that requires an executor}. For identical behavior, pass {@link
- * MoreExecutors#directExecutor}, but consider whether another executor would be safer, as
- * discussed in the {@link ListenableFuture#addListener ListenableFuture.addListener}
- * documentation. This method is scheduled to be removed in July 2018.
- */
- @Deprecated
- @DoNotCall
- @Partially.GwtIncompatible("AVAILABLE but requires exceptionType to be Throwable.class")
- public static Usage examples:
- *
- * The fallback can also choose to propagate the original exception when desired:
- *
- * This overload, which does not accept an executor, uses {@code directExecutor}, a dangerous
- * choice in some cases. See the discussion in the {@link ListenableFuture#addListener
- * ListenableFuture.addListener} documentation. All its warnings about heavyweight listeners are
- * also applicable to heavyweight functions passed to this method. (Specifically, {@code
- * directExecutor} functions should avoid heavyweight operations inside {@code
- * AsyncFunction.apply}. Any heavyweight operations should occur in other threads responsible for
- * completing the returned {@code Future}.)
- *
- * @param input the primary input {@code Future}
- * @param exceptionType the exception type that triggers use of {@code fallback}. The exception
- * type is matched against the input's exception. "The input's exception" means the cause of
- * the {@link ExecutionException} thrown by {@code input.get()} or, if {@code get()} throws a
- * different kind of exception, that exception itself. To avoid hiding bugs and other
- * unrecoverable errors, callers should prefer more specific types, avoiding {@code
- * Throwable.class} in particular.
- * @param fallback the {@link AsyncFunction} to be called if {@code input} fails with the expected
- * exception type. The function's argument is the input's exception. "The input's exception"
- * means the cause of the {@link ExecutionException} thrown by {@code input.get()} or, if
- * {@code get()} throws a different kind of exception, that exception itself.
- * @since 19.0 (similar functionality in 14.0 as {@code withFallback})
- * @deprecated Use {@linkplain #catchingAsync(ListenableFuture, Class, AsyncFunction, Executor)
- * the overload that requires an executor}. For identical behavior, pass {@link
- * MoreExecutors#directExecutor}, but consider whether another executor would be safer, as
- * discussed in the {@link ListenableFuture#addListener ListenableFuture.addListener}
- * documentation. This method is scheduled to be removed in July 2018.
- */
- @CanIgnoreReturnValue // TODO(kak): @CheckReturnValue
- @Deprecated
- @DoNotCall
- @Partially.GwtIncompatible("AVAILABLE but requires exceptionType to be Throwable.class")
- public static More precisely, the returned {@code Future} takes its result from a {@code Future} produced
- * by applying the given {@code AsyncFunction} to the result of the original {@code Future}.
- * Example usage:
- *
- * This overload, which does not accept an executor, uses {@code directExecutor}, a dangerous
- * choice in some cases. See the discussion in the {@link ListenableFuture#addListener
- * ListenableFuture.addListener} documentation. All its warnings about heavyweight listeners are
- * also applicable to heavyweight functions passed to this method. (Specifically, {@code
- * directExecutor} functions should avoid heavyweight operations inside {@code
- * AsyncFunction.apply}. Any heavyweight operations should occur in other threads responsible for
- * completing the returned {@code Future}.)
- *
- * The returned {@code Future} attempts to keep its cancellation state in sync with that of the
- * input future and that of the future returned by the function. That is, if the returned {@code
- * Future} is cancelled, it will attempt to cancel the other two, and if either of the other two
- * is cancelled, the returned {@code Future} will receive a callback in which it will attempt to
- * cancel itself.
- *
- * @param input The future to transform
- * @param function A function to transform the result of the input future to the result of the
- * output future
- * @return A future that holds result of the function (if the input succeeded) or the original
- * input's failure (if not)
- * @since 19.0 (in 11.0 as {@code transform})
- * @deprecated Use {@linkplain #transformAsync(ListenableFuture, AsyncFunction, Executor) the
- * overload that requires an executor}. For identical behavior, pass {@link
- * MoreExecutors#directExecutor}, but consider whether another executor would be safer, as
- * discussed in the {@link ListenableFuture#addListener ListenableFuture.addListener}
- * documentation. This method is scheduled to be removed in July 2018.
- */
- @Deprecated
- @DoNotCall
- public static ListenableFuture This overload, which does not accept an executor, uses {@code directExecutor}, a dangerous
- * choice in some cases. See the discussion in the {@link ListenableFuture#addListener
- * ListenableFuture.addListener} documentation. All its warnings about heavyweight listeners are
- * also applicable to heavyweight functions passed to this method.
- *
- * The returned {@code Future} attempts to keep its cancellation state in sync with that of the
- * input future. That is, if the returned {@code Future} is cancelled, it will attempt to cancel
- * the input, and if the input is cancelled, the returned {@code Future} will receive a callback
- * in which it will attempt to cancel itself.
- *
- * An example use of this method is to convert a serializable object returned from an RPC into
- * a POJO.
- *
- * @param input The future to transform
- * @param function A Function to transform the results of the provided future to the results of
- * the returned future. This will be run in the thread that notifies input it is complete.
- * @return A future that holds result of the transformation.
- * @since 9.0 (in 1.0 as {@code compose})
- * @deprecated Use {@linkplain #transform(ListenableFuture, Function, Executor) the overload that
- * requires an executor}. For identical behavior, pass {@link MoreExecutors#directExecutor},
- * but consider whether another executor would be safer, as discussed in the {@link
- * ListenableFuture#addListener ListenableFuture.addListener} documentation. This method is
- * scheduled to be removed in July 2018.
- */
- @Deprecated
- @DoNotCall
- public static ListenableFuture There is no guaranteed ordering of execution of callbacks, but any callback added through
- * this method is guaranteed to be called once the computation is complete.
- *
- * Example:
- *
- * This overload, which does not accept an executor, uses {@code directExecutor}, a dangerous
- * choice in some cases. See the discussion in the {@link ListenableFuture#addListener
- * ListenableFuture.addListener} documentation. All its warnings about heavyweight listeners are
- * also applicable to heavyweight callbacks passed to this method.
- *
- * For a more general interface to attach a completion listener to a {@code Future}, see {@link
- * ListenableFuture#addListener addListener}.
- *
- * @param future The future attach the callback to.
- * @param callback The callback to invoke when {@code future} is completed.
- * @since 10.0
- * @deprecated Use {@linkplain #addCallback(ListenableFuture, FutureCallback, Executor) the
- * overload that requires an executor}. For identical behavior, pass {@link
- * MoreExecutors#directExecutor}, but consider whether another executor would be safer, as
- * discussed in the {@link ListenableFuture#addListener ListenableFuture.addListener}
- * documentation. This method is scheduled to be removed in July 2018.
- */
- @Deprecated
- @DoNotCall
- public static Usage example:
- *
- * This overload, which does not accept an executor, uses {@code directExecutor}, a dangerous
- * choice in some cases. See the discussion in the {@link ListenableFuture#addListener
- * ListenableFuture.addListener} documentation. All its warnings about heavyweight listeners are
- * also applicable to heavyweight functions passed to this method.
- *
- * @param input the primary input {@code Future}
- * @param exceptionType the exception type that triggers use of {@code fallback}. The exception
- * type is matched against the input's exception. "The input's exception" means the cause of
- * the {@link ExecutionException} thrown by {@code input.get()} or, if {@code get()} throws a
- * different kind of exception, that exception itself. To avoid hiding bugs and other
- * unrecoverable errors, callers should prefer more specific types, avoiding {@code
- * Throwable.class} in particular.
- * @param fallback the {@link Function} to be called if {@code input} fails with the expected
- * exception type. The function's argument is the input's exception. "The input's exception"
- * means the cause of the {@link ExecutionException} thrown by {@code input.get()} or, if
- * {@code get()} throws a different kind of exception, that exception itself.
- * @since 19.0
- * @deprecated Use {@linkplain #catching(ListenableFuture, Class, Function, Executor) the overload
- * that requires an executor}. For identical behavior, pass {@link
- * MoreExecutors#directExecutor}, but consider whether another executor would be safer, as
- * discussed in the {@link ListenableFuture#addListener ListenableFuture.addListener}
- * documentation. This method is scheduled to be removed in July 2018.
- */
- @Deprecated
- @DoNotCall
- @Partially.GwtIncompatible("AVAILABLE but requires exceptionType to be Throwable.class")
- public static Usage examples:
- *
- * The fallback can also choose to propagate the original exception when desired:
- *
- * This overload, which does not accept an executor, uses {@code directExecutor}, a dangerous
- * choice in some cases. See the discussion in the {@link ListenableFuture#addListener
- * ListenableFuture.addListener} documentation. All its warnings about heavyweight listeners are
- * also applicable to heavyweight functions passed to this method. (Specifically, {@code
- * directExecutor} functions should avoid heavyweight operations inside {@code
- * AsyncFunction.apply}. Any heavyweight operations should occur in other threads responsible for
- * completing the returned {@code Future}.)
- *
- * @param input the primary input {@code Future}
- * @param exceptionType the exception type that triggers use of {@code fallback}. The exception
- * type is matched against the input's exception. "The input's exception" means the cause of
- * the {@link ExecutionException} thrown by {@code input.get()} or, if {@code get()} throws a
- * different kind of exception, that exception itself. To avoid hiding bugs and other
- * unrecoverable errors, callers should prefer more specific types, avoiding {@code
- * Throwable.class} in particular.
- * @param fallback the {@link AsyncFunction} to be called if {@code input} fails with the expected
- * exception type. The function's argument is the input's exception. "The input's exception"
- * means the cause of the {@link ExecutionException} thrown by {@code input.get()} or, if
- * {@code get()} throws a different kind of exception, that exception itself.
- * @since 19.0 (similar functionality in 14.0 as {@code withFallback})
- * @deprecated Use {@linkplain #catchingAsync(ListenableFuture, Class, AsyncFunction, Executor)
- * the overload that requires an executor}. For identical behavior, pass {@link
- * MoreExecutors#directExecutor}, but consider whether another executor would be safer, as
- * discussed in the {@link ListenableFuture#addListener ListenableFuture.addListener}
- * documentation. This method is scheduled to be removed in July 2018.
- */
- @CanIgnoreReturnValue // TODO(kak): @CheckReturnValue
- @Deprecated
- @DoNotCall
- @Partially.GwtIncompatible("AVAILABLE but requires exceptionType to be Throwable.class")
- public static More precisely, the returned {@code Future} takes its result from a {@code Future} produced
- * by applying the given {@code AsyncFunction} to the result of the original {@code Future}.
- * Example usage:
- *
- * This overload, which does not accept an executor, uses {@code directExecutor}, a dangerous
- * choice in some cases. See the discussion in the {@link ListenableFuture#addListener
- * ListenableFuture.addListener} documentation. All its warnings about heavyweight listeners are
- * also applicable to heavyweight functions passed to this method. (Specifically, {@code
- * directExecutor} functions should avoid heavyweight operations inside {@code
- * AsyncFunction.apply}. Any heavyweight operations should occur in other threads responsible for
- * completing the returned {@code Future}.)
- *
- * The returned {@code Future} attempts to keep its cancellation state in sync with that of the
- * input future and that of the future returned by the function. That is, if the returned {@code
- * Future} is cancelled, it will attempt to cancel the other two, and if either of the other two
- * is cancelled, the returned {@code Future} will receive a callback in which it will attempt to
- * cancel itself.
- *
- * @param input The future to transform
- * @param function A function to transform the result of the input future to the result of the
- * output future
- * @return A future that holds result of the function (if the input succeeded) or the original
- * input's failure (if not)
- * @since 19.0 (in 11.0 as {@code transform})
- * @deprecated Use {@linkplain #transformAsync(ListenableFuture, AsyncFunction, Executor) the
- * overload that requires an executor}. For identical behavior, pass {@link
- * MoreExecutors#directExecutor}, but consider whether another executor would be safer, as
- * discussed in the {@link ListenableFuture#addListener ListenableFuture.addListener}
- * documentation. This method is scheduled to be removed in July 2018.
- */
- @Deprecated
- @DoNotCall
- public static ListenableFuture This overload, which does not accept an executor, uses {@code directExecutor}, a dangerous
- * choice in some cases. See the discussion in the {@link ListenableFuture#addListener
- * ListenableFuture.addListener} documentation. All its warnings about heavyweight listeners are
- * also applicable to heavyweight functions passed to this method.
- *
- * The returned {@code Future} attempts to keep its cancellation state in sync with that of the
- * input future. That is, if the returned {@code Future} is cancelled, it will attempt to cancel
- * the input, and if the input is cancelled, the returned {@code Future} will receive a callback
- * in which it will attempt to cancel itself.
- *
- * An example use of this method is to convert a serializable object returned from an RPC into
- * a POJO.
- *
- * @param input The future to transform
- * @param function A Function to transform the results of the provided future to the results of
- * the returned future. This will be run in the thread that notifies input it is complete.
- * @return A future that holds result of the transformation.
- * @since 9.0 (in 1.0 as {@code compose})
- * @deprecated Use {@linkplain #transform(ListenableFuture, Function, Executor) the overload that
- * requires an executor}. For identical behavior, pass {@link MoreExecutors#directExecutor},
- * but consider whether another executor would be safer, as discussed in the {@link
- * ListenableFuture#addListener ListenableFuture.addListener} documentation. This method is
- * scheduled to be removed in July 2018.
- */
- @Deprecated
- @DoNotCall
- public static ListenableFuture There is no guaranteed ordering of execution of callbacks, but any callback added through
- * this method is guaranteed to be called once the computation is complete.
- *
- * Example:
- *
- * This overload, which does not accept an executor, uses {@code directExecutor}, a dangerous
- * choice in some cases. See the discussion in the {@link ListenableFuture#addListener
- * ListenableFuture.addListener} documentation. All its warnings about heavyweight listeners are
- * also applicable to heavyweight callbacks passed to this method.
- *
- * For a more general interface to attach a completion listener to a {@code Future}, see {@link
- * ListenableFuture#addListener addListener}.
- *
- * @param future The future attach the callback to.
- * @param callback The callback to invoke when {@code future} is completed.
- * @since 10.0
- * @deprecated Use {@linkplain #addCallback(ListenableFuture, FutureCallback, Executor) the
- * overload that requires an executor}. For identical behavior, pass {@link
- * MoreExecutors#directExecutor}, but consider whether another executor would be safer, as
- * discussed in the {@link ListenableFuture#addListener ListenableFuture.addListener}
- * documentation. This method is scheduled to be removed in July 2018.
- */
- @Deprecated
- @DoNotCall
- public static {@code
- * ListenableFuture
- *
- * {@code
- * ListenableFuture
- *
- * {@code
- * ListenableFuture
- *
- * {@code
- * ListenableFuture
- *
- * > rowsFuture =
- * transform(queryFuture, QueryResult::getRows);
- * }
{@code
- * ListenableFuture
- *
- * {@code
- * ListenableFuture
- *
- * {@code
- * ListenableFuture
- *
- * {@code
- * ListenableFuture
- *
- * {@code
- * ListenableFuture
- *
- * {@code
- * ListenableFuture
- *
- * > rowsFuture =
- * transform(queryFuture, QueryResult::getRows);
- * }
{@code
- * ListenableFuture
- *
- *