Package io.github.futures4j

Class Futures

java.lang.Object

io.github.futures4j.Futures

public final class Futures
extends Object

Utility class for working with Future instances.

Provides methods and nested classes for combining, flattening, and manipulating multiple futures, including support for cancellation, aggregation, and transformation of results.

Author:

Sebastian Thomschke

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Futures.CombinedFuture<FROM,TO>	Represents a future that combines multiple futures into a single future.
static class	Futures.Combiner<T>	Builder class for aggregating multiple Future instances that return type T.
static class	Futures.FlatteningCombiner<T>	Builder class for aggregating multiple Future instances that return collections of type T, and flattening the results into a single collection.

Method Summary

Modifier and Type	Method	Description
static boolean	cancel(@Nullable Future<?> futureToCancel)	Cancels the future if it is incomplete, without interrupting running tasks.
static boolean	cancel(@Nullable Future<?> futureToCancel, boolean mayInterruptIfRunning)	Cancels the future if it is incomplete.
static boolean	cancelInterruptibly(@Nullable Future<?> futureToCancel)	Cancels the future if it is incomplete, interrupting if running.
static <T> Futures.Combiner<T>	combine(@Nullable Iterable<? extends @Nullable Future<? extends T>> futures)	Creates a new Futures.Combiner and adds the specified futures to it.
static <T> Futures.Combiner<T>	combine(Future<? extends T> @Nullable ... futures)	Creates a new Futures.Combiner and adds the specified futures to it.
static <T> Futures.FlatteningCombiner<T>	combineFlattened(@Nullable Iterable<? extends @Nullable Future<? extends @Nullable Iterable<? extends T>>> futures)	Creates a new Futures.FlatteningCombiner and adds the specified futures to it.
static <T> Futures.FlatteningCombiner<T>	combineFlattened(Future<? extends @Nullable Iterable<T>> @Nullable ... futures)	Creates a new Futures.FlatteningCombiner and adds the specified futures to it.
static void	forwardCancellation(CompletableFuture<?> from, @Nullable Collection<? extends @Nullable Future<?>> to)	Propagates the cancellation of a CompletableFuture to other Futures.
static void	forwardCancellation(CompletableFuture<?> from, @Nullable Future<?> to)	Propagates the cancellation of a CompletableFuture to another Future.
static void	forwardCancellation(CompletableFuture<?> from, Future<?> @Nullable ... to)	Propagates the cancellation of a CompletableFuture to other Futures.
static <T> Optional<T>	getNowOptional(Future<T> future)	Returns the result of the given Future if it is already completed, wrapped in an Optional, or an empty Optional if the future is incomplete, cancelled, or failed.
static <T> T	getNowOrComputeFallback(Future<T> future, BiFunction<Future<T>,@Nullable Exception,T> fallbackComputer)	Returns the result of the given Future if it is already completed, or the value computed by fallbackComputer if the future is incomplete or failed.
static <T> T	getNowOrComputeFallback(Future<T> future, Function<@Nullable Exception,T> fallbackComputer)	Returns the result of the given Future if it is already completed, or the value computed by fallbackComputer if the future is incomplete or failed.
static <T> T	getNowOrFallback(Future<T> future, T fallback)	Returns the result of the given Future if it is already completed, or the specified fallback if the future is incomplete or failed.
static <T> Optional<T>	getOptional(Future<T> future)	Attempts to retrieve the result of the given Future.
static <T> Optional<T>	getOptional(Future<T> future, long timeout, TimeUnit unit)	Attempts to retrieve the result of the given Future within the specified timeout.
static <T> T	getOrComputeFallback(Future<T> future, BiFunction<Future<T>,@Nullable Exception,T> fallbackComputer)	Waits for the given Future to complete and returns its result if it completes normally.
static <T> T	getOrComputeFallback(Future<T> future, BiFunction<Future<T>,@Nullable Exception,T> fallbackComputer, long timeout, TimeUnit unit)	Waits up to the specified timeout for the given Future to complete and returns its result if it completes normally.
static <T> T	getOrComputeFallback(Future<T> future, Function<@Nullable Exception,T> fallbackComputer)	Waits for the given Future to complete and returns its result if it completes normally.
static <T> T	getOrComputeFallback(Future<T> future, Function<@Nullable Exception,T> fallbackComputer, long timeout, TimeUnit unit)	Waits up to the specified timeout for the given Future to complete and returns its result if it completes normally.
static <T> T	getOrFallback(Future<T> future, T fallback)	Waits for the given Future to complete and returns its result if it completes normally.
static <T> T	getOrFallback(Future<T> future, T fallback, long timeout, TimeUnit unit)	Waits up to the specified timeout for the given Future to complete and returns its result if it completes normally.

