Package com.ibm.asyncutil.util

Class Combinators

java.lang.Object

com.ibm.asyncutil.util.Combinators

public class Combinators
extends Object

Utility methods for combining more than one CompletionStage into a single CompletionStage

Method Summary

Modifier and Type	Method	Description
static CompletionStage<Void>	allOf(Collection<? extends CompletionStage<?>> stages)	Given a collection of stages, returns a new CompletionStage that is completed when all input stages are complete.
static <T> CompletionStage<Collection<T>>	collect(Collection<? extends CompletionStage<T>> stages)	Given a collection of stages all of the same type, returns a new CompletionStage that is completed with a collection of the results of all input stages when all stages complete.
static <T,A,R> CompletionStage<R>	collect(Collection<? extends CompletionStage<T>> stages, Collector<? super T,A,R> collector)	Applies a collector to the results of all stages after all complete, returning a CompletionStage of the collected result.
static <K,V> CompletionStage<Map<K,V>>	keyedAll(Map<K,? extends CompletionStage<V>> stageMap)	Given a Map from some key type K to CompletionStages of values, returns a CompletionStage which completes with a Map<K, V> when all the CompletionStages in the input map have completed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

allOf

public static CompletionStage<Void> allOf(Collection<? extends CompletionStage<?>> stages)

Given a collection of stages, returns a new CompletionStage that is completed when all input stages are complete. If any stage completes exceptionally, the returned stage will complete exceptionally.

Parameters:

stages - a Collection of CompletionStage

Returns:

a CompletionStage which will complete after every stage in stages completes

Throws:

NullPointerException - if stages or any of its elements are null

collect

public static <T> CompletionStage<Collection<T>> collect(Collection<? extends CompletionStage<T>> stages)

Given a collection of stages all of the same type, returns a new CompletionStage that is completed with a collection of the results of all input stages when all stages complete. If the input collection has a defined order, the order will be preserved in the returned collection. If an element of stages completes exceptionally, so too will the CompletionStage returned by this method.

Parameters:

stages - a Collection of CompletionStage all of type T

Returns:

a CompletionStage which will complete with a collection of the elements produced by stages when all stages complete

Throws:

NullPointerException - if stages or any of its elements are null

collect

public static <T,A,R> CompletionStage<R> collect(Collection<? extends CompletionStage<T>> stages,
                                                 Collector<? super T,A,R> collector)

Applies a collector to the results of all stages after all complete, returning a CompletionStage of the collected result. There is no need nor benefit for the Collector to have the CONCURRENT characteristic, the collector will be applied in a single thread. If any of the input stages completes exceptionally, so too will the CompletionStage returned by this method.

Type Parameters:

T - The type of the elements in stages which will be collected by collector

A - The intermediate collection type

R - The final type returned by collector

Parameters:

stages - a Collection of stages all of type T

collector - a Collector which will be applied to the results of stages to produce the final R result.

Returns:

a CompletionStage which will complete with the R typed object that is produced by collector when all input stages have completed.

Throws:

NullPointerException - if stages or any of its elements are null

keyedAll

public static <K,V> CompletionStage<Map<K,V>> keyedAll(Map<K,? extends CompletionStage<V>> stageMap)

Given a Map from some key type K to CompletionStages of values, returns a CompletionStage which completes with a Map<K, V> when all the CompletionStages in the input map have completed. For example, if we have an asynchronous method to lookup student grade point averages.

 
 Map<Student, CompletionStage<Double>> gpaFutures =
  students
      .stream()
      .collect(Collectors.toMap(Functions.identity(), student -> getGpaAsync(student));
 Map<Student, Double> studentGpas = keyedAll(gpaFutures).toCompletableFuture().join();
 
 

If a value in stageMap completes exceptionally, so too will the CompletionStage returned by this method.

Type Parameters:

K - the input and output key type

V - the value type for the map that will be produced by the returned CompletionStage

Parameters:

stageMap - a Map with keys of type K and CompletionStages of type V for values

Returns:

a CompletionStage that will be completed with a map mapping keys of type K to the values returned by the CompletionStages in stageMap

Throws:

NullPointerException - if stageMap or any of its values are null