FutureValue (stream-utils 1.1 API)

java.lang.Object
- com.github.robtimus.stream.FutureValue<T>

Type Parameters:: T - The type of CompletionStage result.

public final class FutureValue<T>
extends Object

A class that allows filtering and mapping on CompletionStage instances inside streams.

In streams, applying operations such as Stream.filter(Predicate) immediately alter the state of the streams. When using streams of CompletionStage, the result is not available when the stream operation is applied. This class is meant to help with that issue as far as possible. It does so by providing the most essential functionality using asynchronous mapping:

Filtering values. However, because the actual filtering is done asynchronously, instead of using Stream.filter(Predicate), Stream.map(Function) should be used in combination with filter(Predicate).
Transforming values, using a combination of Stream.map(Function) and map(Function).
Collecting values, using a combination of Stream.collect(Collector) and collect(Collector).
Running an action on values, using a combination of Stream.forEach(Consumer) and run(Consumer).

Most other operations rely on the internal state of the stream to change. These operations should not be used after the first mapping to wrap(CompletionStage) or wrap(CompletableFuture). The only stream operations that can safely be used are Stream.map(Function) (both for mapping and filtering), Stream.forEach(Consumer) and Stream.collect(Collector). For other methods, if possible, use Stream.collect(Collector) as replacement. For instance, the following can be used as replacement for Stream.reduce(BinaryOperator) using Collectors.reducing(BinaryOperator):


 CompletableFuture<Optional<Integer>> result = stream
         .map(FutureValue::wrap)
         .map(FutureValue.filter(i -> (i & 1) == 0))
         .collect(FutureValue.collect(reducing(Integer::sum));

The following is a list of stream operations and their possible Collector replacements:

Stream operations

Stream operation Replacement

Stream.toArray() Collectors.toList() and List.toArray()

Stream.reduce(BinaryOperator) Collectors.reducing(BinaryOperator)

Stream.reduce(Object, BinaryOperator) Collectors.reducing(Object, BinaryOperator)

Stream.reduce(Object, BiFunction, BinaryOperator) Collectors.reducing(Object, Function, BinaryOperator)
Note that this transforms values before accumulating them.

Stream.min(Comparator) Collectors.minBy(Comparator)

Stream.max(Comparator) Collectors.maxBy(Comparator)

Stream.count() Collectors.counting()

Stream.findAny() findAny()
findAny(ExecutorService)

Stream operations
Stream operation	Replacement
`Stream.toArray()`	`Collectors.toList()` and `List.toArray()`
`Stream.reduce(BinaryOperator)`	`Collectors.reducing(BinaryOperator)`
`Stream.reduce(Object, BinaryOperator)`	`Collectors.reducing(Object, BinaryOperator)`
`Stream.reduce(Object, BiFunction, BinaryOperator)`	`Collectors.reducing(Object, Function, BinaryOperator)` Note that this transforms values before accumulating them.
`Stream.min(Comparator)`	`Collectors.minBy(Comparator)`
`Stream.max(Comparator)`	`Collectors.maxBy(Comparator)`
`Stream.count()`	`Collectors.counting()`
`Stream.findAny()`	`findAny()` `findAny(ExecutorService)`

Author:: Rob Spoor

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static <T,A,R> Collector<FutureValue<T>,?,CompletableFuture<R>>`	`collect(Collector<T,A,R> collector)` Returns a `Collector` that accumulates `FutureValue` instances into a `CompletableFuture`.
`static <T> UnaryOperator<FutureValue<T>>`	`filter(Predicate<? super T> predicate)` Returns a unary operator that applies filtering to a stream of `FutureValue`.
`static <T> Collector<FutureValue<T>,?,CompletableFuture<Optional<T>>>`	`findAny()` Returns a `Collector` that returns any `CompletionStage` result.
`static <T> Collector<FutureValue<T>,?,CompletableFuture<Optional<T>>>`	`findAny(ExecutorService executor)` Returns a `Collector` that returns any `CompletionStage` result.
`static <T,R> Function<FutureValue<T>,FutureValue<R>>`	`flatMap(Function<? super T,? extends CompletionStage<R>> mapper)` Returns a function that transforms one `FutureValue` instance into another.
`static <T,R> Function<FutureValue<T>,FutureValue<R>>`	`map(Function<? super T,? extends R> mapper)` Returns a function that transforms one `FutureValue` instance into another.
`static <T> Consumer<FutureValue<T>>`	`run(Consumer<? super T> action)` Returns a consumer that performs an action on `FutureValue` instances.
`static <T> FutureValue<T>`	`wrap(CompletableFuture<T> future)` Wraps a `CompletableFuture` in a `FutureValue`.
`static <T> FutureValue<T>`	`wrap(CompletionStage<T> future)` Wraps a `CompletionStage` in a `FutureValue`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - wrap
```
public static <T> FutureValue<T> wrap(CompletionStage<T> future)
```
    Wraps a CompletionStage in a FutureValue. This is usually used in Stream.map(Function) to start using this class.
    
    Type Parameters:
    
    T - The type of CompletionStage result.
    
    Parameters:
    
    future - The future to wrap.
    
    Returns:
    
    A FutureValue wrapping the given CompletionStage.
    
    Throws:
    
    NullPointerException - If the given CompletionStage is null.
    
    Since:
    
    1.1
  - wrap
```
public static <T> FutureValue<T> wrap(CompletableFuture<T> future)
```
    Wraps a CompletableFuture in a FutureValue. This is usually used in Stream.map(Function) to start using this class.
    
    Type Parameters:
    
    T - The type of CompletableFuture result.
    
    Parameters:
    
    future - The future to wrap.
    
    Returns:
    
    A FutureValue wrapping the given CompletableFuture.
    
    Throws:
    
    NullPointerException - If the given CompletableFuture is null.
  - filter
```
public static <T> UnaryOperator<FutureValue<T>> filter(Predicate<? super T> predicate)
```
    Returns a unary operator that applies filtering to a stream of FutureValue. However, because the actual filtering is done asynchronously, this must be applied using Stream.map(Function) and not using Stream.filter(Predicate).
    
    Type Parameters:
    
    T - The type of CompletionStage result.
    
    Parameters:
    
    predicate - The predicate to apply.
    
    Returns:
    
    A unary operator that applies filtering to a stream of FutureValue.
    
    Throws:
    
    NullPointerException - If the given predicate is null.
  - map
```
public static <T,R> Function<FutureValue<T>,FutureValue<R>> map(Function<? super T,? extends R> mapper)
```
    Returns a function that transforms one FutureValue instance into another. This is usually used in a call to Stream.map(Function) to transform CompletionStage results.
    
    Type Parameters:
    
    T - The type of the input to the function.
    
    R - The type of the result of the function.
    
    Parameters:
    
    mapper - The function to apply to each CompletionStage result.
    
    Returns:
    
    A function that transforms one FutureValue instance into another
    
    Throws:
    
    NullPointerException - If the given function is null.
  - flatMap
```
public static <T,R> Function<FutureValue<T>,FutureValue<R>> flatMap(Function<? super T,? extends CompletionStage<R>> mapper)
```
    Returns a function that transforms one FutureValue instance into another. This is usually used in a call to Stream.map(Function) to transform CompletionStage results. Unlike map(Function), the result of the function must be a CompletionStage, e.g. a CompletableFuture.
    
    Type Parameters:
    
    T - The type of the input to the function.
    
    R - The type of the returned CompletionStage result.
    
    Parameters:
    
    mapper - The function to apply to each CompletionStage result.
    
    Returns:
    
    A function that transforms one FutureValue instance into another
    
    Throws:
    
    NullPointerException - If the given function is null.
    
    Since:
    
    1.1
  - collect
```
public static <T,A,R> Collector<FutureValue<T>,?,CompletableFuture<R>> collect(Collector<T,A,R> collector)
```
    Returns a Collector that accumulates FutureValue instances into a CompletableFuture. This method is similar to AdditionalCollectors.completableFutures(Collector). That method can be used if no filtering or mapping is needed on the CompletionStage results.
    
    Type Parameters:
    
    T - The result type of the CompletionStage instances.
    
    A - The intermediate accumulation type of the Collector.
    
    R - The result type of the collected CompletableFuture.
    
    Parameters:
    
    collector - The collector for the CompletionStage results.
    
    Returns:
    
    A Collector that collects FutureValue instances.
    
    Throws:
    
    NullPointerException - If the given Collector is null.
  - run
```
public static <T> Consumer<FutureValue<T>> run(Consumer<? super T> action)
```
    Returns a consumer that performs an action on FutureValue instances. This is usually used in a call to Stream.forEach(Consumer) or Stream.forEachOrdered(Consumer).
    Although this method can be used in a call to Stream.peek(Consumer), the result is unpredictable due to the asynchronous nature of CompletionStages. The same goes for Stream.forEachOrdered(Consumer).
    
    Type Parameters:
    
    T - The type of CompletionStage result.
    
    Parameters:
    
    action - The action to perform for each CompletionStage result. Note that the action is called asynchronously.
    
    Returns:
    
    A consumer that performs the given action on FutureValue instances asynchronously.
    
    Throws:
    
    NullPointerException - If the given action is null.
  - findAny
```
public static <T> Collector<FutureValue<T>,?,CompletableFuture<Optional<T>>> findAny()
```
    Returns a Collector that returns any CompletionStage result. To prevent waiting for more CompletionStages to finish than necessary, this method will create another CompletableFuture using the ForkJoinPool.commonPool(). This will return as value the first available result, or throw the first available error.
    
    Type Parameters:
    
    T - The type of CompletionStage result.
    
    Returns:
    
    A Collector that returns any CompletionStage result.
  - findAny
```
public static <T> Collector<FutureValue<T>,?,CompletableFuture<Optional<T>>> findAny(ExecutorService executor)
```
    Returns a Collector that returns any CompletionStage result. To prevent waiting for more CompletionStages to finish than necessary, this method will create another CompletableFuture. This will return as value the first available result, or throw the first available error.
    
    Type Parameters:
    
    T - The type of CompletionStage result.
    
    Parameters:
    
    executor - The executor service to use for creating the new CompletableFuture.
    
    Returns:
    
    A Collector that returns any CompletionStage result.
    
    Throws:
    
    NullPointerException - If the given executor service is null.

Class FutureValue<T>

Method Summary

Methods inherited from class java.lang.Object

Method Detail

wrap

wrap

filter

map

flatMap

collect

run

findAny

findAny