Skip to content

Commit

Permalink
fix: add javadoc for ApiFutures (#1609)
Browse files Browse the repository at this point in the history 
* fix: add javadoc for `ApiFutures`

* format doc

* revert code change

* add returns tag

* change to one callback in comment

* format
  • Loading branch information
@JoeWang1127
JoeWang1127 authored Apr 6, 2023
1 parent 7444fd2 commit 4bb0a5e
Showing 1 changed file with 178 additions and 20 deletions.
198 changes: 178 additions & 20 deletions api-common-java/src/main/java/com/google/api/core/ApiFutures.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,18 +45,35 @@
public final class ApiFutures {
private ApiFutures() {}

/*
* @deprecated Use {@linkplain #addCallback(ApiFuture, ApiFutureCallback, Executor) the
* overload that requires an executor}. For identical behavior, pass {@link
* com.google.common.util.concurrent.MoreExecutors#directExecutor}, but consider whether
* another executor would be safer.
/**
* Registers a callback to be run when the {@link ApiFuture}'s computation is complete or, if the
* computation is already complete, immediately.
*
* @param future The future attach the callback to
* @param callback The callback to invoke when future is completed
* @deprecated Use {@linkplain #addCallback(ApiFuture, ApiFutureCallback, Executor) the overload
* that requires an executor}. For identical behavior, pass {@link
* com.google.common.util.concurrent.MoreExecutors#directExecutor}, but consider whether
* another executor would be safer.
*/
@Deprecated
public static <V> void addCallback(
final ApiFuture<V> future, final ApiFutureCallback<? super V> callback) {
addCallback(future, callback, directExecutor());
}

/**
* Registers a callback to be run when the {@link ApiFuture}'s computation is complete or, if the
* computation is already complete, immediately.
*
* <p>Note that this method is a delegate of {@link Futures#addCallback(ListenableFuture,
* FutureCallback, Executor)}.
*
* @param future The future attach the callback to
* @param callback The callback to invoke when future is completed
* @param executor The executor to run callback when the future completes
* @see Futures#addCallback(ListenableFuture, FutureCallback, Executor)
*/
public static <V> void addCallback(
final ApiFuture<V> future, final ApiFutureCallback<? super V> callback, Executor executor) {
Futures.addCallback(
Expand All @@ -75,11 +92,20 @@ public void onSuccess(V v) {
executor);
}

/*
* @deprecated Use {@linkplain #catching(ApiFuture, Class, ApiFunction, Executor) the
* overload that requires an executor}. For identical behavior, pass {@link
* com.google.common.util.concurrent.MoreExecutors#directExecutor}, but consider whether
* another executor would be safer.
/**
* Returns an {@link ApiFuture} whose result is taken from the given primary input or, if the
* primary input fails with the given exceptionType, from the result provided by the callback.
*
* @param input The primary input {@code ApiFuture}
* @param exceptionType The exception type that triggers use of {@code fallback}
* @param callback The {@link ApiFunction} to be called if input fails with the expected exception
* type
* @return A future whose result is taken either from the given {@code input} or by the {@code
* callback}
* @deprecated Use {@linkplain #catching(ApiFuture, Class, ApiFunction, Executor) the overload
* that requires an executor}. For identical behavior, pass {@link
* com.google.common.util.concurrent.MoreExecutors#directExecutor}, but consider whether
* another executor would be safer.
*/
@Deprecated
public static <V, X extends Throwable> ApiFuture<V> catching(
Expand All @@ -89,6 +115,22 @@ public static <V, X extends Throwable> ApiFuture<V> catching(
return catching(input, exceptionType, callback, directExecutor());
}

/**
* Returns an {@link ApiFuture} whose result is taken from the given primary input or, if the
* primary input fails with the given exceptionType, from the result provided by the callback.
*
* <p>Note that this method is a delegate of {@link Futures#catching(ListenableFuture, Class,
* Function, Executor)}.
*
* @param input The primary input {@code ApiFuture}
* @param exceptionType The exception type that triggers use of {@code fallback}
* @param callback The {@link ApiFunction} to be called if input fails with the expected exception
* type
* @param executor The executor that runs {@code fallback} if {@code input} fails
* @return A future whose result is taken either from the given {@code input} or by the {@code
* callback}
* @see Futures#catching(ListenableFuture, Class, Function, Executor)
*/
public static <V, X extends Throwable> ApiFuture<V> catching(
ApiFuture<? extends V> input,
Class<X> exceptionType,
Expand All @@ -103,6 +145,22 @@ public static <V, X extends Throwable> ApiFuture<V> catching(
return new ListenableFutureToApiFuture<V>(catchingFuture);
}

/**
* Returns a {@link ApiFuture} whose result is taken from the given primary input or, if the
* primary input fails with the given exceptionType, from the result provided by the callback.
*
* <p>Note that this method is a delegate of {@link Futures#catchingAsync(ListenableFuture, Class,
* AsyncFunction, Executor)}
*
* @param input The primary input {@code ApiFuture}
* @param exceptionType The exception type that triggers use of {@code fallback}.
* @param callback The {@link ApiAsyncFunction} to be called if {@code input} fails with the
* expected * exception type.
* @param executor The executor that runs {@code fallback} if {@code input} fails
* @return A future whose result is taken either from the given {@code input} or by the {@code
* callback}
* @see Futures#catchingAsync(ListenableFuture, Class, AsyncFunction, Executor)
*/
@BetaApi
public static <V, X extends Throwable> ApiFuture<V> catchingAsync(
ApiFuture<V> input,
Expand All @@ -124,30 +182,78 @@ public ListenableFuture<V> apply(X exception) throws Exception {
return new ListenableFutureToApiFuture<>(catchingFuture);
}

/**
* Creates a {@code ApiFuture} which has its value set immediately upon construction.
*
* <p>Note that this method is a delegate of {@link Futures#immediateFuture(Object)}.
*
* @param value The value set to the {@code ApiFuture} upon construction
* @return A future that holds {@code value}
* @see Futures#immediateFuture(Object)
*/
public static <V> ApiFuture<V> immediateFuture(V value) {
return new ListenableFutureToApiFuture<>(Futures.<V>immediateFuture(value));
}

/**
* Returns a {@code ApiFuture} which has an exception set immediately upon construction.
*
* <p>Note that this method is a delegate of {@link Futures#immediateFailedFuture(Throwable)}.
*
* @param throwable The exception set to the {@code ApiFuture} upon construction
* @return A future that holds an exception
* @see Futures#immediateFailedFuture(Throwable)
*/
public static <V> ApiFuture<V> immediateFailedFuture(Throwable throwable) {
return new ListenableFutureToApiFuture<V>(Futures.<V>immediateFailedFuture(throwable));
}

/**
* Creates a {@code ApiFuture} which is cancelled immediately upon construction, so that {@code
* isCancelled()} always returns {@code true}.
*
* <p>Note that this method is a delegate of {@link Futures#immediateCancelledFuture()}.
*
* @return A cancelled future
* @see Futures#immediateCancelledFuture()
*/
public static <V> ApiFuture<V> immediateCancelledFuture() {
return new ListenableFutureToApiFuture<V>(Futures.<V>immediateCancelledFuture());
}

/*
* @deprecated Use {@linkplain #transform(ApiFuture, ApiFunction, Executor) the
* overload that requires an executor}. For identical behavior, pass {@link
* com.google.common.util.concurrent.MoreExecutors#directExecutor}, but consider whether
* another executor would be safer.
/**
* Returns a new {@code ApiFuture} whose result is derived from the result of the given {@code
* ApiFuture}.
*
* @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
* @return A future that holds result of the transformation
* @deprecated Use {@linkplain #transform(ApiFuture, ApiFunction, Executor) the overload that
* requires an executor}. For identical behavior, pass {@link
* com.google.common.util.concurrent.MoreExecutors#directExecutor}, but consider whether
* another executor would be safer.
*/
@Deprecated
public static <V, X> ApiFuture<X> transform(
ApiFuture<? extends V> input, final ApiFunction<? super V, ? extends X> function) {
return transform(input, function, directExecutor());
}

/**
* Returns a new {@code ApiFuture} whose result is derived from the result of the given {@code
* ApiFuture}.
*
* <p>Note that this method is a delegate of {@link Futures#transform(ListenableFuture, Function,
* Executor)}.
*
* @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.
* @param executor Executor to run the function in.
* @return A future that holds result of the transformation
* @see Futures#transform(ListenableFuture, Function, Executor)
*/
public static <V, X> ApiFuture<X> transform(
ApiFuture<? extends V> input,
final ApiFunction<? super V, ? extends X> function,
Expand All @@ -159,6 +265,18 @@ public static <V, X> ApiFuture<X> transform(
executor));
}

/**
* Creates a new {@code ApiFuture} whose value is a list containing the values of all its input
* futures, if all succeed.
*
* <p>The list of results is in the same order as the input list.
*
* <p>Note that this method is a delegate of {@link Futures#allAsList(Iterable)}.
*
* @param futures Futures to combine
* @return A future that provides a list of the results of the component futures
* @see Futures#allAsList(Iterable)
*/
public static <V> ApiFuture<List<V>> allAsList(
Iterable<? extends ApiFuture<? extends V>> futures) {
return new ListenableFutureToApiFuture<>(
Expand All @@ -172,6 +290,21 @@ public ListenableFuture<? extends V> apply(ApiFuture<? extends V> apiFuture) {
})));
}

/**
* Creates a new {@code ApiFuture} whose value is a list containing the values of all its
* successful input futures. The list of results is in the same order as the input list, and if
* any of the provided futures fails or is canceled, its corresponding position will contain
* {@code null} (which is indistinguishable from the future having a successful value of {@code
* null}).
*
* <p>The list of results is in the same order as the input list.
*
* <p>Note that this method is a delegate of {@link Futures#successfulAsList(Iterable)}.
*
* @param futures Futures to combine
* @return A future that provides a list of the results of the component futures
* @see Futures#successfulAsList(Iterable)
*/
@BetaApi
public static <V> ApiFuture<List<V>> successfulAsList(
Iterable<? extends ApiFuture<? extends V>> futures) {
Expand All @@ -186,18 +319,43 @@ public ListenableFuture<? extends V> apply(ApiFuture<? extends V> apiFuture) {
})));
}

