de.fhg.fokus.xtensions.concurrent

Class CompletableFutureExtensions

java.lang.Object

de.fhg.fokus.xtensions.concurrent.CompletableFutureExtensions

public final class CompletableFutureExtensions
extends Object

This class provides static methods (many of them to be used as extension methods) that enrich the CompletableFuture class.

The extension methods for CompletableFuture make some common use cases easier. Some of these methods are:

• then(CompletableFuture, Function)
• then(CompletableFuture, Consumer)
• then(CompletableFuture, Runnable)
• whenCancelled(CompletableFuture<R>, ()=>void)
• whenException(CompletableFuture<R>, (Throwable)=>void)
• handleCancellation(CompletableFuture<R>, ()=>R)
• cancelOnTimeout(CompletableFuture, long, TimeUnit)
• cancelOnTimeout(CompletableFuture, ScheduledExecutorService, long, TimeUnit)
• forwardTo(CompletionStage, CompletableFuture)
• forwardCancellation(CompletableFuture, CompletableFuture)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CompletableFutureExtensions.TimeoutConfig An instance of this class will be passed to the configuration block passed to the orTimeout(CompletableFuture<R>, (TimeoutConfig)=>void) extension method.

Constructor Summary

Constructors

Constructor and Description
CompletableFutureExtensions()

Method Summary

