Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

fix: add javadoc for ApiFutures #1609

Merged
merged 6 commits into from
Apr 6, 2023
Merged

fix: add javadoc for ApiFutures #1609

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e60e1c9
fix: add javadoc for `ApiFutures`
JoeWang1127 Apr 5, 2023
21cfd48
format doc
JoeWang1127 Apr 5, 2023
253db9a
revert code change
JoeWang1127 Apr 5, 2023
cba45c0
add returns tag
JoeWang1127 Apr 5, 2023
a8b70bd
change to one callback in comment
JoeWang1127 Apr 6, 2023
3981a46
format
JoeWang1127 Apr 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
198 changes: 178 additions & 20 deletions api-common-java/src/main/java/com/google/api/core/ApiFutures.java
View file
Open in desktop
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) {
burkedavison marked this conversation as resolved.
Show resolved Hide resolved
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