Methods inherited from class java.lang.Object

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

Method Detail

cancel

public static boolean cancel(@Nullable Future<?> futureToCancel)

Cancels the future if it is incomplete, without interrupting running tasks.

Parameters:

futureToCancel - the future to cancel

Returns:

true if the future is now cancelled

cancel

public static boolean cancel(@Nullable Future<?> futureToCancel,
                             boolean mayInterruptIfRunning)

Cancels the future if it is incomplete.

Parameters:

futureToCancel - the future to cancel

mayInterruptIfRunning - true if the thread executing this task should be interrupted; otherwise, in-progress tasks are allowed to complete

Returns:

true if the future is now cancelled

cancelInterruptibly

public static boolean cancelInterruptibly(@Nullable Future<?> futureToCancel)

Cancels the future if it is incomplete, interrupting if running.

Parameters:

futureToCancel - the future to cancel

Returns:

true if the future is now cancelled

combine

@SafeVarargs
public static <T> Futures.Combiner<T> combine(@NonNullByDefault({})
                                              Future<? extends T> @Nullable ... futures)

Creates a new Futures.Combiner and adds the specified futures to it.

Type Parameters:

T - the type of the future results

Parameters:

futures - the futures to combine

Returns:

a new Combiner containing the specified futures

combine

public static <T> Futures.Combiner<T> combine(@Nullable Iterable<? extends @Nullable Future<? extends T>> futures)

Creates a new Futures.Combiner and adds the specified futures to it.

Type Parameters:

T - the type of the future results

Parameters:

futures - the futures to combine

Returns:

a new Combiner containing the specified futures

combineFlattened

@SafeVarargs
public static <T> Futures.FlatteningCombiner<T> combineFlattened(@NonNullByDefault({})
                                                                 Future<? extends @Nullable Iterable<T>> @Nullable ... futures)

Creates a new Futures.FlatteningCombiner and adds the specified futures to it.

Type Parameters:

T - the type of the future results

Parameters:

futures - the futures to combine

Returns:

a new FlatteningCombiner containing the specified futures

combineFlattened

public static <T> Futures.FlatteningCombiner<T> combineFlattened(@Nullable Iterable<? extends @Nullable Future<? extends @Nullable Iterable<? extends T>>> futures)

Creates a new Futures.FlatteningCombiner and adds the specified futures to it.

Type Parameters:

T - the type of the future results

Parameters:

futures - the futures to combine

Returns:

a new FlatteningCombiner containing the specified futures

forwardCancellation

public static void forwardCancellation(CompletableFuture<?> from,
                                       @Nullable Collection<? extends @Nullable Future<?>> to)

Propagates the cancellation of a CompletableFuture to other Futures.

If the specified from future is cancelled, all futures in the provided to collection will be cancelled too.

Parameters:

from - the CompletableFuture whose cancellation should be propagated

to - the collection of Future instances that should be cancelled if from is cancelled

forwardCancellation

public static void forwardCancellation(CompletableFuture<?> from,
                                       @Nullable Future<?> to)

Propagates the cancellation of a CompletableFuture to another Future.

If the specified from future is cancelled, the to future will be cancelled too.

Parameters:

from - the CompletableFuture whose cancellation should be propagated

to - the Future instance that should be cancelled if from is cancelled

forwardCancellation

public static void forwardCancellation(CompletableFuture<?> from,
                                       @NonNullByDefault({})
                                       Future<?> @Nullable ... to)

Propagates the cancellation of a CompletableFuture to other Futures.

If the specified from future is cancelled, all futures in the provided to array will be cancelled too.

Parameters:

from - the CompletableFuture whose cancellation should be propagated

to - the array of Future instances that should be cancelled if from is cancelled

getNowOptional

public static <T> Optional<T> getNowOptional(Future<T> future)

Returns the result of the given Future if it is already completed, wrapped in an Optional, or an empty Optional if the future is incomplete, cancelled, or failed.

Type Parameters:

T - the type of the future result

Parameters:

future - the future to get the result from

Returns:

an Optional containing the result if completed normally, or empty otherwise

getNowOrComputeFallback

public static <T> T getNowOrComputeFallback(Future<T> future,
                                            BiFunction<Future<T>,@Nullable Exception,T> fallbackComputer)

Returns the result of the given Future if it is already completed, or the value computed by fallbackComputer if the future is incomplete or failed.

Type Parameters:

T - the type of the future result

Parameters:

future - the future to get the result from

fallbackComputer - a function to compute the fallback value