Modifier and Type	Method and Description
static boolean	cancel(CompletableFuture<?> future) Calls CompletableFuture.cancel(boolean) on the given future with parameter false.
static <R> CompletableFuture<R>	cancelOnTimeout(CompletableFuture<R> fut, Duration timeout) This method calls cancelOnTimeout(CompletableFuture, long , TimeUnit) with a best effort converting the given Duration timeout to a long of TimeUnit.
static <R> CompletableFuture<R>	cancelOnTimeout(CompletableFuture<R> fut, long timeout, TimeUnit unit) Defines a timeout for the given future fut.
static <R> CompletableFuture<R>	cancelOnTimeout(CompletableFuture<R> fut, ScheduledExecutorService scheduler, long time, TimeUnit unit) Defines a timeout for the given future fut.
static <R> CompletionStage<R>	completeWith(CompletableFuture<? super R> toComplete, CompletionStage<R> with) This is the inverse operation of forwardTo.
static <R> CompletableFuture<R>	copy(CompletableFuture<R> fut) Returns a CompletableFuture that completes normally if the given CompletableFuture fut completes normally.
static <R> CompletableFuture<R>	exceptionallyAsync(CompletableFuture<? extends R> fut, Executor executor, Functions.Function1<? super Throwable,? extends R> handler) This is a version of exceptionally where the handler is executed on the given executor. The future returned by this method either completes successfully, if parameter fut completes successfully, or with the result of handler, if fut completes exceptionally.
static <R> CompletableFuture<R>	exceptionallyAsync(CompletableFuture<? extends R> fut, Functions.Function1<? super Throwable,? extends R> handler) This is a version of exceptionally where the handler is executed on the common ForkJoinPool. The future returned by this method either completes successfully, if parameter fut completes successfully, or with the result of handler, if fut completes exceptionally.
static void	forwardCancellation(CompletableFuture<?> from, CompletableFuture<?> to) Registers a callback on future from so when the future is cancelled, the future to will be attempted to be cancelled as well.
static void	forwardCancellation(CompletableFuture<?> from, CompletableFuture<?> to, CompletableFuture<?>... toRest) Registers a callback on future from so when the future is cancelled, the future to and all futures in toRest will be attempted to be cancelled as well.
static <R> CompletionStage<R>	forwardTo(CompletionStage<R> from, CompletableFuture<? super R> to) This function will forward the result of future from to future to.
static <R> CompletableFuture<R>	handleCancellation(CompletableFuture<R> fut, Functions.Function0<? extends R> handler) The effect of calling this method is like using CompletableFuture#exceptionally where the provided function is only called when fut is completed with a CancellationException.
static <R> CompletableFuture<R>	handleCancellationAsync(CompletableFuture<R> fut, Executor executor, Functions.Function0<? extends R> handler) The effect of calling this method is like using CompletableFuture#exceptionally where the provided function is only called when fut is completed with a CancellationException.
static <R> CompletableFuture<R>	handleCancellationAsync(CompletableFuture<R> fut, Functions.Function0<? extends R> handler) The effect of calling this method is like using CompletableFuture#exceptionally where the provided function is only called when fut is completed with a CancellationException.
static <R> CompletableFuture<R>	orTimeout(CompletableFuture<R> fut, long timeoutTime, TimeUnit unit) This extension function will create a new CompletableFuture that will either be completed with the result of fut (either successful or ), or if after the timeoutTime in time unit the future fut was not completed, the returned future will be completed exceptionally with a TimeoutException.
static <R> CompletableFuture<R>	orTimeout(CompletableFuture<R> fut, Procedures.Procedure1<? super CompletableFutureExtensions.TimeoutConfig> config) This method will return a future that will be completed exceptionally if the given CompletableFuture fut does not complete in a given timeout interval.
static <R> CompletableFuture<R>	recoverWith(CompletableFuture<R> fut, Functions.Function1<? super Throwable,? extends CompletionStage<? extends R>> recovery) If the given future fut completes successfully, the future returned from this method will be completed with the result value.
static <R> CompletableFuture<R>	recoverWithAsync(CompletableFuture<R> fut, Executor executor, Functions.Function1<? super Throwable,? extends CompletionStage<? extends R>> recovery) If the given future fut completes successfully, the future returned from this method will be completed with the result value.
static <R> CompletableFuture<R>	recoverWithAsync(CompletableFuture<R> fut, Functions.Function1<? super Throwable,? extends CompletionStage<? extends R>> recovery) If the given future fut completes successfully, the future returned from this method will be completed with the result value.
static CompletableFuture<Void>	then(CompletableFuture<?> fut, Runnable handler) This function is calling CompletableFuture.thenRun(Runnable) on fut, adapting handler as the parameter.
static <R> CompletableFuture<Void>	then(CompletableFuture<R> fut, Consumer<? super R> handler) This function is calling CompletableFuture.thenAccept(Consumer) on fut, adapting handler as the parameter.
static <R,U> CompletableFuture<U>	then(CompletableFuture<R> fut, Function<? super R,? extends U> handler) This function is calling CompletableFuture.thenApply(Function) on fut, adapting handler as the parameter.
static <R> CompletableFuture<R>	whenCancelled(CompletableFuture<R> fut, Procedures.Procedure0 handler) Registers handler on the given future fut to be called when the future is cancelled (meaning completed with an instance of CancellationException).
static <R> CompletableFuture<R>	whenCancelledAsync(CompletableFuture<R> fut, Executor executor, Procedures.Procedure0 handler) Registers handler on the given future fut to be called when the future is cancelled (meaning completed with an instance of CancellationException).
static <R> CompletableFuture<R>	whenCancelledAsync(CompletableFuture<R> fut, Procedures.Procedure0 handler) Registers handler on the given future fut to be called when the future is cancelled (meaning completed with an instance of CancellationException).
static void	whenCancelledInterrupt(CompletableFuture<?> fut, Procedures.Procedure0 interruptableBlock) This function helps integration of CompletableFuture and blocking APIs.
static <R> CompletableFuture<R>	whenException(CompletableFuture<R> fut, Procedures.Procedure1<? super Throwable> handler) Registers handler on the given future fut to be called when the future completes exceptionally.
static <R> CompletableFuture<R>	whenExceptionAsync(CompletableFuture<R> fut, Executor e, Procedures.Procedure1<? super Throwable> handler) Registers handler on the given future fut to be called when the future completes exceptionally.
static <R> CompletableFuture<R>	whenExceptionAsync(CompletableFuture<R> fut, Procedures.Procedure1<? super Throwable> handler) Registers handler on the given future fut to be called when the future completes exceptionally.

Methods inherited from class java.lang.Object

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

Constructor Detail

CompletableFutureExtensions

public CompletableFutureExtensions()

Method Detail

cancel

public static boolean cancel(CompletableFuture<?> future)

Calls CompletableFuture.cancel(boolean) on the given future with parameter false. Since the boolean parameter mayInterruptIfRunning has no influence on CompletableFuture instances anyway, this method provides a cancel method without the parameter.

Parameters:

future - the future to be cancelled

Returns:

true if the future is actually cancelled

See Also:

CompletableFuture.cancel(boolean)

cancelOnTimeout

public static <R> CompletableFuture<R> cancelOnTimeout(CompletableFuture<R> fut,
                                                       Duration timeout)

