From c37225bc95598f68c9e76e5ef17c201a072e8b8a Mon Sep 17 00:00:00 2001 From: Noa Resare Date: Mon, 23 Feb 2015 19:38:30 +0100 Subject: [PATCH] Simplified and cleaned up the javadoc of the transform family of functions --- .../com/spotify/futures/FuturesExtra.java | 240 +++++++++--------- 1 file changed, 123 insertions(+), 117 deletions(-) diff --git a/src/main/java/com/spotify/futures/FuturesExtra.java b/src/main/java/com/spotify/futures/FuturesExtra.java index f5b7b00..c38d307 100644 --- a/src/main/java/com/spotify/futures/FuturesExtra.java +++ b/src/main/java/com/spotify/futures/FuturesExtra.java @@ -159,16 +159,15 @@ public void onFailure(Throwable t) { } /** - * Transform the results of two {@link ListenableFuture}s a and b once both has completed using - * {@code function} and complete the returned ListenableFuture at that point. This method is - * synchronous in the sense that function.apply() executes synchronously and returns a value - * and not a {@link ListenableFuture}. + * Transform the input futures into a single future, using the provided + * transform function. The transformation follows the same semantics as as + * {@link Futures#transform(ListenableFuture, Function)} and the input + * futures are combined using {@link Futures#allAsList}. * - * @param a the first ListenableFuture - * @param b the second ListenableFuture - * @param function a Function2 implementation, possibly expressed as a java 8 lambda - * @return a ListenableFuture of the result of {@code function}, that completes as soon as - * the supplied Function2.apply() invocation has completed. + * @param a a ListenableFuture to combine + * @param b a ListenableFuture to combine + * @param function the implementation of the transform + * @return a ListenableFuture holding the result of function.apply() */ public static ListenableFuture syncTransform2( ListenableFuture a, @@ -183,30 +182,30 @@ public Z apply(List results) { } /** - * Implementations of this interface is used in {@link #syncTransform2} to synchronously - * transform two values into a third value. + * Implementations of this interface is used to synchronously transform the + * input values into an output value. */ public interface Function2 { /** - * Combine a and b and return the result. - * @param a the first value. - * @param b the second value. - * @return a result of the combination of a and b. + * Combine the inputs into the returned output + * + * @param a an input value + * @param b an input value + * @return a result of the combination of the input values. */ Z apply(A a, B b); } /** - * Asynchronously transform the result of two {@link ListenableFuture}s a and b once both - * has completed using {@code function} and complete the returned ListenableFuture at the point. - * Execution is asynchronous in the sense that function returns a Future that may be executed - * asynchronously and once it completes it will complete the future that this method returns. + * Transform the input futures into a single future, using the provided + * transform function. The transformation follows the same semantics as as + * {@link Futures#transform(ListenableFuture, AsyncFunction)} and the input + * futures are combined using {@link Futures#allAsList}. * - * @param a the first ListenableFuture - * @param b the second ListenableFuture - * @param function an AsyncFunction2 implementation, possibly expressed as a java 8 lambda. - * @return a ListenableFuture of the result of {@code function}, that completes as soon as - * the future that gets returned by the supplied Function2.apply() has completed. + * @param a a ListenableFuture to combine + * @param b a ListenableFuture to combine + * @param function the implementation of the transform + * @return a ListenableFuture holding the result of function.apply() */ public static ListenableFuture asyncTransform2( ListenableFuture a, @@ -237,17 +236,16 @@ public interface AsyncFunction2 { } /** - * Transform the results of 3 {@link ListenableFuture}s a, b and c once all has completed using - * {@code function} and complete the returned ListenableFuture at that point. This method is - * synchronous in the sense that function.apply() executes synchronously and returns a value - * and not a {@link java.util.concurrent.Future}. + * Transform the input futures into a single future, using the provided + * transform function. The transformation follows the same semantics as as + * {@link Futures#transform(ListenableFuture, Function)} and the input + * futures are combined using {@link Futures#allAsList}. * - * @param a the first ListenableFuture. - * @param b the second ListenableFuture. - * @param c the third ListenableFuture. - * @param function a Function3 implementation, possibly expressed as a java 8 lambda - * @return a ListenableFuture of the result of {@code function}, that completes as soon as - * the supplied Function3.apply() invocation has completed. + * @param a a ListenableFuture to combine + * @param b a ListenableFuture to combine + * @param c a ListenableFuture to combine + * @param function the implementation of the transform + * @return a ListenableFuture holding the result of function.apply() */ public static ListenableFuture syncTransform3( ListenableFuture a, @@ -262,22 +260,25 @@ public Z apply(List results) { }); } + /** + * Implementations of this interface is used to synchronously transform the + * input values into an output value. + */ public interface Function3 { Z apply(A a, B b, C c); } /** - * Asynchronously transform the result of 3 {@link ListenableFuture}s a, b and c once both - * has completed using {@code function} and complete the returned ListenableFuture at the point. - * Execution is asynchronous in the sense that function returns a Future that may be executed - * asynchronously and once it completes it will complete the future that this method returns. + * Transform the input futures into a single future, using the provided + * transform function. The transformation follows the same semantics as as + * {@link Futures#transform(ListenableFuture, AsyncFunction)} and the input + * futures are combined using {@link Futures#allAsList}. * - * @param a the first ListenableFuture - * @param b the second ListenableFuture - * @param c the third ListenableFuture - * @param function an AsyncFunction3 implementation, possibly expressed as a java 8 lambda. - * @return a ListenableFuture of the result of {@code function}, that completes as soon as - * the future that gets returned by the supplied Function3.apply() has completed. + * @param a a ListenableFuture to combine + * @param b a ListenableFuture to combine + * @param c a ListenableFuture to combine + * @param function the implementation of the transform + * @return a ListenableFuture holding the result of function.apply() */ public static ListenableFuture asyncTransform3( ListenableFuture a, @@ -297,18 +298,17 @@ public interface AsyncFunction3 { } /** - * Transform the results of 4 {@link ListenableFuture}s a, b, c and d once all has completed using - * {@code function} and complete the returned ListenableFuture at that point. This method is - * synchronous in the sense that function.apply() executes synchronously and returns a value - * and not a {@link java.util.concurrent.Future}. + * Transform the input futures into a single future, using the provided + * transform function. The transformation follows the same semantics as as + * {@link Futures#transform(ListenableFuture, Function)} and the input + * futures are combined using {@link Futures#allAsList}. * - * @param a the first ListenableFuture. - * @param b the second ListenableFuture. - * @param c the third ListenableFuture. - * @param d the fourth ListenableFuture. - * @param function a Function4 implementation, possibly expressed as a java 8 lambda - * @return a ListenableFuture of the result of {@code function}, that completes as soon as - * the supplied Function4.apply() invocation has completed. + * @param a a ListenableFuture to combine + * @param b a ListenableFuture to combine + * @param c a ListenableFuture to combine + * @param d a ListenableFuture to combine + * @param function the implementation of the transform + * @return a ListenableFuture holding the result of function.apply() */ public static ListenableFuture syncTransform4( ListenableFuture a, @@ -325,23 +325,26 @@ public Z apply(List results) { }); } + /** + * Implementations of this interface is used to synchronously transform the + * input values into an output value. + */ public interface Function4 { Z apply(A a, B b, C c, D d); } /** - * Asynchronously transform the result of 3 {@link ListenableFuture}s a, b, c and d once both - * has completed using {@code function} and complete the returned ListenableFuture at the point. - * Execution is asynchronous in the sense that function returns a Future that may be executed - * asynchronously and once it completes it will complete the future that this method returns. + * Transform the input futures into a single future, using the provided + * transform function. The transformation follows the same semantics as as + * {@link Futures#transform(ListenableFuture, AsyncFunction)} and the input + * futures are combined using {@link Futures#allAsList}. * - * @param a the first ListenableFuture - * @param b the second ListenableFuture - * @param c the third ListenableFuture - * @param d the fourth ListenableFuture - * @param function an AsyncFunction4 implementation, possibly expressed as a java 8 lambda. - * @return a ListenableFuture of the result of {@code function}, that completes as soon as - * the future that gets returned by the supplied Function4.apply() has completed. + * @param a a ListenableFuture to combine + * @param b a ListenableFuture to combine + * @param c a ListenableFuture to combine + * @param d a ListenableFuture to combine + * @param function the implementation of the transform + * @return a ListenableFuture holding the result of function.apply() */ public static ListenableFuture asyncTransform4( ListenableFuture a, @@ -363,19 +366,18 @@ public interface AsyncFunction4 { } /** - * Transform the results of 5 {@link ListenableFuture}s a, b, c, d and e once all has completed - * using {@code function} and complete the returned ListenableFuture at that point. This method is - * synchronous in the sense that function.apply() executes synchronously and returns a value - * and not a {@link java.util.concurrent.Future}. + * Transform the input futures into a single future, using the provided + * transform function. The transformation follows the same semantics as as + * {@link Futures#transform(ListenableFuture, Function)} and the input + * futures are combined using {@link Futures#allAsList}. * - * @param a the first ListenableFuture. - * @param b the second ListenableFuture. - * @param c the third ListenableFuture. - * @param d the fourth ListenableFuture. - * @param e the fifth ListenableFuture. - * @param function a Function5 implementation, possibly expressed as a java 8 lambda - * @return a ListenableFuture of the result of {@code function}, that completes as soon as - * the supplied Function5.apply() invocation has completed. + * @param a a ListenableFuture to combine + * @param b a ListenableFuture to combine + * @param c a ListenableFuture to combine + * @param d a ListenableFuture to combine + * @param e a ListenableFuture to combine + * @param function the implementation of the transform + * @return a ListenableFuture holding the result of function.apply() */ public static ListenableFuture syncTransform5( ListenableFuture a, @@ -394,24 +396,27 @@ public Z apply(List results) { }); } + /** + * Implementations of this interface is used to synchronously transform the + * input values into an output value. + */ public interface Function5 { Z apply(A a, B b, C c, D d, E e); } /** - * Asynchronously transform the result of 3 {@link ListenableFuture}s a, b, c, d and e once both - * has completed using {@code function} and complete the returned ListenableFuture at the point. - * Execution is asynchronous in the sense that function returns a Future that may be executed - * asynchronously and once it completes it will complete the future that this method returns. + * Transform the input futures into a single future, using the provided + * transform function. The transformation follows the same semantics as as + * {@link Futures#transform(ListenableFuture, AsyncFunction)} and the input + * futures are combined using {@link Futures#allAsList}. * - * @param a the first ListenableFuture - * @param b the second ListenableFuture - * @param c the third ListenableFuture - * @param d the fourth ListenableFuture - * @param e the fifth ListenableFuture - * @param function an AsyncFunction5 implementation, possibly expressed as a java 8 lambda. - * @return a ListenableFuture of the result of {@code function}, that completes as soon as - * the future that gets returned by the supplied Function5.apply() has completed. + * @param a a ListenableFuture to combine + * @param b a ListenableFuture to combine + * @param c a ListenableFuture to combine + * @param d a ListenableFuture to combine + * @param e a ListenableFuture to combine + * @param function the implementation of the transform + * @return a ListenableFuture holding the result of function.apply() */ public static ListenableFuture asyncTransform5( ListenableFuture a, @@ -436,20 +441,19 @@ public interface AsyncFunction5 { } /** - * Transform the results of 6 {@link ListenableFuture}s a, b, c, d, e and f once all has completed - * using {@code function} and complete the returned ListenableFuture at that point. This method is - * synchronous in the sense that function.apply() executes synchronously and returns a value - * and not a {@link java.util.concurrent.Future}. + * Transform the input futures into a single future, using the provided + * transform function. The transformation follows the same semantics as as + * {@link Futures#transform(ListenableFuture, Function)} and the input + * futures are combined using {@link Futures#allAsList}. * - * @param a the first ListenableFuture. - * @param b the second ListenableFuture. - * @param c the third ListenableFuture. - * @param d the fourth ListenableFuture. - * @param e the fifth ListenableFuture. - * @param f the sixth ListenableFuture. - * @param function a Function5 implementation, possibly expressed as a java 8 lambda - * @return a ListenableFuture of the result of {@code function}, that completes as soon as - * the supplied Function5.apply() invocation has completed. + * @param a a ListenableFuture to combine + * @param b a ListenableFuture to combine + * @param c a ListenableFuture to combine + * @param d a ListenableFuture to combine + * @param e a ListenableFuture to combine + * @param f a ListenableFuture to combine + * @param function the implementation of the transform + * @return a ListenableFuture holding the result of function.apply() */ public static ListenableFuture syncTransform6( ListenableFuture a, @@ -470,26 +474,28 @@ public Z apply(List results) { }); } + /** + * Implementations of this interface is used to synchronously transform the + * input values into an output value. + */ public interface Function6 { Z apply(A a, B b, C c, D d, E e, F f); } /** - * Asynchronously transform the result of 3 {@link ListenableFuture}s a, b, c, d, e and f once - * both has completed using {@code function} and complete the returned ListenableFuture at the - * point. - * Execution is asynchronous in the sense that function returns a Future that may be executed - * asynchronously and once it completes it will complete the future that this method returns. + * Transform the input futures into a single future, using the provided + * transform function. The transformation follows the same semantics as as + * {@link Futures#transform(ListenableFuture, AsyncFunction)} and the input + * futures are combined using {@link Futures#allAsList}. * - * @param a the first ListenableFuture - * @param b the second ListenableFuture - * @param c the third ListenableFuture - * @param d the fourth ListenableFuture - * @param e the fifth ListenableFuture - * @param f the sixth ListenableFuture - * @param function an AsyncFunction6 implementation, possibly expressed as a java 8 lambda. - * @return a ListenableFuture of the result of {@code function}, that completes as soon as - * the future that gets returned by the supplied Function6.apply() has completed. + * @param a a ListenableFuture to combine + * @param b a ListenableFuture to combine + * @param c a ListenableFuture to combine + * @param d a ListenableFuture to combine + * @param e a ListenableFuture to combine + * @param f a ListenableFuture to combine + * @param function the implementation of the transform + * @return a ListenableFuture holding the result of function.apply() */ public static ListenableFuture asyncTransform6( ListenableFuture a,