io.vavr.concurrent

Interface Future<T>

Type Parameters:

T - Type of the computation result.

All Superinterfaces:

Iterable<T>, Value<T>

public interface Future<T>
extends Value<T>

A Future is a computation result that becomes available at some point. All operations provided are non-blocking.

The underlying ExecutorService is used to execute asynchronous handlers, e.g. via onComplete(...).

A Future has two states: pending and completed.

• Pending: The computation is ongoing. Only a pending future may be completed or cancelled.
• Completed: The computation finished successfully with a result, failed with an exception or was cancelled.

Callbacks may be registered on a Future at each point of time. These actions are performed as soon as the Future is completed. An action which is registered on a completed Future is immediately performed. The action may run on a separate Thread, depending on the underlying ExecutorService. Actions which are registered on a cancelled Future are performed with the failed result.

Author:

Daniel Dietrich

Field Summary

Fields

Modifier and Type	Field and Description
static ExecutorService	DEFAULT_EXECUTOR_SERVICE The default executor service is Executors.newCachedThreadPool().

Method Summary

Modifier and Type	Method and Description
default Future<T>	andThen(Consumer<? super Try<T>> action) Support for chaining of callbacks that are guaranteed to be executed in a specific order.
Future<T>	await() Blocks the current Thread until this Future completed or returns immediately if this Future is already completed.
default boolean	cancel() Cancels the Future.
boolean	cancel(boolean mayInterruptIfRunning) Cancels the Future.
default <R> Future<R>	collect(PartialFunction<? super T,? extends R> partialFunction) Collects value that is in the domain of the given partialFunction by mapping the value to type R.
ExecutorService	executorService() Returns the ExecutorService used by this Future.
default Future<Throwable>	failed() A projection that inverses the result of this Future.
static <T> Future<T>	failed(ExecutorService executorService, Throwable exception) Creates a failed Future with the given exception, backed by the given ExecutorService.
static <T> Future<T>	failed(Throwable exception) Creates a failed Future with the given exception, backed by the DEFAULT_EXECUTOR_SERVICE.
default Future<T>	fallbackTo(Future<? extends T> that) Returns a Future that returns the result of this Future, if it is a success.
default Future<T>	filter(Predicate<? super T> predicate) Shortcut for filterTry(predicate::test.
default Future<T>	filterTry(CheckedPredicate<? super T> predicate) Filters the result of this Future by calling Try.filterTry(CheckedPredicate).
static <T> Future<Option<T>>	find(ExecutorService executorService, Iterable<? extends Future<? extends T>> futures, Predicate<? super T> predicate) Returns a Future that eventually succeeds with the first result of the given Futures which matches the given predicate.
static <T> Future<Option<T>>	find(Iterable<? extends Future<? extends T>> futures, Predicate<? super T> predicate) Returns a Future that eventually succeeds with the first result of the given Futures which matches the given predicate.
static <T> Future<T>	firstCompletedOf(ExecutorService executorService, Iterable<? extends Future<? extends T>> futures) Returns a new Future that will contain the result of the first of the given futures that is completed, backed by the given ExecutorService.
static <T> Future<T>	firstCompletedOf(Iterable<? extends Future<? extends T>> futures) Returns a new Future that will contain the result of the first of the given futures that is completed, backed by the DEFAULT_EXECUTOR_SERVICE.
default <U> Future<U>	flatMap(Function<? super T,? extends Future<? extends U>> mapper)
default <U> Future<U>	flatMapTry(CheckedFunction1<? super T,? extends Future<? extends U>> mapper)
static <T,U> Future<U>	fold(ExecutorService executorService, Iterable<? extends Future<? extends T>> futures, U zero, BiFunction<? super U,? super T,? extends U> f) Returns a Future which contains the result of the fold of the given future values.
static <T,U> Future<U>	fold(Iterable<? extends Future<? extends T>> futures, U zero, BiFunction<? super U,? super T,? extends U> f) Returns a Future which contains the result of the fold of the given future values.
default void	forEach(Consumer<? super T> action) Performs the given action asynchronously hence this Future result becomes available.
static <T> Future<T>	fromCompletableFuture(CompletableFuture<T> future) Creates a Future with the given CompletableFuture, backed by the DEFAULT_EXECUTOR_SERVICE
static <T> Future<T>	fromCompletableFuture(ExecutorService executorService, CompletableFuture<T> future) Creates a Future with the given CompletableFuture, backed by given ExecutorService
static <T> Future<T>	fromJavaFuture(ExecutorService executorService, Future<T> future) Creates a Future with the given java.util.concurrent.Future, backed by given ExecutorService
static <T> Future<T>	fromJavaFuture(Future<T> future) Creates a Future with the given java.util.concurrent.Future, backed by the DEFAULT_EXECUTOR_SERVICE
static <T> Future<T>	fromTry(ExecutorService executorService, Try<? extends T> result) Creates a Future from a Try, backed by the given ExecutorService.
static <T> Future<T>	fromTry(Try<? extends T> result) Creates a Future from a Try, backed by the DEFAULT_EXECUTOR_SERVICE.
default T	get() Gets the value if the computation result is a Success or throws if it was a Failure.
default Option<Throwable>	getCause() Returns the underlying exception of this Future, syntactic sugar for future.getValue().map(Try::getCause).
Option<Try<T>>	getValue() Returns the value of the Future.
default boolean	isAsync() A Futures's value is computed asynchronously.
boolean	isCompleted() Checks if this Future is completed, i.e.
default boolean	isEmpty() Checks, if this future has a value.
default boolean	isFailure() Checks if this Future completed with a failure.
default boolean	isLazy() A Future's value is computed eagerly.
default boolean	isSingleValued() A Future is single-valued.
default boolean	isSuccess() Checks if this Future completed with a success.
default Iterator<T>	iterator() Returns a rich io.vavr.collection.Iterator.
default <U> Future<U>	map(Function<? super T,? extends U> mapper) Maps the underlying value to a different component type.
default <U> Future<U>	mapTry(CheckedFunction1<? super T,? extends U> mapper)
static <T> Future<T>	narrow(Future<? extends T> future) Narrows a widened Future<? extends T> to Future<T> by performing a type-safe cast.
static <T> Future<T>	of(CheckedFunction0<? extends T> computation) Starts an asynchronous computation, backed by the DEFAULT_EXECUTOR_SERVICE.
static <T> Future<T>	of(ExecutorService executorService, CheckedFunction0<? extends T> computation) Starts an asynchronous computation, backed by the given ExecutorService.
static <T> Future<T>	ofCallable(Callable<? extends T> computation) Starts an asynchronous computation, backed by the DEFAULT_EXECUTOR_SERVICE.
static <T> Future<T>	ofCallable(ExecutorService executorService, Callable<? extends T> computation) Starts an asynchronous computation, backed by the given ExecutorService.
static <T> Future<T>	ofSupplier(ExecutorService executorService, Supplier<? extends T> computation) Starts an asynchronous computation, backed by the given ExecutorService.
static <T> Future<T>	ofSupplier(Supplier<? extends T> computation) Starts an asynchronous computation, backed by the DEFAULT_EXECUTOR_SERVICE.
Future<T>	onComplete(Consumer<? super Try<T>> action) Performs the action once the Future is complete.
default Future<T>	onFailure(Consumer<? super Throwable> action) Performs the action once the Future is complete and the result is a Try.Failure.
default Future<T>	onSuccess(Consumer<? super T> action) Performs the action once the Future is complete and the result is a Try.Success.
default Future<T>	orElse(Future<? extends T> other)
default Future<T>	orElse(Supplier<? extends Future<? extends T>> supplier)
default Future<T>	peek(Consumer<? super T> action) Performs the given action on the first element if this is an eager implementation.
default Future<T>	recover(Function<? super Throwable,? extends T> f) Handles a failure of this Future by returning another result.
default Future<T>	recoverWith(Function<? super Throwable,? extends Future<? extends T>> f) Handles a failure of this Future by returning the result of another Future.
static <T> Future<T>	reduce(ExecutorService executorService, Iterable<? extends Future<? extends T>> futures, BiFunction<? super T,? super T,? extends T> f) Returns a Future which contains the reduce result of the given future values.
static <T> Future<T>	reduce(Iterable<? extends Future<? extends T>> futures, BiFunction<? super T,? super T,? extends T> f) Returns a Future which contains the reduce result of the given future values.
static Future<Void>	run(CheckedRunnable unit) Runs an asynchronous computation, backed by the DEFAULT_EXECUTOR_SERVICE.
static Future<Void>	run(ExecutorService executorService, CheckedRunnable unit) Starts an asynchronous computation, backed by the given ExecutorService.
static Future<Void>	runRunnable(ExecutorService executorService, Runnable computation) Starts an asynchronous computation, backed by the given ExecutorService.
static Future<Void>	runRunnable(Runnable computation) Starts an asynchronous computation, backed by the DEFAULT_EXECUTOR_SERVICE.
static <T> Future<Seq<T>>	sequence(ExecutorService executorService, Iterable<? extends Future<? extends T>> futures) Reduces many Futures into a single Future by transforming an Iterable<Future<? extends T>> into a Future<Seq<T>>.
static <T> Future<Seq<T>>	sequence(Iterable<? extends Future<? extends T>> futures) Reduces many Futures into a single Future by transforming an Iterable<Future<? extends T>> into a Future<Seq<T>>.
default String	stringPrefix() Returns the name of this Value type, which is used by toString().
static <T> Future<T>	successful(ExecutorService executorService, T result) Creates a succeeded Future, backed by the given ExecutorService.
static <T> Future<T>	successful(T result) Creates a succeeded Future, backed by the DEFAULT_EXECUTOR_SERVICE.
default CompletableFuture<T>	toCompletableFuture() Converts this to a CompletableFuture
default <U> U	transform(Function<? super Future<T>,? extends U> f) Transforms this Future.
default <U> Future<U>	transformValue(Function<? super Try<T>,? extends Try<? extends U>> f) Transforms the value of this Future, whether it is a success or a failure.
static <T,U> Future<Seq<U>>	traverse(ExecutorService executorService, Iterable<? extends T> values, Function<? super T,? extends Future<? extends U>> mapper) Maps the values of an iterable in parallel to a sequence of mapped values into a single Future by transforming an Iterable<? extends T> into a Future<Seq<U>>.
static <T,U> Future<Seq<U>>	traverse(Iterable<? extends T> values, Function<? super T,? extends Future<? extends U>> mapper) Maps the values of an iterable in parallel to a sequence of mapped values into a single Future by transforming an Iterable<? extends T> into a Future<Seq<U>>.
default <U> Future<Tuple2<T,U>>	zip(Future<? extends U> that) Returns a tuple of this and that Future result.
default <U,R> Future<R>	zipWith(Future<? extends U> that, BiFunction<? super T,? super U,? extends R> combinator) Returns a this and that Future result combined using a given combinator function.

Methods inherited from interface io.vavr.Value

collect, collect, contains, corresponds, eq, equals, exists, forAll, getOrElse, getOrElse, getOrElseThrow, getOrElseTry, getOrNull, hashCode, narrow, out, out, spliterator, stderr, stdout, toArray, toCharSeq, toEither, toEither, toInvalid, toInvalid, toJavaArray, toJavaArray, toJavaCollection, toJavaList, toJavaList, toJavaMap, toJavaMap, toJavaMap, toJavaOptional, toJavaParallelStream, toJavaSet, toJavaSet, toJavaStream, toLeft, toLeft, toLinkedMap, toLinkedMap, toLinkedSet, toList, toMap, toMap, toOption, toPriorityQueue, toPriorityQueue, toQueue, toRight, toRight, toSet, toSortedMap, toSortedMap, toSortedMap, toSortedMap, toSortedSet, toSortedSet, toStream, toString, toTree, toTry, toTry, toValid, toValid, toValidation, toValidation, toVector

Field Detail

DEFAULT_EXECUTOR_SERVICE

static final ExecutorService DEFAULT_EXECUTOR_SERVICE

The default executor service is Executors.newCachedThreadPool(). Please note that it may prevent the VM from shutdown.

Method Detail

failed

static <T> Future<T> failed(Throwable exception)

Creates a failed Future with the given exception, backed by the DEFAULT_EXECUTOR_SERVICE.

Type Parameters:

T - The value type of a successful result.

Parameters:

exception - The reason why it failed.

Returns:

A failed Future.

Throws:

NullPointerException - if exception is null

failed

static <T> Future<T> failed(ExecutorService executorService,
                            Throwable exception)

Creates a failed Future with the given exception, backed by the given ExecutorService.

Type Parameters:

T - The value type of a successful result.

Parameters:

executorService - An executor service.

exception - The reason why it failed.

Returns:

A failed Future.

Throws:

NullPointerException - if executorService or exception is null

find

static <T> Future<Option<T>> find(Iterable<? extends Future<? extends T>> futures,
                                  Predicate<? super T> predicate)

Returns a Future that eventually succeeds with the first result of the given Futures which matches the given predicate. If no result matches, the Future will contain Option.None.

The returned Future is backed by the DEFAULT_EXECUTOR_SERVICE.

Type Parameters:

T - Result type of the futures.

Parameters:

futures - An iterable of futures.

predicate - A predicate that tests successful future results.

Returns:

A Future of an Option of the first result of the given futures that satisfies the given predicate.

Throws:

NullPointerException - if one of the arguments is null

find

static <T> Future<Option<T>> find(ExecutorService executorService,
                                  Iterable<? extends Future<? extends T>> futures,
                                  Predicate<? super T> predicate)

Returns a Future that eventually succeeds with the first result of the given Futures which matches the given predicate. If no result matches, the Future will contain Option.None.

The returned Future is backed by the given ExecutorService.

Type Parameters:

T - Result type of the futures.

Parameters:

executorService - An executor service.

futures - An iterable of futures.

predicate - A predicate that tests successful future results.

Returns:

A Future of an Option of the first result of the given futures that satisfies the given predicate.

Throws:

NullPointerException - if one of the arguments is null

firstCompletedOf

static <T> Future<T> firstCompletedOf(Iterable<? extends Future<? extends T>> futures)

Returns a new Future that will contain the result of the first of the given futures that is completed, backed by the DEFAULT_EXECUTOR_SERVICE.

Type Parameters:

T - The result type.

Parameters:

futures - An iterable of futures.

Returns:

A new Future.

Throws:

NullPointerException - if futures is null

firstCompletedOf

static <T> Future<T> firstCompletedOf(ExecutorService executorService,
                                      Iterable<? extends Future<? extends T>> futures)

Returns a new Future that will contain the result of the first of the given futures that is completed, backed by the given ExecutorService.

Type Parameters:

T - The result type.

Parameters:

executorService - An executor service.

futures - An iterable of futures.

Returns:

A new Future.

Throws:

NullPointerException - if executorService or futures is null

fold

static <T,U> Future<U> fold(Iterable<? extends Future<? extends T>> futures,
                            U zero,
                            BiFunction<? super U,? super T,? extends U> f)

Returns a Future which contains the result of the fold of the given future values. If any future or the fold fail, the result is a failure.

The resulting Future is backed by the DEFAULT_EXECUTOR_SERVICE.

Type Parameters:

T - The result type of the given Futures.

U - The fold result type.

Parameters:

futures - An iterable of futures.

zero - The zero element of the fold.

f - The fold operation.

Returns:

A new Future that will contain the fold result.

Throws:

NullPointerException - if futures or f is null.

fold

static <T,U> Future<U> fold(ExecutorService executorService,
                            Iterable<? extends Future<? extends T>> futures,
                            U zero,
                            BiFunction<? super U,? super T,? extends U> f)

Returns a Future which contains the result of the fold of the given future values. If any future or the fold fail, the result is a failure.

The resulting Future is backed by the given ExecutorService.

Type Parameters:

T - The result type of the given Futures.

U - The fold result type.

Parameters:

executorService - An ExecutorService.

futures - An iterable of futures.

zero - The zero element of the fold.

f - The fold operation.

Returns:

A new Future that will contain the fold result.

Throws:

NullPointerException - if executorService, futures or f is null.

fromJavaFuture

static <T> Future<T> fromJavaFuture(Future<T> future)

Creates a Future with the given java.util.concurrent.Future, backed by the DEFAULT_EXECUTOR_SERVICE

Type Parameters:

T - Result type of the Future

Parameters:

future - A Future

Returns:

A new Future wrapping the result of the Java future

Throws:

NullPointerException - if future is null

fromJavaFuture

static <T> Future<T> fromJavaFuture(ExecutorService executorService,
                                    Future<T> future)

Creates a Future with the given java.util.concurrent.Future, backed by given ExecutorService

Type Parameters:

T - Result type of the Future

Parameters:

executorService - An ExecutorService

future - A Future

Returns:

A new Future wrapping the result of the Java future

Throws:

NullPointerException - if executorService or future is null

fromCompletableFuture

@GwtIncompatible
static <T> Future<T> fromCompletableFuture(CompletableFuture<T> future)

Creates a Future with the given CompletableFuture, backed by the DEFAULT_EXECUTOR_SERVICE

Type Parameters:

T - Result type of the Future

Parameters:

future - A CompletableFuture

Returns:

A new Future wrapping the result of the CompletableFuture

Throws:

NullPointerException - if future is null

fromCompletableFuture

@GwtIncompatible
static <T> Future<T> fromCompletableFuture(ExecutorService executorService,
                                                            CompletableFuture<T> future)

Creates a Future with the given CompletableFuture, backed by given ExecutorService

Type Parameters:

T - Result type of the Future

Parameters:

executorService - An ExecutorService

future - A CompletableFuture

Returns:

A new Future wrapping the result of the CompletableFuture

Throws:

NullPointerException - if executorService or future is null

fromTry

static <T> Future<T> fromTry(Try<? extends T> result)

Creates a Future from a Try, backed by the DEFAULT_EXECUTOR_SERVICE.

Type Parameters:

T - The value type of a successful result.

Parameters:

result - The result.

Returns:

A completed Future which contains either a Success or a Failure.

Throws:

NullPointerException - if result is null

fromTry

static <T> Future<T> fromTry(ExecutorService executorService,
                             Try<? extends T> result)

Creates a Future from a Try, backed by the given ExecutorService.

Type Parameters:

T - The value type of a successful result.

Parameters:

executorService - An ExecutorService.

result - The result.

Returns:

A completed Future which contains either a Success or a Failure.

Throws:

NullPointerException - if executorService or result is null

narrow

static <T> Future<T> narrow(Future<? extends T> future)

Narrows a widened Future<? extends T> to Future<T> by performing a type-safe cast. This is eligible because immutable/read-only collections are covariant.

Type Parameters:

T - Component type of the Future.

Parameters:

future - A Future.

Returns:

the given future instance as narrowed type Future<T>.

ofSupplier

static <T> Future<T> ofSupplier(Supplier<? extends T> computation)

Starts an asynchronous computation, backed by the DEFAULT_EXECUTOR_SERVICE.

Type Parameters:

T - Type of the computation result.

Parameters:

computation - A computation.

Returns:

A new Future instance

Throws:

NullPointerException - if computation is null.

ofSupplier

static <T> Future<T> ofSupplier(ExecutorService executorService,
                                Supplier<? extends T> computation)

Starts an asynchronous computation, backed by the given ExecutorService.

Type Parameters:

T - Type of the computation result.

Parameters:

executorService - An executor service.

computation - A computation.

Returns:

A new Future instance

Throws:

NullPointerException - if one of executorService or computation is null.

ofCallable

static <T> Future<T> ofCallable(Callable<? extends T> computation)

Starts an asynchronous computation, backed by the DEFAULT_EXECUTOR_SERVICE.

Type Parameters:

T - Type of the computation result.

Parameters:

computation - A computation

Returns:

A new Future instance

Throws:

NullPointerException - if computation is null.

ofCallable

static <T> Future<T> ofCallable(ExecutorService executorService,
                                Callable<? extends T> computation)

Starts an asynchronous computation, backed by the given ExecutorService.

Type Parameters:

T - Type of the computation result.

Parameters:

executorService - An executor service.

computation - A computation.

Returns:

A new Future instance

Throws:

NullPointerException - if one of executorService or computation is null.

runRunnable

static Future<Void> runRunnable(Runnable computation)

Starts an asynchronous computation, backed by the DEFAULT_EXECUTOR_SERVICE.

Parameters:

computation - A computation

Returns:

A new Future instance

Throws:

NullPointerException - if computation is null.

runRunnable

static Future<Void> runRunnable(ExecutorService executorService,
                                Runnable computation)

Starts an asynchronous computation, backed by the given ExecutorService.

Parameters:

executorService - An executor service.

computation - A computation.

Returns:

A new Future instance

Throws:

NullPointerException - if one of executorService or computation is null.

of

static <T> Future<T> of(CheckedFunction0<? extends T> computation)

Starts an asynchronous computation, backed by the DEFAULT_EXECUTOR_SERVICE.

Type Parameters:

T - Type of the computation result.

Parameters:

computation - A computation.

Returns:

A new Future instance.

Throws:

NullPointerException - if computation is null.

of

static <T> Future<T> of(ExecutorService executorService,
                        CheckedFunction0<? extends T> computation)

Starts an asynchronous computation, backed by the given ExecutorService.

Type Parameters:

T - Type of the computation result.

Parameters:

executorService - An executor service.

computation - A computation.

Returns:

A new Future instance.

Throws:

NullPointerException - if one of executorService or computation is null.

reduce

static <T> Future<T> reduce(Iterable<? extends Future<? extends T>> futures,
                            BiFunction<? super T,? super T,? extends T> f)

Returns a Future which contains the reduce result of the given future values. The zero is the result of the first future that completes. If any future or the reduce operation fail, the result is a failure.

The resulting Future is backed by the DEFAULT_EXECUTOR_SERVICE.

Type Parameters:

T - The result type of the given Futures.

Parameters:

futures - An iterable of futures.

f - The reduce operation.

Returns:

A new Future that will contain the reduce result.

Throws:

NullPointerException - if executorService, futures or f is null.

reduce

static <T> Future<T> reduce(ExecutorService executorService,
                            Iterable<? extends Future<? extends T>> futures,
                            BiFunction<? super T,? super T,? extends T> f)

Returns a Future which contains the reduce result of the given future values. The zero is the result of the first future that completes. If any future or the reduce operation fail, the result is a failure.

The resulting Future is backed by the given ExecutorService.

Type Parameters:

T - The result type of the given Futures.

Parameters:

executorService - An ExecutorService.

futures - An iterable of futures.

f - The reduce operation.

Returns:

A new Future that will contain the reduce result.

Throws:

NullPointerException - if executorService, futures or f is null.

run

static Future<Void> run(CheckedRunnable unit)

Runs an asynchronous computation, backed by the DEFAULT_EXECUTOR_SERVICE.

Parameters:

unit - A unit of work.

Returns:

A new Future instance which results in nothing.

Throws:

NullPointerException - if unit is null.

run

static Future<Void> run(ExecutorService executorService,
                        CheckedRunnable unit)

Starts an asynchronous computation, backed by the given ExecutorService.

Parameters:

executorService - An executor service.

unit - A unit of work.

Returns:

A new Future instance which results in nothing.

Throws:

NullPointerException - if one of executorService or unit is null.

sequence

static <T> Future<Seq<T>> sequence(Iterable<? extends Future<? extends T>> futures)

Reduces many Futures into a single Future by transforming an Iterable<Future<? extends T>> into a Future<Seq<T>>.

The resulting Future is backed by the DEFAULT_EXECUTOR_SERVICE.

• If all of the given Futures succeed, sequence() succeeds too:

  // = Future(Success(Seq(1, 2)))
   sequence(
       List.of(
           Future.of(() -> 1),
           Future.of(() -> 2)
       )
   );

• If a given Future fails, sequence() fails too:

  // = Future(Failure(Error)))
   sequence(
       List.of(
           Future.of(() -> 1),
           Future.of(() -> { throw new Error(); }
       )
   );

Type Parameters:

T - Result type of the futures.

Parameters:

futures - An Iterable of Futures.

Returns:

A Future of a Seq of results.

Throws:

NullPointerException - if futures is null.

sequence

static <T> Future<Seq<T>> sequence(ExecutorService executorService,
                                   Iterable<? extends Future<? extends T>> futures)

Reduces many Futures into a single Future by transforming an Iterable<Future<? extends T>> into a Future<Seq<T>>.

The resulting Future is backed by the given ExecutorService.

Type Parameters:

T - Result type of the futures.

Parameters:

executorService - An ExecutorService.

futures - An Iterable of Futures.

Returns:

A Future of a Seq of results.

Throws:

NullPointerException - if executorService or futures is null.

successful

static <T> Future<T> successful(T result)

Creates a succeeded Future, backed by the DEFAULT_EXECUTOR_SERVICE.

Type Parameters:

T - The value type of a successful result.

Parameters:

result - The result.

Returns:

A succeeded Future.

successful

static <T> Future<T> successful(ExecutorService executorService,
                                T result)

Creates a succeeded Future, backed by the given ExecutorService.

Type Parameters:

T - The value type of a successful result.

Parameters:

executorService - An ExecutorService.

result - The result.

Returns:

A succeeded Future.

Throws:

NullPointerException - if executorService is null

toCompletableFuture

@GwtIncompatible
default CompletableFuture<T> toCompletableFuture()

Description copied from interface: Value

Converts this to a CompletableFuture

Specified by:

toCompletableFuture in interface Value<T>

Returns:

A new CompletableFuture containing the value

traverse

static <T,U> Future<Seq<U>> traverse(Iterable<? extends T> values,
                                     Function<? super T,? extends Future<? extends U>> mapper)

Maps the values of an iterable in parallel to a sequence of mapped values into a single Future by transforming an Iterable<? extends T> into a Future<Seq<U>>.

The resulting Future is backed by the DEFAULT_EXECUTOR_SERVICE.

Type Parameters:

T - The type of the given values.

U - The mapped value type.

Parameters:

values - An Iterable of Futures.

mapper - A mapper of values to Futures

Returns:

A Future of a Seq of results.

Throws:

NullPointerException - if values or f is null.

traverse

static <T,U> Future<Seq<U>> traverse(ExecutorService executorService,
                                     Iterable<? extends T> values,
                                     Function<? super T,? extends Future<? extends U>> mapper)

Maps the values of an iterable in parallel to a sequence of mapped values into a single Future by transforming an Iterable<? extends T> into a Future<Seq<U>>.

The resulting Future is backed by the given ExecutorService.

Type Parameters:

T - The type of the given values.

U - The mapped value type.

Parameters:

executorService - An ExecutorService.

values - An Iterable of values.

mapper - A mapper of values to Futures

Returns:

A Future of a Seq of results.

Throws:

NullPointerException - if executorService, values or f is null.

andThen

default Future<T> andThen(Consumer<? super Try<T>> action)

Support for chaining of callbacks that are guaranteed to be executed in a specific order.

An exception, which occurs when performing the given action, is not propagated to the outside. In other words, subsequent actions are performed based on the value of the original Future.

Example:

 // prints Success(1)
 Future.of(() -> 1)
       .andThen(t -> { throw new Error(""); })
       .andThen(System.out::println);
 

Parameters:

action - A side-effecting action.

Returns:

A new Future that contains this result and which is completed after the given action was performed.

Throws:

NullPointerException - if action is null

await

Future<T> await()

Blocks the current Thread until this Future completed or returns immediately if this Future is already completed.

Returns:

this Future instance

cancel

default boolean cancel()

Cancels the Future. A running thread is interrupted.

If the Future was successfully cancelled, the result is a Failure(CancellationException).

Returns:

false, if this Future is already completed or could not be cancelled, otherwise true.

cancel

boolean cancel(boolean mayInterruptIfRunning)

Cancels the Future. A pending Future may be interrupted, depending on the underlying ExecutionService.

If the Future was successfully cancelled, the result is a Failure(CancellationException).

Parameters:

mayInterruptIfRunning - true if a running thread should be interrupted, otherwise a running thread is allowed to complete its computation.

Returns:

false, if this Future is already completed or could not be cancelled, otherwise true.

See Also:

Future.cancel(boolean)

collect

default <R> Future<R> collect(PartialFunction<? super T,? extends R> partialFunction)

Collects value that is in the domain of the given partialFunction by mapping the value to type R.

 partialFunction.isDefinedAt(value)
 

If the element makes it through that filter, the mapped instance is wrapped in Future

 R newValue = partialFunction.apply(value)
 

Type Parameters:

R - The new value type

Parameters:

partialFunction - A function that is not necessarily defined on value of this future.

Returns:

A new Future instance containing value of type R

Throws:

NullPointerException - if partialFunction is null

executorService

ExecutorService executorService()

Returns the ExecutorService used by this Future.

Returns:

The underlying ExecutorService.

failed

default Future<Throwable> failed()

A projection that inverses the result of this Future.

If this Future succeeds, the failed projection returns a failure containing a NoSuchElementException.

If this Future fails, the failed projection returns a success containing the exception.

Returns:

A new Future which contains an exception at a point of time.

fallbackTo

default Future<T> fallbackTo(Future<? extends T> that)

Returns a Future that returns the result of this Future, if it is a success. If the value of this Future is a failure, the result of that Future is returned, if that is a success. If both Futures fail, the failure of this Future is returned.

Example:

 Future<Integer> future = Future.of(() -> { throw new Error(); });
 Future<Integer> that = Future.of(() -> 1);
 Future<Integer> result = future.fallbackTo(that);

 // prints Some(1)
 result.onComplete(System.out::println);
 

Parameters:

that - A fallback future computation

Returns:

A new Future

Throws:

NullPointerException - if that is null

filter

default Future<T> filter(Predicate<? super T> predicate)

Shortcut for filterTry(predicate::test.

Parameters:

predicate - A predicate

Returns:

A new Future

Throws:

NullPointerException - if predicate is null

filterTry

default Future<T> filterTry(CheckedPredicate<? super T> predicate)

Filters the result of this Future by calling Try.filterTry(CheckedPredicate).

Parameters:

predicate - A checked predicate

Returns:

A new Future

Throws:

NullPointerException - if predicate is null

getCause

default Option<Throwable> getCause()

Returns the underlying exception of this Future, syntactic sugar for future.getValue().map(Try::getCause).

Returns:

None if the Future is not completed yet. Returns Some(Throwable) if the Future was completed with a failure.

Throws:

UnsupportedOperationException - if the Future was successfully completed with a value

getValue

Option<Try<T>> getValue()

Returns the value of the Future.

Returns:

None, if the Future is not yet completed or was cancelled, otherwise Some(Try).

isCompleted

boolean isCompleted()

Checks if this Future is completed, i.e. has a value.

Returns:

true, if the computation successfully finished, failed or was cancelled, false otherwise.

isSuccess

default boolean isSuccess()

Checks if this Future completed with a success.

Returns:

true, if this Future completed and is a Success, false otherwise.

isFailure

default boolean isFailure()

Checks if this Future completed with a failure.

Returns:

true, if this Future completed and is a Failure, false otherwise.

onComplete

Future<T> onComplete(Consumer<? super Try<T>> action)

Performs the action once the Future is complete.

Parameters:

action - An action to be performed when this future is complete.

Returns:

this Future

Throws:

NullPointerException - if action is null.

onFailure

default Future<T> onFailure(Consumer<? super Throwable> action)

Performs the action once the Future is complete and the result is a Try.Failure. Please note that the future is also a failure when it was cancelled.

Parameters:

action - An action to be performed when this future failed.

Returns:

this Future

Throws:

NullPointerException - if action is null.

onSuccess

default Future<T> onSuccess(Consumer<? super T> action)

Performs the action once the Future is complete and the result is a Try.Success.

Parameters:

action - An action to be performed when this future succeeded.

Returns:

this Future

Throws:

NullPointerException - if action is null.

recover

default Future<T> recover(Function<? super Throwable,? extends T> f)

Handles a failure of this Future by returning another result.

Example:

 // = "oh!"
 Future.of(() -> new Error("oh!")).recover(Throwable::getMessage);
 

Parameters:

f - A function which takes the exception of a failure and returns a new value.

Returns:

A new Future.

Throws:

NullPointerException - if f is null

recoverWith

default Future<T> recoverWith(Function<? super Throwable,? extends Future<? extends T>> f)

Handles a failure of this Future by returning the result of another Future.

Example:

 // = "oh!"
 Future.of(() -> { throw new Error("oh!"); }).recoverWith(x -> Future.of(x::getMessage));
 

Parameters:

f - A function which takes the exception of a failure and returns a new future.

Returns:

A new Future.

Throws:

NullPointerException - if f is null

transform

default <U> U transform(Function<? super Future<T>,? extends U> f)

Transforms this Future.

Type Parameters:

U - Type of transformation result

Parameters:

f - A transformation

Returns:

An instance of type U

Throws:

NullPointerException - if f is null

transformValue

default <U> Future<U> transformValue(Function<? super Try<T>,? extends Try<? extends U>> f)

Transforms the value of this Future, whether it is a success or a failure.

Type Parameters:

U - Generic type of transformation Try result

Parameters:

f - A transformation

Returns:

A Future of type U

Throws:

NullPointerException - if f is null

zip

default <U> Future<Tuple2<T,U>> zip(Future<? extends U> that)

Returns a tuple of this and that Future result.

If this Future failed the result contains this failure. Otherwise the result contains that failure or a tuple of both successful Future results.

Type Parameters:

U - Result type of that

Parameters:

that - Another Future

Returns:

A new Future that returns both Future results.

Throws:

NullPointerException - if that is null

zipWith

default <U,R> Future<R> zipWith(Future<? extends U> that,
                                BiFunction<? super T,? super U,? extends R> combinator)

Returns a this and that Future result combined using a given combinator function.

If this Future failed the result contains this failure. Otherwise the result contains that failure or a combination of both successful Future results.

Type Parameters:

U - Result type of that

R - Result type of f

Parameters:

that - Another Future

combinator - The combinator function

Returns:

A new Future that returns both Future results.

Throws:

NullPointerException - if that is null

flatMap

default <U> Future<U> flatMap(Function<? super T,? extends Future<? extends U>> mapper)

flatMapTry

default <U> Future<U> flatMapTry(CheckedFunction1<? super T,? extends Future<? extends U>> mapper)

forEach

default void forEach(Consumer<? super T> action)

Performs the given action asynchronously hence this Future result becomes available. The action is not performed, if the result is a failure.

Specified by:

forEach in interface Iterable<T>

Specified by:

forEach in interface Value<T>

Parameters:

action - A Consumer

get

default T get()

Gets the value if the computation result is a Success or throws if it was a Failure. Waits for the result if necessary by blocking the current thread.

IMPORTANT! If the computation result is a Try.Failure, the underlying cause of type Throwable is thrown.

Specified by:

get in interface Value<T>

Returns:

The value of this Future.

isAsync

default boolean isAsync()

A Futures's value is computed asynchronously.

Specified by:

isAsync in interface Value<T>

Returns:

true

isEmpty

default boolean isEmpty()

Checks, if this future has a value.

Specified by:

isEmpty in interface Value<T>

Returns:

true, if this future succeeded with a value, false otherwise.

isLazy

default boolean isLazy()

A Future's value is computed eagerly.

Specified by:

isLazy in interface Value<T>

Returns:

false

isSingleValued

default boolean isSingleValued()

A Future is single-valued.

Specified by:

isSingleValued in interface Value<T>

Returns:

true

iterator

default Iterator<T> iterator()

Description copied from interface: Value

Returns a rich io.vavr.collection.Iterator.

Specified by:

iterator in interface Iterable<T>

Specified by:

iterator in interface Value<T>

Returns:

A new Iterator

map

default <U> Future<U> map(Function<? super T,? extends U> mapper)

Description copied from interface: Value

Maps the underlying value to a different component type.

Specified by:

map in interface Value<T>

Type Parameters:

U - The new component type

Parameters:

mapper - A mapper

Returns:

A new value

mapTry

default <U> Future<U> mapTry(CheckedFunction1<? super T,? extends U> mapper)

orElse

default Future<T> orElse(Future<? extends T> other)

orElse

default Future<T> orElse(Supplier<? extends Future<? extends T>> supplier)

peek

default Future<T> peek(Consumer<? super T> action)

Description copied from interface: Value

Performs the given action on the first element if this is an eager implementation. Performs the given action on all elements (the first immediately, successive deferred), if this is a lazy implementation.

Specified by:

peek in interface Value<T>

Parameters:

action - The action that will be performed on the element(s).

Returns:

this instance

stringPrefix

default String stringPrefix()

Description copied from interface: Value

Returns the name of this Value type, which is used by toString().

Specified by:

stringPrefix in interface Value<T>

Returns:

This type name.