This method calls cancelOnTimeout(CompletableFuture, long , TimeUnit) with a best effort converting the given Duration timeout to a long of TimeUnit. May cause loss in time precision, if the overall timeout duration exceeds Long.MAX_VALUE nanoseconds, which is roughly a duration of 292.5 years. At most at most 999,999,999 nanoseconds (less than one second) may be stripped.

Type Parameters:

R - generic type of given fut

Parameters:

fut - the future to be cancelled after timeout, provided the future is not completed before cancellation.

timeout - specifies time to wait, before canceling fut. Must not be null.

Returns:

result of call to cancelOnTimeout(CompletableFuture, long, TimeUnit)

Throws:

NullPointerException - throws if fut or timeout is null

See Also:

cancelOnTimeout(CompletableFuture, long, TimeUnit)

cancelOnTimeout

public static <R> CompletableFuture<R> cancelOnTimeout(CompletableFuture<R> fut,
                                                       long timeout,
                                                       TimeUnit unit)

Defines a timeout for the given future fut. When the timeout is reached fut will be cancelled, if the future was not completed already. To determine the time to wait until performing the cancellation the time is specified by parameter timeout and the unit of time is specified by parameter unit. This method will create and use a scheduler internally to schedule the cancellation. To use an own scheduler, use method cancelOnTimeout(CompletableFuture, ScheduledExecutorService, long, TimeUnit).

Type Parameters:

R - generic type of given fut

Parameters:

fut - the future to be cancelled after timeout of time unit unit, provided the future is not completed before cancellation.

timeout - specifies time to wait, before canceling fut. Must be >=0

unit - specifies the time unit of timeout

Returns:

returns parameter fut

Throws:

NullPointerException - throws if fut or unit is null

See Also:

cancelOnTimeout(CompletableFuture, ScheduledExecutorService, long, TimeUnit)

cancelOnTimeout

public static <R> CompletableFuture<R> cancelOnTimeout(CompletableFuture<R> fut,
                                                       ScheduledExecutorService scheduler,
                                                       long time,
                                                       TimeUnit unit)

Defines a timeout for the given future fut. When the timeout is reached fut will be cancelled, if the future was not completed already. To determine the time to wait until performing the cancellation the time is specified by parameter timeout and the unit of time is specified by parameter unit. This method will the given scheduler to schedule the cancellation. If the scheduler should be provided for the caller, use method cancelOnTimeout(CompletableFuture, long, TimeUnit). This method is not responsible for shutting down the given scheduler

Type Parameters:

R - generic type of given fut

Parameters:

fut - future to be cancelled after timeout of time of time unit unit.

scheduler - the timeout will be scheduled and the cancellation executed on this scheduling pool.

time - timeout time in time unit unit after which fut will be cancelled.

unit - time unit of timeout time.

Returns:

same reference as parameter fut.

See Also:

cancelOnTimeout(CompletableFuture, long, TimeUnit)

forwardTo

public static <R> CompletionStage<R> forwardTo(CompletionStage<R> from,
                                               CompletableFuture<? super R> to)
                                        throws NullPointerException

This function will forward the result of future from to future to. This is independent of the result, this could be a regular or exceptional result (which includes cancellation). If future to was completed before from got completed the attempt to forward will fail without further feedback to the caller of this method. Returns a CompletableFuture that completes after to was completed with the same result as the original, which includes cancellation

Type Parameters:

R - generic type of given from must be accepted by to as type to complete with.

Parameters:

from - the result of this future will be forwarded to future to

to - the result of from will be forwarded to this future.

Returns:

a CompletableFuture that will complete after the forwarding is complete.

Throws:

NullPointerException - if from or to is null

completeWith

public static <R> CompletionStage<R> completeWith(CompletableFuture<? super R> toComplete,
                                                  CompletionStage<R> with)

This is the inverse operation of forwardTo. This method will simply call forwardTo parameters in switched order.

Type Parameters:

R - generic type of given with, must be accepted by toComplete as type to compete with.

Parameters:

toComplete - the future that will be completed with the result of with.

with - the future that provides the result that will be forwarded to toComplete.

Returns:

a CompletableFuture that will complete after the forwarding is complete.

See Also:

forwardTo(CompletionStage, CompletableFuture)

whenCancelledInterrupt

public static void whenCancelledInterrupt(CompletableFuture<?> fut,
                                          Procedures.Procedure0 interruptableBlock)

