Package org.opennms.core.concurrent

Class FutureUtils

java.lang.Object

org.opennms.core.concurrent.FutureUtils

public class FutureUtils
extends Object

Provides utility functions for creating and combining completion stages.

In general, completable futures do not interrupt ongoing executions when cancelled (cf. CompletableFuture.cancel(boolean)). This class provides utility methods for creating completion stages that cancel ongoing computations in case of timeouts. Depending on the supplied executor service these cancellations will cause the interruption of ongoing executions.

Note: Do not use a ForkJoinTask when construction these completion stages because ForkJoinTask.cancel(boolean) does not interrupt ongoing executions.

Other utility methods allow to collect the results of lists of completion stages into single list valued completion stage.

Constructor Summary

Constructors

Constructor	Description
FutureUtils()

Method Summary

Modifier and Type	Method	Description
static <T> CompletionStage<T>	completionStage(Callable<T> callable, java.time.Duration timeout, java.util.function.Consumer<CompletableFuture<T>> onTimeout, ExecutorService executorService)	Returns a completion stage that is guaranteed to complete.
static <T> CompletionStage<T>	completionStageWithDefaultOnTimeout(Callable<T> callable, java.time.Duration timeout, java.util.function.Supplier<T> defaultValue, ExecutorService executorService)	Returns a completion stage that is guaranteed to complete.
static <T,EX extends Throwable> CompletionStage<T>	completionStageWithTimeoutException(Callable<T> callable, java.time.Duration timeout, java.util.function.Supplier<EX> timeoutException, ExecutorService executorService)	Returns a completion stage that is guaranteed to complete.
static <T> CompletionStage<List<T>>	sequence(List<CompletionStage<T>> cfs)	Collects the results of the futures into a list.
static <U,V> CompletionStage<List<V>>	traverse(List<U> us, java.util.function.Function<U,CompletionStage<V>> func)	Converts a list of values into futures and collects their results.

Methods inherited from class java.lang.Object

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

Constructor Detail

FutureUtils

public FutureUtils()

Method Detail

completionStageWithDefaultOnTimeout

public static <T> CompletionStage<T> completionStageWithDefaultOnTimeout(Callable<T> callable,
                                                                         java.time.Duration timeout,
                                                                         java.util.function.Supplier<T> defaultValue,
                                                                         ExecutorService executorService)

Returns a completion stage that is guaranteed to complete.

It completes with the value returned by the given callable or the supplied default value in case of a timeout. In case the invocation of the callable throws an exception it completes exceptionally.

Note: The execution of the given callable is cancelled on timeout.

Parameters:

executorService - The executor service for executing the callable.

completionStageWithTimeoutException

public static <T,EX extends Throwable> CompletionStage<T> completionStageWithTimeoutException(Callable<T> callable,
                                                                                                    java.time.Duration timeout,
                                                                                                    java.util.function.Supplier<EX> timeoutException,
                                                                                                    ExecutorService executorService)

Returns a completion stage that is guaranteed to complete.

It completes with the value returned by the given callable. In case of a timeout or in case that the invocation of the callable throws an exception is completes exceptionally.

Note: The execution of the given callable is cancelled on timeout.

Parameters:

executorService - The executor service for executing the callable.

completionStage

public static <T> CompletionStage<T> completionStage(Callable<T> callable,
                                                     java.time.Duration timeout,
                                                     java.util.function.Consumer<CompletableFuture<T>> onTimeout,
                                                     ExecutorService executorService)

Returns a completion stage that is guaranteed to complete.

It completes with the value returned by the given callable. In case the invocation of the callable throws an exception it completes exceptionally. In case of a timeout the given callback must complete the completable future either with a value or exceptionally.

Note: The execution of the given callable is cancelled on timeout.

Parameters:

executorService - The executor service for executing the callable.

sequence

public static <T> CompletionStage<List<T>> sequence(List<CompletionStage<T>> cfs)

Collects the results of the futures into a list. The order of results in the list corresponds to the order of the given futures.

traverse

public static <U,V> CompletionStage<List<V>> traverse(List<U> us,
                                                            java.util.function.Function<U,CompletionStage<V>> func)

Converts a list of values into futures and collects their results. The order of the results in the list corresponds to the order of the given values.

All futures are created initially in order to start their execution in parallel.