From e60e1c91776e0be96177a016eb98137ae78972e7 Mon Sep 17 00:00:00 2001 From: Joe Wang Date: Wed, 5 Apr 2023 15:56:33 -0400 Subject: [PATCH 1/6] fix: add javadoc for `ApiFutures` --- .../java/com/google/api/core/ApiFutures.java | 169 ++++++++++++++---- 1 file changed, 136 insertions(+), 33 deletions(-) diff --git a/api-common-java/src/main/java/com/google/api/core/ApiFutures.java b/api-common-java/src/main/java/com/google/api/core/ApiFutures.java index 2189a5e533..ee67e2f90b 100644 --- a/api-common-java/src/main/java/com/google/api/core/ApiFutures.java +++ b/api-common-java/src/main/java/com/google/api/core/ApiFutures.java @@ -45,7 +45,7 @@ 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 @@ -57,6 +57,17 @@ public static void addCallback( addCallback(future, callback, directExecutor()); } + /** + * Registers separate success and failure callbacks to be run when the {@link ApiFuture}'s computation + * is complete or, if the computation is already complete, immediately. + * + *

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 void addCallback( final ApiFuture future, final ApiFutureCallback callback, Executor executor) { Futures.addCallback( @@ -75,7 +86,7 @@ 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 @@ -89,6 +100,19 @@ public static ApiFuture catching( return catching(input, exceptionType, callback, directExecutor()); } + /** + * 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 fallback. + * + *

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 + * + * @see Futures#catching(ListenableFuture, Class, Function, Executor) + */ public static ApiFuture catching( ApiFuture input, Class exceptionType, @@ -100,9 +124,23 @@ public static ApiFuture catching( exceptionType, new ApiFunctionToGuavaFunction(callback), executor); - return new ListenableFutureToApiFuture(catchingFuture); + return new ListenableFutureToApiFuture<>(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 fallback. + * + *

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 + * + * @see Futures#catchingAsync(ListenableFuture, Class, AsyncFunction, Executor) + */ @BetaApi public static ApiFuture catchingAsync( ApiFuture input, @@ -113,30 +151,49 @@ public static ApiFuture catchingAsync( Futures.catchingAsync( listenableFutureForApiFuture(input), exceptionType, - new AsyncFunction() { - @Override - public ListenableFuture apply(X exception) throws Exception { - ApiFuture result = callback.apply(exception); - return listenableFutureForApiFuture(result); - } + exception -> { + ApiFuture result = callback.apply(exception); + return listenableFutureForApiFuture(result); }, executor); return new ListenableFutureToApiFuture<>(catchingFuture); } + /** + * Creates a {@code ApiFuture} which has its value set immediately upon construction. + * + *

Note that this method is a delegate of {@link Futures#immediateFuture(Object)}. + * + * @see Futures#immediateFuture(Object) + */ public static ApiFuture immediateFuture(V value) { - return new ListenableFutureToApiFuture<>(Futures.immediateFuture(value)); + return new ListenableFutureToApiFuture<>(Futures.immediateFuture(value)); } + /** + * Returns a {@code ApiFuture} which has an exception set immediately upon construction. + * + *

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

Note that this method is a delegate of {@link Futures#immediateCancelledFuture()}. + * + * @see Futures#immediateCancelledFuture() + */ public static ApiFuture immediateCancelledFuture() { - return new ListenableFutureToApiFuture(Futures.immediateCancelledFuture()); + return new ListenableFutureToApiFuture<>(Futures.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 @@ -148,6 +205,19 @@ public static ApiFuture transform( return transform(input, function, directExecutor()); } + /** + * Returns a new {@code ApiFuture} whose result is derived from the result of the given {@code ApiFuture}. + * + *

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 ApiFuture transform( ApiFuture input, final ApiFunction function, @@ -159,19 +229,44 @@ public static ApiFuture transform( executor)); } + /** + * Creates a new {@code ApiFuture} whose value is a list containing the values of all its + * input futures, if all succeed. + * + *

The list of results is in the same order as the input list. + * + *

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 ApiFuture> allAsList( Iterable> futures) { return new ListenableFutureToApiFuture<>( Futures.allAsList( Iterables.transform( futures, - new Function, ListenableFuture>() { - public ListenableFuture apply(ApiFuture apiFuture) { - return listenableFutureForApiFuture(apiFuture); - } - }))); + (Function, ListenableFuture>) ApiFutures::listenableFutureForApiFuture))); } + /** + * 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}). + * + *

The list of results is in the same order as the input list. + * + *

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 ApiFuture> successfulAsList( Iterable> futures) { @@ -179,16 +274,13 @@ public static ApiFuture> successfulAsList( Futures.successfulAsList( Iterables.transform( futures, - new Function, ListenableFuture>() { - public ListenableFuture apply(ApiFuture apiFuture) { - return listenableFutureForApiFuture(apiFuture); - } - }))); + (Function, ListenableFuture>) ApiFutures::listenableFutureForApiFuture))); } - /* - * @deprecated Use {@linkplain #transformAsync(ApiFuture, ApiFunction, Executor) the - * overload that requires an executor}. For identical behavior, pass {@link + /** + * @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. */ @@ -198,18 +290,29 @@ public static ApiFuture transformAsync( 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). + * + *

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 ApiFuture transformAsync( ApiFuture input, final ApiAsyncFunction function, Executor executor) { ListenableFuture listenableInput = listenableFutureForApiFuture(input); ListenableFuture listenableOutput = Futures.transformAsync( listenableInput, - new AsyncFunction() { - @Override - public ListenableFuture apply(I input) throws Exception { - return listenableFutureForApiFuture(function.apply(input)); - } - }, + anotherInput -> listenableFutureForApiFuture(function.apply(anotherInput)), executor); return new ListenableFutureToApiFuture<>(listenableOutput); } @@ -220,7 +323,7 @@ private static ListenableFuture listenableFutureForApiFuture(ApiFuture // prefer to use the wrapped ListenableFuture to reduce the number of layers listenableFuture = ((AbstractApiFuture) apiFuture).getInternalListenableFuture(); } else { - listenableFuture = new ApiFutureToListenableFuture(apiFuture); + listenableFuture = new ApiFutureToListenableFuture<>(apiFuture); } return listenableFuture; } From 21cfd489cd3704c45759e3ac5465962dd3f40ae2 Mon Sep 17 00:00:00 2001 From: Joe Wang Date: Wed, 5 Apr 2023 15:59:35 -0400 Subject: [PATCH 2/6] format doc --- .../java/com/google/api/core/ApiFutures.java | 120 +++++++++--------- 1 file changed, 61 insertions(+), 59 deletions(-) diff --git a/api-common-java/src/main/java/com/google/api/core/ApiFutures.java b/api-common-java/src/main/java/com/google/api/core/ApiFutures.java index ee67e2f90b..a4f3e0327a 100644 --- a/api-common-java/src/main/java/com/google/api/core/ApiFutures.java +++ b/api-common-java/src/main/java/com/google/api/core/ApiFutures.java @@ -46,10 +46,10 @@ 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. + * @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 void addCallback( @@ -58,14 +58,15 @@ public static void addCallback( } /** - * Registers separate success and failure callbacks to be run when the {@link ApiFuture}'s computation - * is complete or, if the computation is already complete, immediately. + * Registers separate success and failure callbacks to be run when the {@link ApiFuture}'s + * computation is complete or, if the computation is already complete, immediately. + * + *

Note that this method is a delegate of {@link Futures#addCallback(ListenableFuture, + * FutureCallback, Executor)}. * - *

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 void addCallback( @@ -87,10 +88,10 @@ public void onSuccess(V v) { } /** - * @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 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 ApiFuture catching( @@ -101,16 +102,17 @@ public static ApiFuture catching( } /** - * 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 fallback. + * 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 fallback. * - *

Note that this method is a delegate of {@link Futures#catching(ListenableFuture, Class, Function, Executor)}. + *

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 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 - * * @see Futures#catching(ListenableFuture, Class, Function, Executor) */ public static ApiFuture catching( @@ -128,17 +130,17 @@ public static ApiFuture catching( } /** - * 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 fallback. + * 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 fallback. * - *

Note that this method is a delegate of {@link Futures#catchingAsync(ListenableFuture, Class, AsyncFunction, Executor)} + *

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 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 - * * @see Futures#catchingAsync(ListenableFuture, Class, AsyncFunction, Executor) */ @BetaApi @@ -161,10 +163,10 @@ public static ApiFuture catchingAsync( /** * Creates a {@code ApiFuture} which has its value set immediately upon construction. - * - *

Note that this method is a delegate of {@link Futures#immediateFuture(Object)}. * - * @see Futures#immediateFuture(Object) + *

Note that this method is a delegate of {@link Futures#immediateFuture(Object)}. + * + * @see Futures#immediateFuture(Object) */ public static ApiFuture immediateFuture(V value) { return new ListenableFutureToApiFuture<>(Futures.immediateFuture(value)); @@ -173,20 +175,20 @@ public static ApiFuture immediateFuture(V value) { /** * Returns a {@code ApiFuture} which has an exception set immediately upon construction. * - *

Note that this method is a delegate of {@link Futures#immediateFailedFuture(Throwable)}. - * - * @see Futures#immediateFailedFuture(Throwable) + *

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

Note that this method is a delegate of {@link Futures#immediateCancelledFuture()}. - * + * Creates a {@code ApiFuture} which is cancelled immediately upon construction, so that {@code + * isCancelled()} always returns {@code true}. + * + *

Note that this method is a delegate of {@link Futures#immediateCancelledFuture()}. + * * @see Futures#immediateCancelledFuture() */ public static ApiFuture immediateCancelledFuture() { @@ -194,10 +196,10 @@ public static ApiFuture 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. + * @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 ApiFuture transform( @@ -206,16 +208,17 @@ public static ApiFuture transform( } /** - * Returns a new {@code ApiFuture} whose result is derived from the result of the given {@code ApiFuture}. + * Returns a new {@code ApiFuture} whose result is derived from the result of the given {@code + * ApiFuture}. * - *

Note that this method is a delegate of {@link Futures#transform(ListenableFuture, Function, Executor)}. + *

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 ApiFuture transform( @@ -230,8 +233,8 @@ public static ApiFuture transform( } /** - * Creates a new {@code ApiFuture} whose value is a list containing the values of all its - * input futures, if all succeed. + * Creates a new {@code ApiFuture} whose value is a list containing the values of all its input + * futures, if all succeed. * *

The list of results is in the same order as the input list. * @@ -239,7 +242,6 @@ public static ApiFuture transform( * * @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 ApiFuture> allAsList( @@ -248,7 +250,8 @@ public static ApiFuture> allAsList( Futures.allAsList( Iterables.transform( futures, - (Function, ListenableFuture>) ApiFutures::listenableFutureForApiFuture))); + (Function, ListenableFuture>) + ApiFutures::listenableFutureForApiFuture))); } /** @@ -258,13 +261,12 @@ public static ApiFuture> allAsList( * {@code null} (which is indistinguishable from the future having a successful value of {@code * null}). * - *

The list of results is in the same order as the input list. + *

The list of results is in the same order as the input list. * - *

Note that this method is a delegate of {@link Futures#successfulAsList(Iterable)}. + *

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 @@ -274,15 +276,15 @@ public static ApiFuture> successfulAsList( Futures.successfulAsList( Iterables.transform( futures, - (Function, ListenableFuture>) ApiFutures::listenableFutureForApiFuture))); + (Function, ListenableFuture>) + ApiFutures::listenableFutureForApiFuture))); } /** * @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. + * 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 ApiFuture transformAsync( @@ -292,18 +294,18 @@ public static ApiFuture transformAsync( /** * 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). + * given {@code ApiFuture}. If the given {@code Future} fails, the returned {@code ApiFuture} + * fails with the same exception (and the function is not invoked). * - *

Note that this method is a delegate of {@link Futures#transformAsync(ListenableFuture, AsyncFunction, Executor)}. + *

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 + * 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) - * + * input's failure (if not) * @see Futures#transformAsync(ListenableFuture, AsyncFunction, Executor) */ public static ApiFuture transformAsync( From 253db9abec4a22a9cf705610832efad0a2b8b66e Mon Sep 17 00:00:00 2001 From: Joe Wang Date: Wed, 5 Apr 2023 16:18:33 -0400 Subject: [PATCH 3/6] revert code change --- .../java/com/google/api/core/ApiFutures.java | 40 +++++++++++++------ 1 file changed, 27 insertions(+), 13 deletions(-) diff --git a/api-common-java/src/main/java/com/google/api/core/ApiFutures.java b/api-common-java/src/main/java/com/google/api/core/ApiFutures.java index a4f3e0327a..e66dc31a15 100644 --- a/api-common-java/src/main/java/com/google/api/core/ApiFutures.java +++ b/api-common-java/src/main/java/com/google/api/core/ApiFutures.java @@ -126,7 +126,7 @@ public static ApiFuture catching( exceptionType, new ApiFunctionToGuavaFunction(callback), executor); - return new ListenableFutureToApiFuture<>(catchingFuture); + return new ListenableFutureToApiFuture(catchingFuture); } /** @@ -153,9 +153,12 @@ public static ApiFuture catchingAsync( Futures.catchingAsync( listenableFutureForApiFuture(input), exceptionType, - exception -> { - ApiFuture result = callback.apply(exception); - return listenableFutureForApiFuture(result); + new AsyncFunction() { + @Override + public ListenableFuture apply(X exception) throws Exception { + ApiFuture result = callback.apply(exception); + return listenableFutureForApiFuture(result); + } }, executor); return new ListenableFutureToApiFuture<>(catchingFuture); @@ -169,7 +172,7 @@ public static ApiFuture catchingAsync( * @see Futures#immediateFuture(Object) */ public static ApiFuture immediateFuture(V value) { - return new ListenableFutureToApiFuture<>(Futures.immediateFuture(value)); + return new ListenableFutureToApiFuture<>(Futures.immediateFuture(value)); } /** @@ -180,7 +183,7 @@ public static ApiFuture immediateFuture(V value) { * @see Futures#immediateFailedFuture(Throwable) */ public static ApiFuture immediateFailedFuture(Throwable throwable) { - return new ListenableFutureToApiFuture<>(Futures.immediateFailedFuture(throwable)); + return new ListenableFutureToApiFuture(Futures.immediateFailedFuture(throwable)); } /** @@ -192,7 +195,7 @@ public static ApiFuture immediateFailedFuture(Throwable throwable) { * @see Futures#immediateCancelledFuture() */ public static ApiFuture immediateCancelledFuture() { - return new ListenableFutureToApiFuture<>(Futures.immediateCancelledFuture()); + return new ListenableFutureToApiFuture(Futures.immediateCancelledFuture()); } /** @@ -250,8 +253,11 @@ public static ApiFuture> allAsList( Futures.allAsList( Iterables.transform( futures, - (Function, ListenableFuture>) - ApiFutures::listenableFutureForApiFuture))); + new Function, ListenableFuture>() { + public ListenableFuture apply(ApiFuture apiFuture) { + return listenableFutureForApiFuture(apiFuture); + } + }))); } /** @@ -276,8 +282,11 @@ public static ApiFuture> successfulAsList( Futures.successfulAsList( Iterables.transform( futures, - (Function, ListenableFuture>) - ApiFutures::listenableFutureForApiFuture))); + new Function, ListenableFuture>() { + public ListenableFuture apply(ApiFuture apiFuture) { + return listenableFutureForApiFuture(apiFuture); + } + }))); } /** @@ -314,7 +323,12 @@ public static ApiFuture transformAsync( ListenableFuture listenableOutput = Futures.transformAsync( listenableInput, - anotherInput -> listenableFutureForApiFuture(function.apply(anotherInput)), + new AsyncFunction() { + @Override + public ListenableFuture apply(I input) throws Exception { + return listenableFutureForApiFuture(function.apply(input)); + } + }, executor); return new ListenableFutureToApiFuture<>(listenableOutput); } @@ -325,7 +339,7 @@ private static ListenableFuture listenableFutureForApiFuture(ApiFuture // prefer to use the wrapped ListenableFuture to reduce the number of layers listenableFuture = ((AbstractApiFuture) apiFuture).getInternalListenableFuture(); } else { - listenableFuture = new ApiFutureToListenableFuture<>(apiFuture); + listenableFuture = new ApiFutureToListenableFuture(apiFuture); } return listenableFuture; } From cba45c0591e2d741d66102a54a3ccc499a3348a4 Mon Sep 17 00:00:00 2001 From: Joe Wang Date: Wed, 5 Apr 2023 17:35:45 -0400 Subject: [PATCH 4/6] add returns tag --- .../java/com/google/api/core/ApiFutures.java | 57 ++++++++++++++++--- 1 file changed, 48 insertions(+), 9 deletions(-) diff --git a/api-common-java/src/main/java/com/google/api/core/ApiFutures.java b/api-common-java/src/main/java/com/google/api/core/ApiFutures.java index e66dc31a15..cd4608b369 100644 --- a/api-common-java/src/main/java/com/google/api/core/ApiFutures.java +++ b/api-common-java/src/main/java/com/google/api/core/ApiFutures.java @@ -46,6 +46,11 @@ public final class ApiFutures { private ApiFutures() {} /** + * Registers separate success and failure callbacks 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 @@ -64,9 +69,9 @@ public static void addCallback( *

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. + * @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 void addCallback( @@ -88,6 +93,15 @@ public void onSuccess(V v) { } /** + * 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 @@ -102,17 +116,19 @@ public static ApiFuture catching( } /** - * 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 fallback. + * 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. * *

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 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. + * 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 ApiFuture catching( @@ -131,7 +147,7 @@ public static ApiFuture catching( /** * 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 fallback. + * primary input fails with the given exceptionType, from the result provided by the callback. * *

Note that this method is a delegate of {@link Futures#catchingAsync(ListenableFuture, Class, * AsyncFunction, Executor)} @@ -141,6 +157,8 @@ public static ApiFuture catching( * @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 @@ -169,6 +187,8 @@ public ListenableFuture apply(X exception) throws Exception { * *

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 ApiFuture immediateFuture(V value) { @@ -180,6 +200,8 @@ public static ApiFuture immediateFuture(V value) { * *

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 ApiFuture immediateFailedFuture(Throwable throwable) { @@ -192,6 +214,7 @@ public static ApiFuture immediateFailedFuture(Throwable throwable) { * *

Note that this method is a delegate of {@link Futures#immediateCancelledFuture()}. * + * @return A cancelled future * @see Futures#immediateCancelledFuture() */ public static ApiFuture immediateCancelledFuture() { @@ -199,6 +222,13 @@ public static ApiFuture immediateCancelledFuture() { } /** + * 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 @@ -221,7 +251,7 @@ public static ApiFuture 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. + * @return A future that holds result of the transformation * @see Futures#transform(ListenableFuture, Function, Executor) */ public static ApiFuture transform( @@ -290,6 +320,15 @@ public ListenableFuture apply(ApiFuture apiFuture) { } /** + * 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 From a8b70bd998f9f69f2d5d9db4cdf037a211335018 Mon Sep 17 00:00:00 2001 From: Joe Wang Date: Thu, 6 Apr 2023 13:44:28 -0400 Subject: [PATCH 5/6] change to one callback in comment --- .../src/main/java/com/google/api/core/ApiFutures.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-common-java/src/main/java/com/google/api/core/ApiFutures.java b/api-common-java/src/main/java/com/google/api/core/ApiFutures.java index cd4608b369..f7a948b93d 100644 --- a/api-common-java/src/main/java/com/google/api/core/ApiFutures.java +++ b/api-common-java/src/main/java/com/google/api/core/ApiFutures.java @@ -46,7 +46,7 @@ public final class ApiFutures { private ApiFutures() {} /** - * Registers separate success and failure callbacks to be run when the {@link ApiFuture}'s + * 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 @@ -63,7 +63,7 @@ public static void addCallback( } /** - * Registers separate success and failure callbacks to be run when the {@link ApiFuture}'s + * Registers a callback to be run when the {@link ApiFuture}'s * computation is complete or, if the computation is already complete, immediately. * *

Note that this method is a delegate of {@link Futures#addCallback(ListenableFuture, From 3981a46e091eba0b5a7e0bf8915766826387cdad Mon Sep 17 00:00:00 2001 From: Joe Wang Date: Thu, 6 Apr 2023 13:46:01 -0400 Subject: [PATCH 6/6] format --- .../src/main/java/com/google/api/core/ApiFutures.java | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api-common-java/src/main/java/com/google/api/core/ApiFutures.java b/api-common-java/src/main/java/com/google/api/core/ApiFutures.java index f7a948b93d..4c263ce845 100644 --- a/api-common-java/src/main/java/com/google/api/core/ApiFutures.java +++ b/api-common-java/src/main/java/com/google/api/core/ApiFutures.java @@ -46,8 +46,8 @@ public final class ApiFutures { private ApiFutures() {} /** - * Registers a callback to be run when the {@link ApiFuture}'s - * computation is complete or, if the computation is already complete, immediately. + * 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 @@ -63,8 +63,8 @@ public static void addCallback( } /** - * Registers a callback to be run when the {@link ApiFuture}'s - * computation is complete or, if the computation is already complete, immediately. + * Registers a callback to be run when the {@link ApiFuture}'s computation is complete or, if the + * computation is already complete, immediately. * *

Note that this method is a delegate of {@link Futures#addCallback(ListenableFuture, * FutureCallback, Executor)}.