This function helps integration of CompletableFuture and blocking APIs. Blocking APIs may allow cancellation via interrupting the thread the blocking call is performed on. When a blocking call is performed on a thread pool it is crucial that the interruption is visible to other tasks that may be run on the thread. This function is a bridge between cancellation of CompletableFuture and thread interruption for blocking APIs. The interruptableBlock is called by this method and only while the block is executed cancellation of the future passed as parameter fut will lead to interruption of the current thread executing this method and the interruptableBlock. Thrown exceptions will be thrown to the caller of this method.
After this method the interrupted flag of this thread is unset, even when the block throws an exception. This way the thread calling this can safely be a pooled thread and may not interrupt some other task submitted to the thread pool managing the thread.
This is an example of how this message could be used:

 
 import static extension de.fhg.fokus.xtensions.concurrent.AsyncCompute.
 import static extension de.fhg.fokus.xtensions.concurrent.CompletableFutureExtensions.
 // ...
 val blockOpPool = Executors.newCachedThreadPool
 // ...
 val sleepy = blockOpPool.asyncRun [
   whenCancelledInterrupt [|
     try {
       Thread.sleep(100)
     } catch (InterruptedException e) {
       println("Hey, I was cancelled")
     }
   ]
 ]
 sleepy.cancel // may interrupt Thread.sleep
 
 

Parameters:

fut - future that if cancelled will interrupt the thread calling interruptableBlock. But only as long as the thread is in the interruptableBlock.

interruptableBlock - the block of code that is executed on the thread calling this method. If fut is cancelled during execution of the block, the calling thread will be interrupted. After execution of this block the thread's interrupted flag will be reset. This is also guaranteed if the block of code throws an exception.

Throws:

NullPointerException - will be thrown if fut or interruptableBlock is null.

handleCancellation

public static <R> CompletableFuture<R> handleCancellation(CompletableFuture<R> fut,
                                                          Functions.Function0<? extends R> handler)

The effect of calling this method is like using CompletableFuture#exceptionally where the provided function is only called when fut is completed with a CancellationException. If fut completes exceptionally, but not with a CancellationException, the exception is re-thrown from the handler, so the returned future will be completed exceptionally with the same exception.

Type Parameters:

R - generic type of given fut and returned future

Parameters:

fut - future handler is registered on. Must not be null.

handler - the callback to be invoked when fut is completed with cancellation. Must not be null.

Returns:

new CompletableFuture that either is completed with the result of fut, if fut completes successful. Otherwise the result provided from handler is used to complete the returned future.

Throws:

NullPointerException - is thrown when fut or handler is null.

handleCancellationAsync

public static <R> CompletableFuture<R> handleCancellationAsync(CompletableFuture<R> fut,
                                                               Functions.Function0<? extends R> handler)

The effect of calling this method is like using CompletableFuture#exceptionally where the provided function is only called when fut is completed with a CancellationException. If fut completes exceptionally, but not with a CancellationException, the exception is re-thrown from the handler, so the returned future will be completed exceptionally with the same exception. The handler will be invoked on the common pool, not on the thread completing fut.

Type Parameters:

R - generic type of given fut and type of value the handler to recover cancellation.

Parameters:

fut - future handler is registered on. Must not be null.

handler - the callback to be invoked when fut is completed with cancellation. Must not be null. Will be invoked on the common pool, not on the thread completing fut.

Returns:

new CompletableFuture that either is completed with the result of fut, if fut completes successful. Otherwise the result provided from handler is used to complete the returned future.

Throws:

NullPointerException - is thrown when fut or handler is null.

handleCancellationAsync

public static <R> CompletableFuture<R> handleCancellationAsync(CompletableFuture<R> fut,
                                                               Executor executor,
                                                               Functions.Function0<? extends R> handler)

The effect of calling this method is like using CompletableFuture#exceptionally where the provided function is only called when fut is completed with a CancellationException. If fut completes exceptionally, but not with a CancellationException, the exception is re-thrown from the handler, so the returned future will be completed exceptionally with the same exception. The handler will be invoked using the Executor e, not on the thread completing fut.

Type Parameters:

R - generic type of given fut and type of value the handler to recover cancellation.

Parameters:

fut - future handler is registered on. Must not be null.

executor - the executor used to execute the given handler callback.

handler - the callback to be invoked when fut is completed with cancellation. Must not be null. Will be invoked via the Executor e, not on the thread completing fut.

Returns:

new CompletableFuture that either is completed with the result of fut, if fut completes successful. Otherwise the result provided from handler is used to complete the returned future.