/*
* @deprecated Use {@linkplain #transformAsync(ApiFuture, ApiFunction, Executor) the
* overload that requires an executor}. For identical behavior, pass {@link
* com.google.common.util.concurrent.MoreExecutors#directExecutor}, but consider whether
* another executor would be safer.
/**
* Returns a new {@code ApiFuture} whose result is asynchronously derived from the result of the
* given {@code ApiFuture}. If the given {@code Future} fails, the returned {@code ApiFuture}
* fails with the same exception (and the function is not invoked).
*
* @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)
* @deprecated Use {@linkplain #transformAsync(ApiFuture, ApiAsyncFunction, Executor)}, the
* overload that requires an executor. For identical behavior, pass {@link
* com.google.common.util.concurrent.MoreExecutors#directExecutor}, but consider whether
* another executor would be safer.
*/
@Deprecated
public static <I, O> ApiFuture<O> transformAsync(
ApiFuture<I> input, final ApiAsyncFunction<I, O> function) {
return transformAsync(input, function, directExecutor());
}

/**
* Returns a new {@code ApiFuture} whose result is asynchronously derived from the result of the
* given {@code ApiFuture}. If the given {@code Future} fails, the returned {@code ApiFuture}
* fails with the same exception (and the function is not invoked).
*
* <p>Note that this method is a delegate of {@link Futures#transformAsync(ListenableFuture,
* AsyncFunction, Executor)}.
*
* @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
* @param executor Executor to run the function in.
* @return A future that holds result of the function (if the input succeeded) or the original
* input's failure (if not)
* @see Futures#transformAsync(ListenableFuture, AsyncFunction, Executor)
*/
public static <I, O> ApiFuture<O> transformAsync(
ApiFuture<I> input, final ApiAsyncFunction<I, O> function, Executor executor) {
ListenableFuture<I> listenableInput = listenableFutureForApiFuture(input);
Expand Down

0 comments on commit 4bb0a5e

Please sign in to comment.