Returns:

the result if completed normally, or the computed fallback value

getNowOrComputeFallback

public static <T> T getNowOrComputeFallback(Future<T> future,
                                            Function<@Nullable Exception,T> fallbackComputer)

Returns the result of the given Future if it is already completed, or the value computed by fallbackComputer if the future is incomplete or failed.

Type Parameters:

T - the type of the future result

Parameters:

future - the future to get the result from

fallbackComputer - a function to compute the fallback value

Returns:

the result if completed normally, or the computed fallback value

getNowOrFallback

public static <T> T getNowOrFallback(Future<T> future,
                                     T fallback)

Returns the result of the given Future if it is already completed, or the specified fallback if the future is incomplete or failed.

Type Parameters:

T - the type of the future result

Parameters:

future - the future to get the result from

fallback - the fallback value to return if the future is incomplete or failed

Returns:

the result if completed normally, or the fallback value

getOptional

public static <T> Optional<T> getOptional(Future<T> future)

Attempts to retrieve the result of the given Future.

Type Parameters:

T - the type of the future result

Parameters:

future - the future to get the result from

Returns:

an Optional containing the result if completed normally, or empty otherwise

getOptional

public static <T> Optional<T> getOptional(Future<T> future,
                                          long timeout,
                                          TimeUnit unit)

Attempts to retrieve the result of the given Future within the specified timeout.

Type Parameters:

T - the type of the future result

Parameters:

future - the future to get the result from

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

an Optional containing the result if completed within the timeout, or empty otherwise

getOrComputeFallback

public static <T> T getOrComputeFallback(Future<T> future,
                                         BiFunction<Future<T>,@Nullable Exception,T> fallbackComputer)

Waits for the given Future to complete and returns its result if it completes normally. If the future is interrupted, cancelled, or failed, the value computed by fallbackComputer is returned instead.

Type Parameters:

T - the type of the future result

Parameters:

future - the future to get the result from

fallbackComputer - a function to compute the fallback value

Returns:

the result if completed normally, or the computed fallback value

getOrComputeFallback

public static <T> T getOrComputeFallback(Future<T> future,
                                         BiFunction<Future<T>,@Nullable Exception,T> fallbackComputer,
                                         long timeout,
                                         TimeUnit unit)

Waits up to the specified timeout for the given Future to complete and returns its result if it completes normally. If the future is interrupted, timed out, cancelled, or failed, the value computed by fallbackComputer is returned instead.

Type Parameters:

T - the type of the future result

Parameters:

future - the future to get the result from

fallbackComputer - a function to compute the fallback value

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

the result if completed within the timeout, or the computed fallback value

getOrComputeFallback

public static <T> T getOrComputeFallback(Future<T> future,
                                         Function<@Nullable Exception,T> fallbackComputer)

Waits for the given Future to complete and returns its result if it completes normally. If the future is interrupted, cancelled, or failed, the value computed by fallbackComputer is returned instead.

Type Parameters:

T - the type of the future result

Parameters:

future - the future to get the result from

fallbackComputer - a function to compute the fallback value

Returns:

the result if completed normally, or the computed fallback value

getOrComputeFallback

public static <T> T getOrComputeFallback(Future<T> future,
                                         Function<@Nullable Exception,T> fallbackComputer,
                                         long timeout,
                                         TimeUnit unit)

Waits up to the specified timeout for the given Future to complete and returns its result if it completes normally. If the future is interrupted, timed out, cancelled, or failed, the value computed by fallbackComputer is returned instead.

Type Parameters:

T - the type of the future result

Parameters:

future - the future to get the result from

fallbackComputer - a function to compute the fallback value

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

the result if completed within the timeout, or the computed fallback value

getOrFallback

public static <T> T getOrFallback(Future<T> future,
                                  T fallback)

Waits for the given Future to complete and returns its result if it completes normally. If the future is interrupted, cancelled, or failed, the provided fallback value is returned instead.

Type Parameters:

T - the type of the future result

Parameters:

future - the future to get the result from

fallback - the fallback value to return if the future completes with an exception

Returns:

the result if completed normally, or the fallback value

getOrFallback

public static <T> T getOrFallback(Future<T> future,
                                  T fallback,
                                  long timeout,
                                  TimeUnit unit)

Waits up to the specified timeout for the given Future to complete and returns its result if it completes normally. If the future is interrupted, timed out, cancelled, or failed, the provided fallback value is returned instead.

Type Parameters:

T - the type of the future result

Parameters:

future - the future to get the result from

fallback - the fallback value to return if the future completes with an exception

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

the result if completed within the timeout, or the fallback value