Throws:

NullPointerException - is thrown when fut or handler is null.

exceptionallyAsync

public static <R> CompletableFuture<R> exceptionallyAsync(CompletableFuture<? extends R> fut,
                                                          Functions.Function1<? super Throwable,? extends R> handler)

This is a version of exceptionally where the handler is executed on the common ForkJoinPool.
The future returned by this method either completes successfully, if parameter fut completes successfully, or with the result of handler, if fut completes exceptionally. If handler throws an exception, the returned future will complete exceptionally with the thrown exception.

Type Parameters:

R - generic type of given fut and type of value the handler to recover from exception.

Parameters:

fut - Future that's successful result will be forwarded to the returned future. If this future completes exceptionally handler will be called to determine the completion result of the returned future.

handler - If fut completes exceptionally, this handler will be called to determine the result that will be set on the future returned by this method. If handler throws an exception, the returned future completes exceptionally with the exception thrown by handler. The handler not be null.

Returns:

new future that will either complete with the result of fut, if it completes successfully, or with the result provided by handler if fut completes exceptionally.

Throws:

NullPointerException - if fut or handle is null.

See Also:

exceptionallyAsync(CompletableFuture, Executor, org.eclipse.xtext.xbase.lib.Functions.Function1)

exceptionallyAsync

public static <R> CompletableFuture<R> exceptionallyAsync(CompletableFuture<? extends R> fut,
                                                          Executor executor,
                                                          Functions.Function1<? super Throwable,? extends R> handler)

This is a version of exceptionally where the handler is executed on the given executor.
The future returned by this method either completes successfully, if parameter fut completes successfully, or with the result of handler, if fut completes exceptionally. If handler throws an exception, the returned future will complete exceptionally with the thrown exception.

Type Parameters:

R - generic type of given fut and type of value the handler to recover from exception.

Parameters:

fut - Future that's successful result will be forwarded to the returned future. If this future completes exceptionally handler will be called to determine the completion result of the returned future.

executor - the executor used to check on the result of fut and execution of handler.

handler - If fut completes exceptionally, this handler will be called to determine the result that will be set on the future returned by this method. If handler throws an exception, the returned future completes exceptionally with the exception thrown by handler. The handler not be null.

Returns:

new future that will either complete with the result of fut, if it completes successfully, or with the result provided by handler if fut completes exceptionally.

Throws:

NullPointerException - if fut, executor, or handle is null.

See Also:

exceptionallyAsync(CompletableFuture, org.eclipse.xtext.xbase.lib.Functions.Function1)

whenCancelled

public static <R> CompletableFuture<R> whenCancelled(CompletableFuture<R> fut,
                                                     Procedures.Procedure0 handler)

Registers handler on the given future fut to be called when the future is cancelled (meaning completed with an instance of CancellationException).

Type Parameters:

R - generic type of given fut and returned future.

Parameters:

fut - the future handler is registered on for notification about cancellation. Must not be null.

handler - callback to be registered on fut, being called when the future gets cancelled. Must not be null.

Returns:

a CompletableFuture that will complete after the handler completes or if fut completes without being cancelled. If fut is cancelled the returned future will be completed exceptionally with a CancellationException, but will not itself count as cancelled (isCancelled will return false). When the original future completes exceptionally, callback methods on the returned future will provide a CompletionException wrapping the original exception. This includes CancellationExceptions.

Throws:

NullPointerException - if fut or handler is null.

whenCancelledAsync

public static <R> CompletableFuture<R> whenCancelledAsync(CompletableFuture<R> fut,
                                                          Procedures.Procedure0 handler)

Registers handler on the given future fut to be called when the future is cancelled (meaning completed with an instance of CancellationException). The handler will be invoked on the common pool, not on the thread completing fut.

Type Parameters:

R - generic type of given fut and returned future.

Parameters:

fut - the future handler is registered on for notification about cancellation. Must not be null.

handler - callback to be registered on fut, being called when the future gets cancelled. Must not be null. Will be called on the common pool.

Returns:

a CompletableFuture that will complete after the handler completes or if fut completes without being cancelled. If fut is cancelled the returned future will be completed exceptionally with a CancellationException, but will not itself count as cancelled (isCancelled will return false). When the original future completes exceptionally, callback methods on the returned future will provide a CompletionException wrapping the original exception. This includes CancellationExceptions.

Throws:

NullPointerException - if fut or handler is null.

whenCancelledAsync

public static <R> CompletableFuture<R> whenCancelledAsync(CompletableFuture<R> fut,
                                                          Executor executor,
                                                          Procedures.Procedure0 handler)

Registers handler on the given future fut to be called when the future is cancelled (meaning completed with an instance of CancellationException). The handler will be invoked on the Executor e, not on the thread completing fut.

Type Parameters:

R - generic type of given fut and returned future.

Parameters:

fut - the future handler is registered on for notification about cancellation. Must not be null.

executor - the executor used to execute the given handler callback.

handler - callback to be registered on fut, being called when the future gets cancelled. Must not be null. Will be called on the Executor e.

Returns:

a CompletableFuture that will complete after the handler completes or if fut completes without being cancelled. If fut is cancelled the returned future will be completed exceptionally with a CancellationException, but will not itself count as cancelled (isCancelled will return false). When the original future completes exceptionally, callback methods on the returned future will provide a CompletionException wrapping the original exception. This includes CancellationExceptions.

Throws:

NullPointerException - if fut or handler is null.

whenException

public static <R> CompletableFuture<R> whenException(CompletableFuture<R> fut,
                                                     Procedures.Procedure1<? super Throwable> handler)

Registers handler on the given future fut to be called when the future completes exceptionally. This also includes cancellation.

Type Parameters:

R - generic type of given fut and returned future.

Parameters:

fut - the future handler is registered on for notification about exceptional completion. Must not be null.

handler - callback to be registered on fut, being called when the future completes with an exception. If the handler throws an exception, the returned future will be completed with the original exception. The handler must not be null.

Returns:

a CompletableFuture that will complete after the handler completes or if fut completes successfully. If fut completes exceptionally the returned future will be completed exceptionally with the same exception.

Throws:

NullPointerException - if fut or handler is null.

whenExceptionAsync

public static <R> CompletableFuture<R> whenExceptionAsync(CompletableFuture<R> fut,
                                                          Procedures.Procedure1<? super Throwable> handler)

Registers handler on the given future fut to be called when the future completes exceptionally. This also includes cancellation. The handler will be executed on the common pool, not on the thread completing fut.

Type Parameters:

R - generic type of given fut and returned future.

Parameters:

fut - the future handler is registered on for notification about exceptional completion. Must not be null.

handler - callback to be registered on fut, being called when the future completes with an exception. If the handler throws an exception, the returned future will be completed with the original exception. The handler must not be null. The handler will be executed on the common pool.

Returns:

a CompletableFuture that will complete after the handler completes or if fut completes successfully. If fut completes exceptionally the returned future will be completed exceptionally with the same exception.

Throws:

NullPointerException - if fut or handler is null.

whenExceptionAsync

public static <R> CompletableFuture<R> whenExceptionAsync(CompletableFuture<R> fut,
                                                          Executor e,
                                                          Procedures.Procedure1<? super Throwable> handler)

Registers handler on the given future fut to be called when the future completes exceptionally. This also includes cancellation. The handler will be executed on the Executor e, not on the thread completing fut.

Type Parameters:

R - generic type of given fut and returned future.

Parameters:

fut - the future handler is registered on for notification about exceptional completion. Must not be null.

handler - callback to be registered on fut, being called when the future completes with an exception. If the handler throws an exception, the returned future will be completed with the original exception. The handler must not be null. The handler will be executed on the Executor e.

e - Executor used to execute handler

Returns:

a CompletableFuture that will complete after the handler completes or if fut completes successfully. If fut completes exceptionally the returned future will be completed exceptionally with the same exception.

Throws:

NullPointerException - if fut or handler is null.

forwardCancellation

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

Registers a callback on future from so when the future is cancelled, the future to will be attempted to be cancelled as well. If by the time to is already completed, the cancellation of from will have no affect.

Parameters:

from - if this future is cancelled, to will be tried to be cancelled as well.. Must not be null.

to - future to be cancelled when from is cancelled.

Throws:

NullPointerException - thrown if from or to is null

forwardCancellation

public static void forwardCancellation(CompletableFuture<?> from,
                                       CompletableFuture<?> to,
                                       CompletableFuture<?>... toRest)

Registers a callback on future from so when the future is cancelled, the future to and all futures in toRest will be attempted to be cancelled as well. If by the time to or futures in toRest is already completed, the cancellation of from will have no affect on the respective future.

Parameters:

from - if this future is cancelled, to will be tried to be cancelled as well.. Must not be null.

to - first future to be cancelled when from is cancelled. Must not be null and must not contain any null references.

toRest - additional futures to be cancelled when from is cancelled.

Throws:

NullPointerException - thrown if from, to, toRest, or any of the fields of toRest is null.

then

public static <R> CompletableFuture<Void> then(CompletableFuture<R> fut,
                                               Consumer<? super R> handler)

This function is calling CompletableFuture.thenAccept(Consumer) on fut, adapting handler as the parameter.

Type Parameters:

R - generic type of given fut and type that must be accepted by handler for consumption.

Parameters:

fut - the future on which thenAccept will be called. Must not be null.

handler - the function that will be called as the consumer to thenAccept Must not be null.

Returns:

resulting CompletableFuture of thenAccept call

Throws:

NullPointerException - if either fut or handler is null

See Also:

then(CompletableFuture, Function), then(CompletableFuture, Runnable)

then

public static <R,U> CompletableFuture<U> then(CompletableFuture<R> fut,
                                              Function<? super R,? extends U> handler)

This function is calling CompletableFuture.thenApply(Function) on fut, adapting handler as the parameter.

Type Parameters:

R - generic type of given fut and input type for handler.

U - output type of handler and generic type of returned future.

Parameters:

fut - the future on which thenApply will be called Must not be null.

handler - the function that will be called as the consumer to thenApply Must not be null.

Returns:

resulting CompletableFuture of thenApply call

Throws:

NullPointerException - if either fut or handler is null

See Also:

then(CompletableFuture, Runnable), then(CompletableFuture, Consumer)

then

public static CompletableFuture<Void> then(CompletableFuture<?> fut,
                                           Runnable handler)

This function is calling CompletableFuture.thenRun(Runnable) on fut, adapting handler as the parameter.

Parameters:

fut - the future on which thenRun will be called

handler - the function that will be called as the consumer to thenRun

Returns:

resulting CompletableFuture of thenRun call

Throws:

NullPointerException - if either fut or handler is null

See Also:

then(CompletableFuture, Consumer), then(CompletableFuture, Function)

recoverWith

public static <R> CompletableFuture<R> recoverWith(CompletableFuture<R> fut,
                                                   Functions.Function1<? super Throwable,? extends CompletionStage<? extends R>> recovery)

If the given future fut completes successfully, the future returned from this method will be completed with the result value. Otherwise the provider recovery will be called to provide a future and the result of this future will be used to complete the returned future. This also means that if the provided recovery future was completed exceptionally, the failure will be forwarded to the returned future.

Type Parameters:

R - generic type of given fut and type that must be provided by future provided by recovery.

Parameters:

fut - the future that may fail (complete exceptionally). If it completes successfully, the result value will be used to complete the returned future

recovery - provides a CompletionStage in case fut completes exceptionally. In this case the result (either value or exception) will be used to complete the future returned from the function. If this supplier provides a null reference, the returned future will be completed with a NullPointerException. If the supplier throws an exception, the returned future will be completed with this exception.

Returns:

future that will either complete successfully, if fut completes successfully. If fut completes exceptionally, otherwise recovery will be called and the result of the provided CompletionStage will be forwarded to the returned future.

recoverWithAsync

public static <R> CompletableFuture<R> recoverWithAsync(CompletableFuture<R> fut,
                                                        Functions.Function1<? super Throwable,? extends CompletionStage<? extends R>> recovery)

If the given future fut completes successfully, the future returned from this method will be completed with the result value. Otherwise the provider recovery will be called to provide a future and the result of this future will be used to complete the returned future. This also means that if the provided recovery future was completed exceptionally, the failure will be forwarded to the returned future. The recovery function will be executed on the common pool.

Type Parameters:

R - generic type of given fut and type that must be provided by future provided by recovery.

Parameters:

fut - the future that may fail (complete exceptionally). If it completes successfully, the result value will be used to complete the returned future

recovery - provides a CompletionStage in case fut completes exceptionally. In this case the result (either value or exception) will be used to complete the future returned from the function. If this supplier provides a null reference, the returned future will be completed with a NullPointerException. If the supplier throws an exception, the returned future will be completed with this exception. The provider will be executed on the common pool.

Returns:

future that will either complete successfully, if fut completes successfully. If fut completes exceptionally, otherwise recovery will be called and the result of the provided CompletionStage will be forwarded to the returned future.

recoverWithAsync

public static <R> CompletableFuture<R> recoverWithAsync(CompletableFuture<R> fut,
                                                        Executor executor,
                                                        Functions.Function1<? super Throwable,? extends CompletionStage<? extends R>> recovery)

If the given future fut completes successfully, the future returned from this method will be completed with the result value. Otherwise the provider recovery will be called to provide a future and the result of this future will be used to complete the returned future. This also means that if the provided recovery future was completed exceptionally, the failure will be forwarded to the returned future. The recovery function will be executed on executed on Executor e.

Type Parameters:

R - generic type of given fut and type that must be provided by future provided by recovery.

Parameters:

fut - the future that may fail (complete exceptionally). If it completes successfully, the result value will be used to complete the returned future

executor - the executor used to execute the given recovery callback.

recovery - provides a CompletionStage in case fut completes exceptionally. In this case the result (either value or exception) will be used to complete the future returned from the function. If this supplier provides a null reference, the returned future will be completed with a NullPointerException. If the supplier throws an exception, the returned future will be completed with this exception. The provider will be executed on Executor e.

Returns:

future that will either complete successfully, if fut completes successfully. If fut completes exceptionally, otherwise recovery will be called and the result of the provided CompletionStage will be forwarded to the returned future.

orTimeout

public static <R> CompletableFuture<R> orTimeout(CompletableFuture<R> fut,
                                                 Procedures.Procedure1<? super CompletableFutureExtensions.TimeoutConfig> config)

This method will return a future that will be completed exceptionally if the given CompletableFuture fut does not complete in a given timeout interval. The given config lambda defines the details of the timeout cancellation operation. Note that for all fields of TimeoutConfig default values used, so all setters are optional. See the documentation of the setters of the CompletableFutureExtensions.TimeoutConfig to get to know the default values.

Example:

 
 val myFuture = CompletableFuture.supplyAsync [...]
 val cancelScheduler = new ScheduledThreadPoolExecutor(1)
     cancelScheduler.removeOnCancelPolicy = true
 val myTimeoutFuture = myFuture.orTimeout [
 	timeout = (5L -> TimeUnit.SECONDS) // amount of time after which cancellation should be started
 	cancelOriginalOnTimeout = false   // on timeout cancel myFuture and myTimeoutFuture
 	backwardPropagateCancel = true    // on cancel of myTimeoutFuture cancel myFuture as well
 	exceptionProvider = [new IllegalStateException("Timeout")]	// on timeout throw IllegalStateException
 	scheduler = cancelScheduler  // scheduler to schedule timeout cancellation
 	tryShutdownScheduler = true  // close scheduler when myFuture is completed
 ]
 
 

Type Parameters:

R - generic type of given fut and of the returned future

Parameters:

fut - source future for which timeout operation is specified

config - operation for configuration of the timeout operation

Returns:

future that will be cancelled if fut is not completed before the timeout configured by config exceeded.

orTimeout

public static <R> CompletableFuture<R> orTimeout(CompletableFuture<R> fut,
                                                 long timeoutTime,
                                                 TimeUnit unit)

This extension function will create a new CompletableFuture that will either be completed with the result of fut (either successful or ), or if after the timeoutTime in time unit the future fut was not completed, the returned future will be completed exceptionally with a TimeoutException.

Type Parameters:

R - generic type of given fut and of the returned future

Parameters:

fut - the future that's result will be forwarded to the returned future before timeout.

timeoutTime - time (of unit) after which the resulting CompletableFuture will be completed exceptionally with a TimeoutException if it was not completed yet.

unit - the TimeUnit for timeoutTime.

Returns:

CompletableFuture that will either be completed with the result of fut it was completed before the timeout. If the returned future is not completed before the timeout it will be completed with a TimoutException.

copy

public static <R> CompletableFuture<R> copy(CompletableFuture<R> fut)

Returns a CompletableFuture that completes normally if the given CompletableFuture fut completes normally. If fut is completed exceptionally, the returned CompletableFuture will be completed exceptionally with an CompletionException with the original exception set as cause. This is a shortcut for fut.thenApply[it]. This can be handy if a CompletableFuture is needed that should provide a result, but must not be completed by the user.

Type Parameters:

R - generic type of given fut and of the returned copied future

Parameters:

fut - the CompletableFuture to be copied

Returns:

A copy of fut, meaning that the result of fut will be forwarded to the returned CompletableFuture.