Package io.foldright.cffu2

Class CompletableFutureUtils

java.lang.Object

io.foldright.cffu2.CompletableFutureUtils

public final class CompletableFutureUtils
extends Object

Utility class providing enhanced and backport methods for CompletableFuture.

Author:

Jerry Lee (oldratlee at gmail dot com), HuHao (995483610 at qq dot com), Eric Lin (linqinghua4 at gmail dot com)

See Also:

• CompletableFuture
• CfIterableUtils
• CfParallelUtils
• CfTupleUtils

Method Summary

Modifier and Type	Method	Description
static <T> CompletableFuture<Void>	acceptEitherSuccess(CompletableFuture<? extends T> cfThis, CompletionStage<? extends T> other, Consumer<? super T> action)	Returns a new CompletableFuture that, when either of given stages success, is executed with the corresponding result as argument to the supplied action.
static <T> CompletableFuture<Void>	acceptEitherSuccessAsync(CompletableFuture<? extends T> cfThis, CompletionStage<? extends T> other, Consumer<? super T> action)	Returns a new CompletableFuture that, when either of given stages success, is executed using the default executor of parameter cfThis, with the corresponding result as argument to the supplied action.
static <T> CompletableFuture<Void>	acceptEitherSuccessAsync(CompletableFuture<? extends T> cfThis, CompletionStage<? extends T> other, Consumer<? super T> action, Executor executor)	Returns a new CompletableFuture that, when either of given stages success, is executed using the supplied executor, with the corresponding result as argument to the supplied action.
static CompletableFuture<Void>	allFailFastOf(CompletionStage<?>... cfs)	Returns a new CompletableFuture that is completed normally when all the given stages complete normally; If any of the given stages complete exceptionally, then the returned CompletableFuture also does so, WITHOUT waiting other incomplete given stages, with a CompletionException holding this exception as its cause.
static CompletableFuture<Void>	allOf(CompletionStage<?>... cfs)	Returns a new CompletableFuture that is completed when all the given stages complete; If any of the given stages complete exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause.
static <T> CompletableFuture<List<T>>	allResultsFailFastOf(CompletionStage<? extends T>... cfs)	Returns a new CompletableFuture that is completed normally with a list containing the successful results of all given stages when all the given stages complete normally; If any of the given stages complete exceptionally, then the returned CompletableFuture also does so, WITHOUT waiting other incomplete given stages, with a CompletionException holding this exception as its cause.
static <T> CompletableFuture<List<T>>	allResultsOf(CompletionStage<? extends T>... cfs)	Returns a new CompletableFuture that is completed normally with a list containing the successful results of all given stages when all the given stages complete; If any of the given stages complete exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause.
static <T> CompletableFuture<List<T>>	allSuccessResultsOf(T valueIfFailed, CompletionStage<? extends T>... cfs)	Returns a new CompletableFuture that is completed normally with a list containing the successful results of all given stages when all the given stages complete; The list of results is in the same order as the input list, and if any of given stages complete exceptionally, their corresponding position will contain valueIfFailed (which is indistinguishable from the stage having a successful value of valueIfFailed).
static <T> CompletableFuture<T>	anyOf(CompletionStage<? extends T>... cfs)	Returns a new CompletableFuture that is completed when any of the given stages complete, with the same result.
static <T> CompletableFuture<T>	anySuccessOf(CompletionStage<? extends T>... cfs)	Returns a new CompletableFuture that completed normally when any of the given stages complete normally, with the same result; Otherwise, when all the given stages complete exceptionally, the returned CompletableFuture also does so, with a CompletionException holding an exception from any of the given stages as its cause.
static <T, U> CompletableFuture<U>	applyToEitherSuccess(CompletableFuture<? extends T> cfThis, CompletionStage<? extends T> other, Function<? super T,? extends U> fn)	Returns a new CompletableFuture that, when either of given stages success, is executed with the corresponding result as argument to the supplied function.
static <T, U> CompletableFuture<U>	applyToEitherSuccessAsync(CompletableFuture<? extends T> cfThis, CompletionStage<? extends T> other, Function<? super T,? extends U> fn)	Returns a new CompletableFuture that, when either of given stages success, is executed using the default executor of parameter cfThis, with the corresponding result as argument to the supplied function.
static <T, U> CompletableFuture<U>	applyToEitherSuccessAsync(CompletableFuture<? extends T> cfThis, CompletionStage<? extends T> other, Function<? super T,? extends U> fn, Executor executor)	Returns a new CompletableFuture that, when either of given stages success, is executed using the supplied executor, with the corresponding result as argument to the supplied function.
static <T, X extends Throwable, F extends CompletionStage<T>> F	catching(F cfThis, Class<X> exceptionType, Function<? super X,? extends T> fallback)	Returns a new CompletableFuture that, when the given stage completes exceptionally with the given exceptionType, is executed with the exception from the given stage(argument cfThis) as the argument to the supplied function.
static <T, X extends Throwable, F extends CompletionStage<T>> F	catchingAsync(F cfThis, Class<X> exceptionType, Function<? super X,? extends T> fallback)	Returns a new CompletableFuture that, when the given stage completes exceptionally with the given exceptionType, is executed with the exception from the given stage(argument cfThis) as the argument to the supplied function, using the default executor of parameter the given stage.
static <T, X extends Throwable, F extends CompletionStage<T>> F	catchingAsync(F cfThis, Class<X> exceptionType, Function<? super X,? extends T> fallback, Executor executor)	Returns a new CompletableFuture that, when the given stage completes exceptionally with the given exceptionType, is executed with the exception from the given stage(argument cfThis) as the argument to the supplied function, using the supplied Executor.
static <T, X extends Throwable, F extends CompletionStage<T>> F	catchingCompose(F cfThis, Class<X> exceptionType, Function<? super X,? extends CompletionStage<T>> fallback)	Returns a new CompletionStage that, when the given stage completes exceptionally with the given exceptionType, is composed using the results of the supplied function applied to the exception from the given stage(argument cfThis).
static <T, X extends Throwable, F extends CompletionStage<T>> F	catchingComposeAsync(F cfThis, Class<X> exceptionType, Function<? super X,? extends CompletionStage<T>> fallback)	Returns a new CompletionStage that, when the given stage completes exceptionally with the given exceptionType, is composed using the results of the supplied function applied to the exception from the given stage(argument cfThis), using the default executor of parameter the given stage.
static <T, X extends Throwable, F extends CompletionStage<T>> F	catchingComposeAsync(F cfThis, Class<X> exceptionType, Function<? super X,? extends CompletionStage<T>> fallback, Executor executor)	Returns a new CompletionStage that, when the given stage completes exceptionally with the given exceptionType, is composed using the results of the supplied function applied to the exception from the given stage(argument cfThis), using the supplied Executor.
static <T, F extends CompletableFuture<? super T>> F	cffuCompleteOnTimeout(F cfThis, T value, long timeout, TimeUnit unit)	Returns a new CompletableFuture that is completed normally with the given value when the given CompletableFuture is not completed before the given timeout; otherwise the returned CompletableFuture completed with the same successful result or exception of the given CompletableFuture.
static <T, F extends CompletableFuture<? super T>> F	cffuCompleteOnTimeout(F cfThis, T value, long timeout, TimeUnit unit, Executor executorWhenTimeout)	Returns a new CompletableFuture that is completed normally with the given value when the given CompletableFuture is not completed before the given timeout; otherwise the returned CompletableFuture completed with the same successful result or exception of the given CompletableFuture.
static <F extends CompletableFuture<?>> F	cffuOrTimeout(F cfThis, long timeout, TimeUnit unit)	Returns a new CompletableFuture that is completed exceptionally with a TimeoutException when the given CompletableFuture is not completed before the given timeout; otherwise the returned CompletableFuture completed with the same successful result or exception of the given CompletableFuture.
static <F extends CompletableFuture<?>> F	cffuOrTimeout(F cfThis, long timeout, TimeUnit unit, Executor executorWhenTimeout)	Returns a new CompletableFuture that is completed exceptionally with a TimeoutException when the given CompletableFuture is not completed before the given timeout; otherwise the returned CompletableFuture completed with the same successful result or exception of the given CompletableFuture.
static <T, F extends CompletableFuture<? super T>> F	completeAsync(F cfThis, Supplier<? extends T> supplier)	Completes given CompletableFuture with the result of the given Supplier function invoked from an asynchronous task using the default executor of parameter cfThis.
static <T, F extends CompletableFuture<? super T>> F	completeAsync(F cfThis, Supplier<? extends T> supplier, Executor executor)	Completes given CompletableFuture with the result of the given Supplier function invoked from an asynchronous task using the given executor.
static <T> CompletionStage<T>	completedStage(T value)	Returns a new CompletionStage that is already completed with the given value and supports only those methods in interface CompletionStage.
static <F extends CompletableFuture<?>> F	completeExceptionallyAsync(F cfThis, Supplier<? extends Throwable> supplier)	If not already completed, completes given CompletableFuture with the exception result of the given Supplier function invoked from an asynchronous task using the default executor of parameter cfThis.
static <F extends CompletableFuture<?>> F	completeExceptionallyAsync(F cfThis, Supplier<? extends Throwable> supplier, Executor executor)	If not already completed, completes given CompletableFuture with the exception result of the given Supplier function invoked from an asynchronous task using the given executor.
static <T, F extends CompletableFuture<? super T>> F	completeOnTimeout(F cfThis, T value, long timeout, TimeUnit unit)	Completes given CompletableFuture with the given value if not otherwise completed before the given timeout.
static <T> CompletableFuture<T>	copy(CompletableFuture<T> cfThis)	Returns a new CompletableFuture that is completed normally with the same value as this CompletableFuture when it completes normally.
static Executor	defaultExecutor(CompletionStage<?> cfThis)	Returns the default Executor of parameter cfThis used for async methods that do not specify an Executor.
static Executor	delayedExecutor(long delay, TimeUnit unit)	Returns a new Executor that submits a task to the default executor after the given delay (or no delay if non-positive).
static Executor	delayedExecutor(long delay, TimeUnit unit, Executor executor)	Returns a new Executor that submits a task to the given base executor after the given delay (or no delay if non-positive).
static <T, F extends CompletionStage<T>> F	exceptionallyAsync(F cfThis, Function<Throwable,? extends T> fn)	Returns a new CompletableFuture that, when the given stage completes exceptionally, is executed with the given stage's exception as the argument to the supplied function, using the default executor of parameter cfThis.
static <T, F extends CompletionStage<T>> F	exceptionallyAsync(F cfThis, Function<Throwable,? extends T> fn, Executor executor)	Returns a new CompletableFuture that, when the given stage completes exceptionally, is executed with the given stage's exception as the argument to the supplied function, using the supplied Executor.
static <T, F extends CompletionStage<T>> F	exceptionallyCompose(F cfThis, Function<Throwable,? extends CompletionStage<T>> fn)	Returns a new CompletableFuture that, when given CompletableFuture completes exceptionally, is composed using the results of the supplied function applied to the given stage's exception.
static <T, F extends CompletionStage<T>> F	exceptionallyComposeAsync(F cfThis, Function<Throwable,? extends CompletionStage<T>> fn)	Returns a new CompletableFuture that, when given CompletableFuture completes exceptionally, is composed using the results of the supplied function applied to the given stage's exception, using the default executor of parameter cfThis.
static <T, F extends CompletionStage<T>> F	exceptionallyComposeAsync(F cfThis, Function<Throwable,? extends CompletionStage<T>> fn, Executor executor)	Returns a new CompletableFuture that, when given CompletableFuture completes exceptionally, is composed using the results of the supplied function applied to the given stage's exception, using the supplied Executor.
static Throwable	exceptionNow(Future<?> cfThis)	Returns the exception thrown by the task without waiting.
static <T> CompletableFuture<T>	failedFuture(Throwable ex)	Returns a new CompletableFuture that is already completed exceptionally with the given exception.
static <T> CompletionStage<T>	failedStage(Throwable ex)	Returns a new CompletionStage that is already completed exceptionally with the given exception and supports only those methods in interface CompletionStage.
static <T> CompletableFuture<T>	fromSyncCall(Callable<? extends T> callable)	Returns a new CompletableFuture that encapsulates the execution of synchronous logic.
static <T> T	getSuccessNow(CompletableFuture<? extends T> cfThis, T valueIfNotSuccess)	Returns the result value if the given stage is completed normally, else returns the given valueIfNotSuccess.
static <T> T	join(CompletableFuture<? extends T> cfThis, long timeout, TimeUnit unit)	Waits if necessary for at most the given time for the computation to complete and then retrieves its result value when complete, or throws an (unchecked) exception if completed exceptionally.
static <T> CompletionStage<T>	minimalCompletionStage(CompletableFuture<T> cfThis)	Returns a new CompletionStage that is completed normally with the same value as given CompletableFuture when it completes normally, and cannot be independently completed or otherwise used in ways not defined by the methods of interface CompletionStage.
static <T> CompletableFuture<List<T>>	mostSuccessResultsOf(Executor executorWhenTimeout, T valueIfNotSuccess, long timeout, TimeUnit unit, CompletionStage<? extends T>... cfs)	Returns a new CompletableFuture that is completed normally with a list containing the successful results of the given stages before the given timeout (aka as many results as possible in the given time); The list of results is in the same order as the input list, and if any of given stages complete exceptionally or are incomplete, their corresponding positions will contain valueIfNotSuccess (which is indistinguishable from the stage having a successful value of valueIfNotSuccess).
static <T> CompletableFuture<List<T>>	mostSuccessResultsOf(T valueIfNotSuccess, long timeout, TimeUnit unit, CompletionStage<? extends T>... cfs)	Returns a new CompletableFuture that is completed normally with a list containing the successful results of the given stages before the given timeout (aka as many results as possible in the given time); The list of results is in the same order as the input list, and if any of given stages complete exceptionally or are incomplete, their corresponding positions will contain valueIfNotSuccess (which is indistinguishable from the stage having a successful value of valueIfNotSuccess).
static CompletableFuture<Void>	mRunAnyAsync(Runnable... actions)	Shortcut to method anyOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable).
static CompletableFuture<Void>	mRunAnyAsync(Executor executor, Runnable... actions)	Shortcut to method anyOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor).
static CompletableFuture<Void>	mRunAnySuccessAsync(Runnable... actions)	Shortcut to method anySuccessOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable).
static CompletableFuture<Void>	mRunAnySuccessAsync(Executor executor, Runnable... actions)	Shortcut to method anySuccessOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor).
static CompletableFuture<Void>	mRunAsync(Runnable... actions)	Shortcut to method allOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable).
static CompletableFuture<Void>	mRunAsync(Executor executor, Runnable... actions)	Shortcut to method allOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor).
static CompletableFuture<Void>	mRunFailFastAsync(Runnable... actions)	Shortcut to method allFailFastOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable).
static CompletableFuture<Void>	mRunFailFastAsync(Executor executor, Runnable... actions)	Shortcut to method allFailFastOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor).
static <T> CompletableFuture<List<T>>	mSupplyAllSuccessAsync(Executor executor, T valueIfFailed, Supplier<? extends T>... suppliers)	Shortcut to method allSuccessResultsOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor).
static <T> CompletableFuture<List<T>>	mSupplyAllSuccessAsync(T valueIfFailed, Supplier<? extends T>... suppliers)	Shortcut to method allSuccessResultsOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier).
static <T> CompletableFuture<T>	mSupplyAnyAsync(Executor executor, Supplier<? extends T>... suppliers)	Shortcut to method anyOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor).
static <T> CompletableFuture<T>	mSupplyAnyAsync(Supplier<? extends T>... suppliers)	Shortcut to method anyOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier).
static <T> CompletableFuture<T>	mSupplyAnySuccessAsync(Executor executor, Supplier<? extends T>... suppliers)	Shortcut to method anySuccessOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor).
static <T> CompletableFuture<T>	mSupplyAnySuccessAsync(Supplier<? extends T>... suppliers)	Shortcut to method anySuccessOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier).
static <T> CompletableFuture<List<T>>	mSupplyAsync(Executor executor, Supplier<? extends T>... suppliers)	Shortcut to method allResultsOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor).
static <T> CompletableFuture<List<T>>	mSupplyAsync(Supplier<? extends T>... suppliers)	Shortcut to method allResultsOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier).
static <T> CompletableFuture<List<T>>	mSupplyFailFastAsync(Executor executor, Supplier<? extends T>... suppliers)	Shortcut to method allResultsFailFastOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor).
static <T> CompletableFuture<List<T>>	mSupplyFailFastAsync(Supplier<? extends T>... suppliers)	Shortcut to method allResultsFailFastOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier).
static <T> CompletableFuture<List<T>>	mSupplyMostSuccessAsync(Executor executor, T valueIfNotSuccess, long timeout, TimeUnit unit, Supplier<? extends T>... suppliers)	Shortcut to method mostSuccessResultsOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor).
static <T> CompletableFuture<List<T>>	mSupplyMostSuccessAsync(T valueIfNotSuccess, long timeout, TimeUnit unit, Supplier<? extends T>... suppliers)	Shortcut to method mostSuccessResultsOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier).
static <U> CompletableFuture<U>	newIncompleteFuture(CompletableFuture<?> cfThis)	Returns a new incomplete CompletableFuture of the type to be returned by a CompletionStage method.
static <T, X extends Throwable> BiConsumer<T,X>	nonExSwallowedBiConsumer(BiConsumer<? super T,? super X> action, boolean addSuppressedToOriginalEx)	Wraps an exception-handling BiConsumer to ensure that if the handling throws a new exception, the error context is preserved by calling Throwable.addSuppressed(java.lang.Throwable).
static <T, X extends Throwable, U> BiFunction<T,X,U>	nonExSwallowedBiFunction(BiFunction<? super T,? super X,? extends U> fn, boolean addSuppressedToOriginalEx)	Wraps an exception-handling BiFunction to ensure that if the handling throws a new exception, the error context is preserved by calling Throwable.addSuppressed(java.lang.Throwable).
static <X extends Throwable, T> Function<X,T>	nonExSwallowedFunction(Function<? super X,? extends T> fn, boolean addSuppressedToOriginalEx)	Wraps an exception-handling Function to ensure that if the handling throws a new exception, the error context is preserved by calling Throwable.addSuppressed(java.lang.Throwable).
static <F extends CompletableFuture<?>> F	orTimeout(F cfThis, long timeout, TimeUnit unit)	Exceptionally completes given CompletableFuture with a TimeoutException if not otherwise completed before the given timeout.
static <T, F extends CompletionStage<? extends T>> F	peek(F cfThis, BiConsumer<? super T,? super Throwable> action)	Peeks the result by executing the given action when the given stage completes, returns the given stage.
static <T, F extends CompletionStage<? extends T>> F	peekAsync(F cfThis, BiConsumer<? super T,? super Throwable> action)	Peeks the result by executing the given action using the default executor of parameter cfThis when the given stage completes, returns the given stage.
static <T, F extends CompletionStage<? extends T>> F	peekAsync(F cfThis, BiConsumer<? super T,? super Throwable> action, Executor executor)	Peeks the result by executing the given action using the supplied executor when the given stage completes, returns the given stage.
static <T> T	resultNow(Future<? extends T> cfThis)	Returns the computed result without waiting.
static CompletableFuture<Void>	runAfterBothFailFast(CompletableFuture<?> cfThis, CompletionStage<?> other, Runnable action)	Returns a new CompletableFuture that, when two given stages both complete normally, executes the given action.
static CompletableFuture<Void>	runAfterBothFailFastAsync(CompletableFuture<?> cfThis, CompletionStage<?> other, Runnable action)	Returns a new CompletableFuture that, when two given stages both complete normally, executes the given action using the default executor of parameter cfThis.
static CompletableFuture<Void>	runAfterBothFailFastAsync(CompletableFuture<?> cfThis, CompletionStage<?> other, Runnable action, Executor executor)	Returns a new CompletableFuture that, when two given stages both complete normally, executes the given action using the supplied executor.
static CompletableFuture<Void>	runAfterEitherSuccess(CompletableFuture<?> cfThis, CompletionStage<?> other, Runnable action)	Returns a new CompletableFuture that, when either of given stages success, executes the given action.
static CompletableFuture<Void>	runAfterEitherSuccessAsync(CompletableFuture<?> cfThis, CompletionStage<?> other, Runnable action)	Returns a new CompletableFuture that, when either of given stages success, executes the given action using the default executor of parameter cfThis.
static CompletableFuture<Void>	runAfterEitherSuccessAsync(CompletableFuture<?> cfThis, CompletionStage<?> other, Runnable action, Executor executor)	Returns a new CompletableFuture that, when either of given stages success, executes the given action using the supplied executor.
static CffuState	state(Future<?> cfThis)	Returns the computation state (CffuState).
static <T, U> CompletableFuture<Void>	thenAcceptBothFailFast(CompletableFuture<? extends T> cfThis, CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action)	Returns a new CompletableFuture that, when both of given stages complete normally, is executed with the two results as arguments to the supplied action.
static <T, U> CompletableFuture<Void>	thenAcceptBothFailFastAsync(CompletableFuture<? extends T> cfThis, CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action)	Returns a new CompletableFuture that, when both of given stages complete normally, is executed using the default executor of parameter cfThis, with the two results as arguments to the supplied action.
static <T, U> CompletableFuture<Void>	thenAcceptBothFailFastAsync(CompletableFuture<? extends T> cfThis, CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action, Executor executor)	Returns a new CompletableFuture that, when both of given stages complete normally, is executed using the supplied executor, with the two results as arguments to the supplied action.
static <T, U, V> CompletableFuture<V>	thenCombineFailFast(CompletableFuture<? extends T> cfThis, CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn)	Returns a new CompletableFuture that, when both of given stages complete normally, is executed with the two results as arguments to the supplied function.
static <T, U, V> CompletableFuture<V>	thenCombineFailFastAsync(CompletableFuture<? extends T> cfThis, CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn)	Returns a new CompletableFuture that, when both of given stages complete normally, is executed using the default executor of parameter cfThis, with the two results as arguments to the supplied function.
static <T, U, V> CompletableFuture<V>	thenCombineFailFastAsync(CompletableFuture<? extends T> cfThis, CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn, Executor executor)	Returns a new CompletableFuture that, when both of given stages complete normally, is executed using the supplied executor, with the two results as arguments to the supplied function.
static <T> CompletableFuture<Void>	thenMAcceptAnyAsync(CompletableFuture<? extends T> cfThis, Executor executor, Consumer<? super T>... actions)	Shortcut to method anyOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor); The given CompletableFuture's result is used as the argument of actions.
static <T> CompletableFuture<Void>	thenMAcceptAnyAsync(CompletableFuture<? extends T> cfThis, Consumer<? super T>... actions)	Shortcut to method anyOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of actions.
static <T> CompletableFuture<Void>	thenMAcceptAnySuccessAsync(CompletableFuture<? extends T> cfThis, Executor executor, Consumer<? super T>... actions)	Shortcut to method anySuccessOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor); The given CompletableFuture's result is used as the argument of actions.
static <T> CompletableFuture<Void>	thenMAcceptAnySuccessAsync(CompletableFuture<? extends T> cfThis, Consumer<? super T>... actions)	Shortcut to method anySuccessOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of actions.
static <T> CompletableFuture<Void>	thenMAcceptAsync(CompletableFuture<? extends T> cfThis, Executor executor, Consumer<? super T>... actions)	Shortcut to method allOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor); The given CompletableFuture's result is used as the argument of actions.
static <T> CompletableFuture<Void>	thenMAcceptAsync(CompletableFuture<? extends T> cfThis, Consumer<? super T>... actions)	Shortcut to method allOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of actions.
static <T> CompletableFuture<Void>	thenMAcceptFailFastAsync(CompletableFuture<? extends T> cfThis, Executor executor, Consumer<? super T>... actions)	Shortcut to method allFailFastOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of actions.
static <T> CompletableFuture<Void>	thenMAcceptFailFastAsync(CompletableFuture<? extends T> cfThis, Consumer<? super T>... actions)	Shortcut to method allFailFastOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of actions.
static <T, U> CompletableFuture<List<U>>	thenMApplyAllSuccessAsync(CompletableFuture<? extends T> cfThis, Executor executor, U valueIfFailed, Function<? super T,? extends U>... fns)	Shortcut to method allSuccessResultsOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor); The given CompletableFuture's result is used as the argument of functions.
static <T, U> CompletableFuture<List<U>>	thenMApplyAllSuccessAsync(CompletableFuture<? extends T> cfThis, U valueIfFailed, Function<? super T,? extends U>... fns)	Shortcut to method allSuccessResultsOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of functions.
static <T, U> CompletableFuture<U>	thenMApplyAnyAsync(CompletableFuture<? extends T> cfThis, Executor executor, Function<? super T,? extends U>... fns)	Shortcut to method anyOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor); The given CompletableFuture's result is used as the argument of functions.
static <T, U> CompletableFuture<U>	thenMApplyAnyAsync(CompletableFuture<? extends T> cfThis, Function<? super T,? extends U>... fns)	Shortcut to method anyOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of functions.
static <T, U> CompletableFuture<U>	thenMApplyAnySuccessAsync(CompletableFuture<? extends T> cfThis, Executor executor, Function<? super T,? extends U>... fns)	Shortcut to method anySuccessOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor); The given CompletableFuture's result is used as the argument of functions.
static <T, U> CompletableFuture<U>	thenMApplyAnySuccessAsync(CompletableFuture<? extends T> cfThis, Function<? super T,? extends U>... fns)	Shortcut to method anySuccessOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of functions.
static <T, U> CompletableFuture<List<U>>	thenMApplyAsync(CompletableFuture<? extends T> cfThis, Executor executor, Function<? super T,? extends U>... fns)	Shortcut to method allResultsOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor); The given CompletableFuture's result is used as the argument of functions.
static <T, U> CompletableFuture<List<U>>	thenMApplyAsync(CompletableFuture<? extends T> cfThis, Function<? super T,? extends U>... fns)	Shortcut to method allResultsOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of functions.
static <T, U> CompletableFuture<List<U>>	thenMApplyFailFastAsync(CompletableFuture<? extends T> cfThis, Executor executor, Function<? super T,? extends U>... fns)	Shortcut to method allResultsFailFastOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor); The given CompletableFuture's result is used as the argument of functions.
static <T, U> CompletableFuture<List<U>>	thenMApplyFailFastAsync(CompletableFuture<? extends T> cfThis, Function<? super T,? extends U>... fns)	Shortcut to method allResultsFailFastOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of functions.
static <T, U> CompletableFuture<List<U>>	thenMApplyMostSuccessAsync(CompletableFuture<? extends T> cfThis, Executor executor, U valueIfNotSuccess, long timeout, TimeUnit unit, Function<? super T,? extends U>... fns)	Shortcut to method mostSuccessResultsOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor); The given CompletableFuture's result is used as the argument of functions.
static <T, U> CompletableFuture<List<U>>	thenMApplyMostSuccessAsync(CompletableFuture<? extends T> cfThis, U valueIfNotSuccess, long timeout, TimeUnit unit, Function<? super T,? extends U>... fns)	Shortcut to method mostSuccessResultsOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of functions.
static CompletableFuture<Void>	thenMRunAnyAsync(CompletableFuture<?> cfThis, Runnable... actions)	Shortcut to method anyOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis.
static CompletableFuture<Void>	thenMRunAnyAsync(CompletableFuture<?> cfThis, Executor executor, Runnable... actions)	Shortcut to method anyOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor).
static CompletableFuture<Void>	thenMRunAnySuccessAsync(CompletableFuture<?> cfThis, Runnable... actions)	Shortcut to method anySuccessOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis.
static CompletableFuture<Void>	thenMRunAnySuccessAsync(CompletableFuture<?> cfThis, Executor executor, Runnable... actions)	Shortcut to method anySuccessOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor).
static CompletableFuture<Void>	thenMRunAsync(CompletableFuture<?> cfThis, Runnable... actions)	Shortcut to method allOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis.
static CompletableFuture<Void>	thenMRunAsync(CompletableFuture<?> cfThis, Executor executor, Runnable... actions)	Shortcut to method allOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor).
static CompletableFuture<Void>	thenMRunFailFastAsync(CompletableFuture<?> cfThis, Runnable... actions)	Shortcut to method allFailFastOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis.
static CompletableFuture<Void>	thenMRunFailFastAsync(CompletableFuture<?> cfThis, Executor executor, Runnable... actions)	Shortcut to method allFailFastOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor).
static Throwable	unwrapCfException(Throwable ex)	Unwraps CompletableFuture exception (CompletionException or ExecutionException) to its cause exception.

Methods inherited from class java.lang.Object

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

Method Details

mSupplyFailFastAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
@SafeVarargs
public static <T> CompletableFuture<List<T>> mSupplyFailFastAsync(Supplier<? extends T>... suppliers)

Shortcut to method allResultsFailFastOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier).

See the allResultsFailFastOf documentation for the rules of result computation.

mSupplyFailFastAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
@SafeVarargs
public static <T> CompletableFuture<List<T>> mSupplyFailFastAsync(Executor executor,
 Supplier<? extends T>... suppliers)

Shortcut to method allResultsFailFastOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor).

See the allResultsFailFastOf documentation for the rules of result computation.

mSupplyAllSuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
@SafeVarargs
public static <T> CompletableFuture<List<T>> mSupplyAllSuccessAsync(@Nullable
 T valueIfFailed,
 Supplier<? extends T>... suppliers)

Shortcut to method allSuccessResultsOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier).

See the allSuccessResultsOf documentation for the rules of result computation.

mSupplyAllSuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
@SafeVarargs
public static <T> CompletableFuture<List<T>> mSupplyAllSuccessAsync(Executor executor,
 @Nullable
 T valueIfFailed,
 Supplier<? extends T>... suppliers)

Shortcut to method allSuccessResultsOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor).

See the allSuccessResultsOf documentation for the rules of result computation.

mSupplyMostSuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
@SafeVarargs
public static <T> CompletableFuture<List<T>> mSupplyMostSuccessAsync(@Nullable
 T valueIfNotSuccess,
 long timeout,
 TimeUnit unit,
 Supplier<? extends T>... suppliers)

Shortcut to method mostSuccessResultsOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier).

See the mostSuccessResultsOf documentation for the rules of result computation.

mSupplyMostSuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
@SafeVarargs
public static <T> CompletableFuture<List<T>> mSupplyMostSuccessAsync(Executor executor,
 @Nullable
 T valueIfNotSuccess,
 long timeout,
 TimeUnit unit,
 Supplier<? extends T>... suppliers)

Shortcut to method mostSuccessResultsOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor).

See the mostSuccessResultsOf documentation for the rules of result computation.

mSupplyAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
@SafeVarargs
public static <T> CompletableFuture<List<T>> mSupplyAsync(Supplier<? extends T>... suppliers)

Shortcut to method allResultsOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier).

See the allResultsOf documentation for the rules of result computation.

mSupplyAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
@SafeVarargs
public static <T> CompletableFuture<List<T>> mSupplyAsync(Executor executor,
 Supplier<? extends T>... suppliers)

Shortcut to method allResultsOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor).

See the allResultsOf documentation for the rules of result computation.

mSupplyAnySuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
@SafeVarargs
public static <T> CompletableFuture<T> mSupplyAnySuccessAsync(Supplier<? extends T>... suppliers)

Shortcut to method anySuccessOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier).

See the anySuccessOf documentation for the rules of result computation.

mSupplyAnySuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
@SafeVarargs
public static <T> CompletableFuture<T> mSupplyAnySuccessAsync(Executor executor,
 Supplier<? extends T>... suppliers)

Shortcut to method anySuccessOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor).

See the anySuccessOf documentation for the rules of result computation.

mSupplyAnyAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
@SafeVarargs
public static <T> CompletableFuture<T> mSupplyAnyAsync(Supplier<? extends T>... suppliers)

Shortcut to method anyOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier).

See the anyOf documentation for the rules of result computation.

mSupplyAnyAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
@SafeVarargs
public static <T> CompletableFuture<T> mSupplyAnyAsync(Executor executor,
 Supplier<? extends T>... suppliers)

Shortcut to method anyOf, wraps input suppliers to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor).

See the anyOf documentation for the rules of result computation.

mRunFailFastAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
public static CompletableFuture<Void> mRunFailFastAsync(Runnable... actions)

Shortcut to method allFailFastOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable).

See the allFailFastOf documentation for the rules of result computation.

mRunFailFastAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
public static CompletableFuture<Void> mRunFailFastAsync(Executor executor,
 Runnable... actions)

Shortcut to method allFailFastOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor).

See the allFailFastOf documentation for the rules of result computation.

mRunAsync

public static CompletableFuture<Void> mRunAsync(Runnable... actions)

Shortcut to method allOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable).

See the allOf documentation for the rules of result computation.

mRunAsync

public static CompletableFuture<Void> mRunAsync(Executor executor,
 Runnable... actions)

Shortcut to method allOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor).

See the allOf documentation for the rules of result computation.

mRunAnySuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
public static CompletableFuture<Void> mRunAnySuccessAsync(Runnable... actions)

Shortcut to method anySuccessOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable).

See the anySuccessOf documentation for the rules of result computation.

mRunAnySuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
public static CompletableFuture<Void> mRunAnySuccessAsync(Executor executor,
 Runnable... actions)

Shortcut to method anySuccessOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor).

See the anySuccessOf documentation for the rules of result computation.

mRunAnyAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
public static CompletableFuture<Void> mRunAnyAsync(Runnable... actions)

Shortcut to method anyOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable).

See the anyOf documentation for the rules of result computation.

mRunAnyAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `mRunAsync`")
public static CompletableFuture<Void> mRunAnyAsync(Executor executor,
 Runnable... actions)

Shortcut to method anyOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor).

See the anyOf documentation for the rules of result computation.

allResultsFailFastOf

@Contract(pure=true)
@SafeVarargs
public static <T> CompletableFuture<List<T>> allResultsFailFastOf(CompletionStage<? extends T>... cfs)

Returns a new CompletableFuture that is completed normally with a list containing the successful results of all given stages when all the given stages complete normally; If any of the given stages complete exceptionally, then the returned CompletableFuture also does so, WITHOUT waiting other incomplete given stages, with a CompletionException holding this exception as its cause. If no stages are provided, returns a CompletableFuture completed with the value empty list.

The list of results is in the same order as the input list.

This method is the same as allResultsOf method except for the fail-fast behavior.

Throws:

NullPointerException - if the cfs param or any of its elements are null

See Also:

• the equivalent Guava method allAsList()

allSuccessResultsOf

@Contract(pure=true)
@SafeVarargs
public static <T> CompletableFuture<List<T>> allSuccessResultsOf(@Nullable
 T valueIfFailed,
 CompletionStage<? extends T>... cfs)

Returns a new CompletableFuture that is completed normally with a list containing the successful results of all given stages when all the given stages complete; The list of results is in the same order as the input list, and if any of given stages complete exceptionally, their corresponding position will contain valueIfFailed (which is indistinguishable from the stage having a successful value of valueIfFailed). If no stages are provided, returns a CompletableFuture completed with the value empty list.

The list of results is in the same order as the input list.

This method differs from allResultsFailFastOf method in that it's tolerant of failed stages for any of the items, representing them as valueIfFailed in the result list.

Parameters:

valueIfFailed - the value used as the result if the input stage completed exceptionally

Throws:

NullPointerException - if the cfs param or any of its elements is null

See Also:

• getSuccessNow(CompletableFuture, Object)
• the equivalent Guava method successfulAsList()

mostSuccessResultsOf

@Contract(pure=true)
@SafeVarargs
public static <T> CompletableFuture<List<T>> mostSuccessResultsOf(@Nullable
 T valueIfNotSuccess,
 long timeout,
 TimeUnit unit,
 CompletionStage<? extends T>... cfs)

Returns a new CompletableFuture that is completed normally with a list containing the successful results of the given stages before the given timeout (aka as many results as possible in the given time); The list of results is in the same order as the input list, and if any of given stages complete exceptionally or are incomplete, their corresponding positions will contain valueIfNotSuccess (which is indistinguishable from the stage having a successful value of valueIfNotSuccess). If no stages are provided, returns a CompletableFuture completed with the value empty list.

The list of results is in the same order as the input list.

This method differs from allResultsFailFastOf method in that it's tolerant of failed or incomplete stages for any of the items, representing them as valueIfNotSuccess in the result list.

Parameters:

valueIfNotSuccess - the value used as the result if the input stage not completed normally

timeout - how long to wait in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

Throws:

NullPointerException - if the cfs param or any of its elements are null

See Also:

• getSuccessNow(CompletableFuture, Object)

mostSuccessResultsOf

@Contract(pure=true)
@SafeVarargs
public static <T> CompletableFuture<List<T>> mostSuccessResultsOf(Executor executorWhenTimeout,
 @Nullable
 T valueIfNotSuccess,
 long timeout,
 TimeUnit unit,
 CompletionStage<? extends T>... cfs)

Returns a new CompletableFuture that is completed normally with a list containing the successful results of the given stages before the given timeout (aka as many results as possible in the given time); The list of results is in the same order as the input list, and if any of given stages complete exceptionally or are incomplete, their corresponding positions will contain valueIfNotSuccess (which is indistinguishable from the stage having a successful value of valueIfNotSuccess). If no stages are provided, returns a CompletableFuture completed with the value empty list.

The list of results is in the same order as the input list.

This method differs from allResultsFailFastOf method in that it's tolerant of failed or incomplete stages for any of the items, representing them as valueIfNotSuccess in the result list.

Parameters:

executorWhenTimeout - the executor to use for asynchronous execution when timeout

valueIfNotSuccess - the value used as the result if the input stage not completed normally

timeout - how long to wait in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

Throws:

NullPointerException - if the cfs param or any of its elements are null

See Also:

• getSuccessNow(CompletableFuture, Object)

allResultsOf

@Contract(pure=true)
@SafeVarargs
public static <T> CompletableFuture<List<T>> allResultsOf(CompletionStage<? extends T>... cfs)

Returns a new CompletableFuture that is completed normally with a list containing the successful results of all given stages when all the given stages complete; If any of the given stages complete exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause. If no stages are provided, returns a CompletableFuture completed with the value empty list.

The list of results is in the same order as the input list.

Comparing the waiting-all-complete behavior of this method, the fail-fast behavior of allResultsFailFastOf method is more responsive to user and generally more desired in the application.

This method is the same as allOf method, except that the returned CompletableFuture contains the results of the given stages.

Throws:

NullPointerException - if the cfs param or any of its elements are null

allFailFastOf

@Contract(pure=true)
public static CompletableFuture<Void> allFailFastOf(CompletionStage<?>... cfs)

Returns a new CompletableFuture that is completed normally when all the given stages complete normally; If any of the given stages complete exceptionally, then the returned CompletableFuture also does so, WITHOUT waiting other incomplete given stages, with a CompletionException holding this exception as its cause. If no stages are provided, returns a CompletableFuture completed with the value null.

The successful results, if any, of the given stages are not reflected in the returned CompletableFuture (CompletableFuture<Void>), but may be obtained by inspecting them individually; Or using the below methods reflected results in the returned CompletableFuture which are more convenient, safer and best-practice of concurrency:

• allResultsFailFastOf, allFailFastOf, parApplyFailFastAsync
• allSuccessResultsOf, allSuccessResultsOf, parApplyAllSuccessAsync
• mostSuccessResultsOf, mostSuccessResultsOf parApplyMostSuccessAsync
• allResultsOf, allResultsOf parApplyAsync

This method is the same as allOf method except for the fail-fast behavior.

Throws:

NullPointerException - if the cfs param or any of its elements are null

See Also:

• the equivalent Guava method whenAllSucceed()

allOf

@CheckReturnValue(explanation="should use the returned CompletableFuture; forget to call its `join()` method?")
@Contract(pure=true)
public static CompletableFuture<Void> allOf(CompletionStage<?>... cfs)

Returns a new CompletableFuture that is completed when all the given stages complete; If any of the given stages complete exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause. If no stages are provided, returns a CompletableFuture completed with the value null.

The successful results, if any, of the given stages are not reflected in the returned CompletableFuture (CompletableFuture<Void>), but may be obtained by inspecting them individually; Or using the below methods reflected results in the returned CompletableFuture which are more convenient, safer and best-practice of concurrency:

• allResultsOf, allResultsOf parApplyAsync
• allResultsFailFastOf, allFailFastOf, parApplyFailFastAsync
• allSuccessResultsOf, allSuccessResultsOf, parApplyAllSuccessAsync
• mostSuccessResultsOf, mostSuccessResultsOf parApplyMostSuccessAsync

Among the applications of this method is to await completion of a set of independent stages before continuing a program, as in: CompletableFuture.allOf(c1, c2, c3).join();.

This method is the same as CompletableFuture#allOf method, except that the parameter type is more generic CompletionStage instead of CompletableFuture.

Throws:

NullPointerException - if the cfs param or any of its elements are null

See Also:

• the equivalent Guava method whenAllComplete()

anySuccessOf

@Contract(pure=true)
@SafeVarargs
public static <T> CompletableFuture<T> anySuccessOf(CompletionStage<? extends T>... cfs)

Returns a new CompletableFuture that completed normally when any of the given stages complete normally, with the same result; Otherwise, when all the given stages complete exceptionally, the returned CompletableFuture also does so, with a CompletionException holding an exception from any of the given stages as its cause. If no stages are provided, returns a new CompletableFuture that is already completed exceptionally with a NoCfsProvidedException.

This method differs from anyOf method in that this method is any-success instead of the any-complete behavior of method anyOf.

Throws:

NullPointerException - if the cfs param or any of its elements are null

anyOf

@Contract(pure=true)
@SafeVarargs
public static <T> CompletableFuture<T> anyOf(CompletionStage<? extends T>... cfs)

Returns a new CompletableFuture that is completed when any of the given stages complete, with the same result. Otherwise, if it completed exceptionally, the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause. If no stages are provided, returns an incomplete CompletableFuture.

Comparing the any-complete behavior(the complete one may be failed) of this method, the any-success behavior of method anySuccessOf is generally more desired in the application.

This method is the same as CompletableFuture#anyOf method, except that the parameter type is more generic CompletionStage instead of CompletableFuture and the return type is more specific T instead of Object.

Throws:

NullPointerException - if the cfs param or any of its elements are null

failedFuture

@Contract(pure=true)
public static <T> CompletableFuture<T> failedFuture(Throwable ex)

Returns a new CompletableFuture that is already completed exceptionally with the given exception.

Type Parameters:

T - the type of the value

Parameters:

ex - the exception

Returns:

the exceptionally completed CompletableFuture

completedStage

@Contract(pure=true)
public static <T> CompletionStage<T> completedStage(@Nullable
 T value)

Returns a new CompletionStage that is already completed with the given value and supports only those methods in interface CompletionStage.

CAUTION: if run on old Java 8 (which does not support *minimal* CompletionStage), this method just returns a *normal* CompletableFuture instance which is NOT a *minimal* CompletionStage.

Type Parameters:

T - the type of the value

Parameters:

value - the value

Returns:

the completed CompletionStage

failedStage

@Contract(pure=true)
public static <T> CompletionStage<T> failedStage(Throwable ex)

Returns a new CompletionStage that is already completed exceptionally with the given exception and supports only those methods in interface CompletionStage.

CAUTION: if run on old Java 8 (which does not support *minimal* CompletionStage), this method just returns a *normal* CompletableFuture instance which is NOT a *minimal* CompletionStage.

Type Parameters:

T - the type of the value

Parameters:

ex - the exception

Returns:

the exceptionally completed CompletionStage

fromSyncCall

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, run directly instead of wrapping")
public static <T> CompletableFuture<T> fromSyncCall(Callable<? extends T> callable)

Returns a new CompletableFuture that encapsulates the execution of synchronous logic. By wrapping synchronous code in a CompletableFuture, exceptions can be handled consistently within the CompletableFuture pipeline, eliminating the need to manage separate exceptional paths both inside and outside the flow.

Throws:

NullPointerException - if argument callable is null

See Also:

• CompletableFuture.runAsync(Runnable)
• CompletableFuture.supplyAsync(Supplier)

newIncompleteFuture

@Contract(pure=true)
public static <U> CompletableFuture<U> newIncompleteFuture(CompletableFuture<?> cfThis)

Returns a new incomplete CompletableFuture of the type to be returned by a CompletionStage method.

In general, you won't use this method in application code, prefer other factory methods.

Type Parameters:

U - the type of the value

See Also:

• CompletableFuture.newIncompleteFuture()
• CompletableFuture()

delayedExecutor

@Contract(pure=true)
public static Executor delayedExecutor(long delay,
 TimeUnit unit)

Returns a new Executor that submits a task to the default executor after the given delay (or no delay if non-positive). Each delay commences upon invocation of the returned executor's execute method.

Parameters:

delay - how long to delay, in units of unit

unit - a TimeUnit determining how to interpret the delay parameter

Returns:

the new delayed executor

delayedExecutor

@Contract(pure=true)
public static Executor delayedExecutor(long delay,
 TimeUnit unit,
 Executor executor)

Returns a new Executor that submits a task to the given base executor after the given delay (or no delay if non-positive). Each delay commences upon invocation of the returned executor's execute method.

Parameters:

delay - how long to delay, in units of unit

unit - a TimeUnit determining how to interpret the delay parameter

executor - the base executor

Returns:

the new delayed executor

thenMApplyFailFastAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T,
U> CompletableFuture<List<U>> thenMApplyFailFastAsync(CompletableFuture<? extends T> cfThis,
 Function<? super T,? extends U>... fns)

Shortcut to method allResultsFailFastOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of functions.

See the allResultsFailFastOf documentation for the rules of result computation.

thenMApplyFailFastAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T,
U> CompletableFuture<List<U>> thenMApplyFailFastAsync(CompletableFuture<? extends T> cfThis,
 Executor executor,
 Function<? super T,? extends U>... fns)

Shortcut to method allResultsFailFastOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor); The given CompletableFuture's result is used as the argument of functions.

See the allResultsFailFastOf documentation for the rules of result computation.

NOTE: if the executor argument is passed as a lambda, the Runnable lambda parameter type needs to be explicitly declared to avoid compilation errors; For more information, see the demo code

thenMApplyAllSuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T,
U> CompletableFuture<List<U>> thenMApplyAllSuccessAsync(CompletableFuture<? extends T> cfThis,
 @Nullable
 U valueIfFailed,
 Function<? super T,? extends U>... fns)

Shortcut to method allSuccessResultsOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of functions.

See the allSuccessResultsOf documentation for the rules of result computation.

thenMApplyAllSuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T,
U> CompletableFuture<List<U>> thenMApplyAllSuccessAsync(CompletableFuture<? extends T> cfThis,
 Executor executor,
 @Nullable
 U valueIfFailed,
 Function<? super T,? extends U>... fns)

Shortcut to method allSuccessResultsOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor); The given CompletableFuture's result is used as the argument of functions.

See the allSuccessResultsOf documentation for the rules of result computation.

NOTE: if the executor argument is passed as a lambda, the Runnable lambda parameter type needs to be explicitly declared to avoid compilation errors; For more information, see the demo code

thenMApplyMostSuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T,
U> CompletableFuture<List<U>> thenMApplyMostSuccessAsync(CompletableFuture<? extends T> cfThis,
 @Nullable
 U valueIfNotSuccess,
 long timeout,
 TimeUnit unit,
 Function<? super T,? extends U>... fns)

Shortcut to method mostSuccessResultsOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of functions.

See the mostSuccessResultsOf documentation for the rules of result computation.

thenMApplyMostSuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T,
U> CompletableFuture<List<U>> thenMApplyMostSuccessAsync(CompletableFuture<? extends T> cfThis,
 Executor executor,
 @Nullable
 U valueIfNotSuccess,
 long timeout,
 TimeUnit unit,
 Function<? super T,? extends U>... fns)

Shortcut to method mostSuccessResultsOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor); The given CompletableFuture's result is used as the argument of functions.

See the mostSuccessResultsOf documentation for the rules of result computation.

thenMApplyAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T,
U> CompletableFuture<List<U>> thenMApplyAsync(CompletableFuture<? extends T> cfThis,
 Function<? super T,? extends U>... fns)

Shortcut to method allResultsOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of functions.

See the allResultsOf documentation for the rules of result computation.

thenMApplyAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T,
U> CompletableFuture<List<U>> thenMApplyAsync(CompletableFuture<? extends T> cfThis,
 Executor executor,
 Function<? super T,? extends U>... fns)

Shortcut to method allResultsOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor); The given CompletableFuture's result is used as the argument of functions.

See the allResultsOf documentation for the rules of result computation.

NOTE: if the executor argument is passed as a lambda, the Runnable lambda parameter type needs to be explicitly declared to avoid compilation errors; For more information, see the demo code

thenMApplyAnySuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T,
U> CompletableFuture<U> thenMApplyAnySuccessAsync(CompletableFuture<? extends T> cfThis,
 Function<? super T,? extends U>... fns)

Shortcut to method anySuccessOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of functions.

See the anySuccessOf documentation for the rules of result computation.

thenMApplyAnySuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T,
U> CompletableFuture<U> thenMApplyAnySuccessAsync(CompletableFuture<? extends T> cfThis,
 Executor executor,
 Function<? super T,? extends U>... fns)

Shortcut to method anySuccessOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor); The given CompletableFuture's result is used as the argument of functions.

See the anySuccessOf documentation for the rules of result computation.

NOTE: if the executor argument is passed as a lambda, the Runnable lambda parameter type needs to be explicitly declared to avoid compilation errors; For more information, see the demo code

thenMApplyAnyAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T,
U> CompletableFuture<U> thenMApplyAnyAsync(CompletableFuture<? extends T> cfThis,
 Function<? super T,? extends U>... fns)

Shortcut to method anyOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of functions.

See the anyOf documentation for the rules of result computation.

thenMApplyAnyAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T,
U> CompletableFuture<U> thenMApplyAnyAsync(CompletableFuture<? extends T> cfThis,
 Executor executor,
 Function<? super T,? extends U>... fns)

Shortcut to method anyOf, wraps input functions to CompletableFuture by CompletableFuture.supplyAsync(Supplier, Executor); The given CompletableFuture's result is used as the argument of functions.

See the anyOf documentation for the rules of result computation.

NOTE: if the executor argument is passed as a lambda, the Runnable lambda parameter type needs to be explicitly declared to avoid compilation errors; For more information, see the demo code

thenMAcceptFailFastAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T> CompletableFuture<Void> thenMAcceptFailFastAsync(CompletableFuture<? extends T> cfThis,
 Consumer<? super T>... actions)

Shortcut to method allFailFastOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of actions.

See the allFailFastOf documentation for the rules of result computation.

NOTE: if the second argument is passed as a lambda literal, the lambda parameter type needs to be explicitly declared to avoid the compilation errors; For more information, see the demo code

thenMAcceptFailFastAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T> CompletableFuture<Void> thenMAcceptFailFastAsync(CompletableFuture<? extends T> cfThis,
 Executor executor,
 Consumer<? super T>... actions)

Shortcut to method allFailFastOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of actions.

See the allFailFastOf documentation for the rules of result computation.

NOTE: if the second argument is passed as a lambda literal, the lambda parameter type needs to be explicitly declared to avoid the compilation errors; For more information, see the demo code

thenMAcceptAsync

@SafeVarargs
public static <T> CompletableFuture<Void> thenMAcceptAsync(CompletableFuture<? extends T> cfThis,
 Consumer<? super T>... actions)

Shortcut to method allOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of actions.

See the allOf documentation for the rules of result computation.

NOTE: if the second argument is passed as a lambda literal, the lambda parameter type needs to be explicitly declared to avoid the compilation errors; For more information, see the demo code

thenMAcceptAsync

@SafeVarargs
public static <T> CompletableFuture<Void> thenMAcceptAsync(CompletableFuture<? extends T> cfThis,
 Executor executor,
 Consumer<? super T>... actions)

Shortcut to method allOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor); The given CompletableFuture's result is used as the argument of actions.

See the allOf documentation for the rules of result computation.

NOTE: if the second argument is passed as a lambda literal, the lambda parameter type needs to be explicitly declared to avoid the compilation errors; For more information, see the demo code

thenMAcceptAnySuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T> CompletableFuture<Void> thenMAcceptAnySuccessAsync(CompletableFuture<? extends T> cfThis,
 Consumer<? super T>... actions)

Shortcut to method anySuccessOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of actions.

See the anySuccessOf documentation for the rules of result computation.

NOTE: if the second argument is passed as a lambda literal, the lambda parameter type needs to be explicitly declared to avoid the compilation errors; For more information, see the demo code

thenMAcceptAnySuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T> CompletableFuture<Void> thenMAcceptAnySuccessAsync(CompletableFuture<? extends T> cfThis,
 Executor executor,
 Consumer<? super T>... actions)

Shortcut to method anySuccessOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor); The given CompletableFuture's result is used as the argument of actions.

See the anySuccessOf documentation for the rules of result computation.

NOTE: if the second argument is passed as a lambda literal, the lambda parameter type needs to be explicitly declared to avoid the compilation errors; For more information, see the demo code

thenMAcceptAnyAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T> CompletableFuture<Void> thenMAcceptAnyAsync(CompletableFuture<? extends T> cfThis,
 Consumer<? super T>... actions)

Shortcut to method anyOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis; The given CompletableFuture's result is used as the argument of actions.

See the anyOf documentation for the rules of result computation.

NOTE: if the second argument is passed as a lambda literal, the lambda parameter type needs to be explicitly declared to avoid the compilation errors; For more information, see the demo code

thenMAcceptAnyAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMAcceptAsync`")
@SafeVarargs
public static <T> CompletableFuture<Void> thenMAcceptAnyAsync(CompletableFuture<? extends T> cfThis,
 Executor executor,
 Consumer<? super T>... actions)

Shortcut to method anyOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor); The given CompletableFuture's result is used as the argument of actions.

See the anyOf documentation for the rules of result computation.

NOTE: if the second argument is passed as a lambda literal, the lambda parameter type needs to be explicitly declared to avoid the compilation errors; For more information, see the demo code

thenMRunFailFastAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMRunAsync`")
public static CompletableFuture<Void> thenMRunFailFastAsync(CompletableFuture<?> cfThis,
 Runnable... actions)

Shortcut to method allFailFastOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis.

See the allFailFastOf documentation for the rules of result computation.

thenMRunFailFastAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMRunAsync`")
public static CompletableFuture<Void> thenMRunFailFastAsync(CompletableFuture<?> cfThis,
 Executor executor,
 Runnable... actions)

Shortcut to method allFailFastOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor).

See the allFailFastOf documentation for the rules of result computation.

thenMRunAsync

public static CompletableFuture<Void> thenMRunAsync(CompletableFuture<?> cfThis,
 Runnable... actions)

Shortcut to method allOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis.

See the allOf documentation for the rules of result computation.

thenMRunAsync

public static CompletableFuture<Void> thenMRunAsync(CompletableFuture<?> cfThis,
 Executor executor,
 Runnable... actions)

Shortcut to method allOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor).

See the allOf documentation for the rules of result computation.

thenMRunAnySuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMRunAsync`")
public static CompletableFuture<Void> thenMRunAnySuccessAsync(CompletableFuture<?> cfThis,
 Runnable... actions)

Shortcut to method anySuccessOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis.

See the anySuccessOf documentation for the rules of result computation.

thenMRunAnySuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMRunAsync`")
public static CompletableFuture<Void> thenMRunAnySuccessAsync(CompletableFuture<?> cfThis,
 Executor executor,
 Runnable... actions)

Shortcut to method anySuccessOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor).

See the anySuccessOf documentation for the rules of result computation.

thenMRunAnyAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMRunAsync`")
public static CompletableFuture<Void> thenMRunAnyAsync(CompletableFuture<?> cfThis,
 Runnable... actions)

Shortcut to method anyOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor) using the default executor of parameter cfThis.

See the anyOf documentation for the rules of result computation.

thenMRunAnyAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer simple method `thenMRunAsync`")
public static CompletableFuture<Void> thenMRunAnyAsync(CompletableFuture<?> cfThis,
 Executor executor,
 Runnable... actions)

Shortcut to method anyOf, wraps input actions to CompletableFuture by CompletableFuture.runAsync(Runnable, Executor).

See the anyOf documentation for the rules of result computation.

thenCombineFailFast

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer method `thenAcceptBoth`")
public static <T,
U,
V> CompletableFuture<V> thenCombineFailFast(CompletableFuture<? extends T> cfThis,
 CompletionStage<? extends U> other,
 BiFunction<? super T,? super U,? extends V> fn)

Returns a new CompletableFuture that, when both of given stages complete normally, is executed with the two results as arguments to the supplied function. If any of the given stages complete exceptionally, then the returned CompletableFuture also does so *without* waiting other incomplete given CompletionStage, with a CompletionException holding this exception as its cause.

Parameters:

fn - the function to use to compute the value of the returned CompletableFuture

thenCombineFailFastAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer method `thenAcceptBothAsync`")
public static <T,
U,
V> CompletableFuture<V> thenCombineFailFastAsync(CompletableFuture<? extends T> cfThis,
 CompletionStage<? extends U> other,
 BiFunction<? super T,? super U,? extends V> fn)

Returns a new CompletableFuture that, when both of given stages complete normally, is executed using the default executor of parameter cfThis, with the two results as arguments to the supplied function. If any of the given stages complete exceptionally, then the returned CompletableFuture also does so *without* waiting other incomplete given CompletionStage, with a CompletionException holding this exception as its cause.

Parameters:

fn - the function to use to compute the value of the returned CompletableFuture

thenCombineFailFastAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer method `thenAcceptBothAsync`")
public static <T,
U,
V> CompletableFuture<V> thenCombineFailFastAsync(CompletableFuture<? extends T> cfThis,
 CompletionStage<? extends U> other,
 BiFunction<? super T,? super U,? extends V> fn,
 Executor executor)

Returns a new CompletableFuture that, when both of given stages complete normally, is executed using the supplied executor, with the two results as arguments to the supplied function. If any of the given stages complete exceptionally, then the returned CompletableFuture also does so *without* waiting other incomplete given CompletionStage, with a CompletionException holding this exception as its cause.

Parameters:

fn - the function to use to compute the value of the returned CompletableFuture

thenAcceptBothFailFast

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer method `thenAcceptBoth`")
public static <T,
U> CompletableFuture<Void> thenAcceptBothFailFast(CompletableFuture<? extends T> cfThis,
 CompletionStage<? extends U> other,
 BiConsumer<? super T,? super U> action)

Returns a new CompletableFuture that, when both of given stages complete normally, is executed with the two results as arguments to the supplied action. If any of the given stages complete exceptionally, then the returned CompletableFuture also does so *without* waiting other incomplete given CompletionStage, with a CompletionException holding this exception as its cause.

Parameters:

action - the action to perform before completing the returned CompletableFuture

thenAcceptBothFailFastAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer method `thenAcceptBothAsync`")
public static <T,
U> CompletableFuture<Void> thenAcceptBothFailFastAsync(CompletableFuture<? extends T> cfThis,
 CompletionStage<? extends U> other,
 BiConsumer<? super T,? super U> action)

Returns a new CompletableFuture that, when both of given stages complete normally, is executed using the default executor of parameter cfThis, with the two results as arguments to the supplied action. If any of the given stages complete exceptionally, then the returned CompletableFuture also does so *without* waiting other incomplete given CompletionStage, with a CompletionException holding this exception as its cause.

Parameters:

action - the action to perform before completing the returned CompletableFuture

thenAcceptBothFailFastAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer method `thenAcceptBothAsync`")
public static <T,
U> CompletableFuture<Void> thenAcceptBothFailFastAsync(CompletableFuture<? extends T> cfThis,
 CompletionStage<? extends U> other,
 BiConsumer<? super T,? super U> action,
 Executor executor)

Returns a new CompletableFuture that, when both of given stages complete normally, is executed using the supplied executor, with the two results as arguments to the supplied action. If any of the given stages complete exceptionally, then the returned CompletableFuture also does so *without* waiting other incomplete given CompletionStage, with a CompletionException holding this exception as its cause.

Parameters:

action - the action to perform before completing the returned CompletableFuture

runAfterBothFailFast

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer method `runAfterBoth`")
public static CompletableFuture<Void> runAfterBothFailFast(CompletableFuture<?> cfThis,
 CompletionStage<?> other,
 Runnable action)

Returns a new CompletableFuture that, when two given stages both complete normally, executes the given action. If any of the given stages complete exceptionally, then the returned CompletableFuture also does so *without* waiting other incomplete given CompletionStage, with a CompletionException holding this exception as its cause.

Parameters:

action - the action to perform before completing the returned CompletableFuture

runAfterBothFailFastAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer method `runAfterBothAsync`")
public static CompletableFuture<Void> runAfterBothFailFastAsync(CompletableFuture<?> cfThis,
 CompletionStage<?> other,
 Runnable action)

Returns a new CompletableFuture that, when two given stages both complete normally, executes the given action using the default executor of parameter cfThis. If any of the given stages complete exceptionally, then the returned CompletableFuture also does so *without* waiting other incomplete given CompletionStage, with a CompletionException holding this exception as its cause.

Parameters:

action - the action to perform before completing the returned CompletableFuture

runAfterBothFailFastAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer method `runAfterBothAsync`")
public static CompletableFuture<Void> runAfterBothFailFastAsync(CompletableFuture<?> cfThis,
 CompletionStage<?> other,
 Runnable action,
 Executor executor)

Returns a new CompletableFuture that, when two given stages both complete normally, executes the given action using the supplied executor. If any of the given stages complete exceptionally, then the returned CompletableFuture also does so *without* waiting other incomplete given CompletionStage, with a CompletionException holding this exception as its cause.

Parameters:

action - the action to perform before completing the returned CompletableFuture

applyToEitherSuccess

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer method `acceptEitherSuccess`")
public static <T,
U> CompletableFuture<U> applyToEitherSuccess(CompletableFuture<? extends T> cfThis,
 CompletionStage<? extends T> other,
 Function<? super T,? extends U> fn)

Returns a new CompletableFuture that, when either of given stages success, is executed with the corresponding result as argument to the supplied function. Otherwise, both complete exceptionally, the returned CompletableFuture also does so, with a CompletionException holding an exception from either as its cause.

Type Parameters:

U - the function's return type

Parameters:

fn - the function to use to compute the value of the returned CompletableFuture

applyToEitherSuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer method `acceptEitherSuccessAsync`")
public static <T,
U> CompletableFuture<U> applyToEitherSuccessAsync(CompletableFuture<? extends T> cfThis,
 CompletionStage<? extends T> other,
 Function<? super T,? extends U> fn)

Returns a new CompletableFuture that, when either of given stages success, is executed using the default executor of parameter cfThis, with the corresponding result as argument to the supplied function. Otherwise, both complete exceptionally, the returned CompletableFuture also does so, with a CompletionException holding an exception from either as its cause.

Type Parameters:

U - the function's return type

Parameters:

fn - the function to use to compute the value of the returned CompletableFuture

applyToEitherSuccessAsync

@CheckReturnValue(explanation="should use the returned CompletableFuture; otherwise, prefer method `acceptEitherSuccessAsync`")
public static <T,
U> CompletableFuture<U> applyToEitherSuccessAsync(CompletableFuture<? extends T> cfThis,
 CompletionStage<? extends T> other,
 Function<? super T,? extends U> fn,
 Executor executor)

Returns a new CompletableFuture that, when either of given stages success, is executed using the supplied executor, with the corresponding result as argument to the supplied function. Otherwise, both complete exceptionally, the returned CompletableFuture also does so, with a CompletionException holding an exception from either as its cause.

Type Parameters:

U - the function's return type

Parameters:

fn - the function to use to compute the value of the returned CompletableFuture

executor - the executor to use for asynchronous execution

acceptEitherSuccess

public static <T> CompletableFuture<Void> acceptEitherSuccess(CompletableFuture<? extends T> cfThis,
 CompletionStage<? extends T> other,
 Consumer<? super T> action)

Returns a new CompletableFuture that, when either of given stages success, is executed with the corresponding result as argument to the supplied action. Otherwise, both complete exceptionally, the returned CompletableFuture also does so, with a CompletionException holding an exception from either as its cause.

Parameters:

action - the action to perform before completing the returned CompletableFuture

acceptEitherSuccessAsync

public static <T> CompletableFuture<Void> acceptEitherSuccessAsync(CompletableFuture<? extends T> cfThis,
 CompletionStage<? extends T> other,
 Consumer<? super T> action)

Returns a new CompletableFuture that, when either of given stages success, is executed using the default executor of parameter cfThis, with the corresponding result as argument to the supplied action. Otherwise, both complete exceptionally, the returned CompletableFuture also does so, with a CompletionException holding an exception from either as its cause.

Parameters:

action - the action to perform before completing the returned CompletableFuture

acceptEitherSuccessAsync

public static <T> CompletableFuture<Void> acceptEitherSuccessAsync(CompletableFuture<? extends T> cfThis,
 CompletionStage<? extends T> other,
 Consumer<? super T> action,
 Executor executor)

Returns a new CompletableFuture that, when either of given stages success, is executed using the supplied executor, with the corresponding result as argument to the supplied action. Otherwise, both complete exceptionally, the returned CompletableFuture also does so, with a CompletionException holding an exception from either as its cause.

Parameters:

action - the action to perform before completing the returned CompletableFuture

executor - the executor to use for asynchronous execution

runAfterEitherSuccess

public static CompletableFuture<Void> runAfterEitherSuccess(CompletableFuture<?> cfThis,
 CompletionStage<?> other,
 Runnable action)

Returns a new CompletableFuture that, when either of given stages success, executes the given action. Otherwise, both complete exceptionally, the returned CompletableFuture also does so, with a CompletionException holding an exception from either as its cause.

Parameters:

action - the action to perform before completing the returned CompletableFuture

runAfterEitherSuccessAsync

public static CompletableFuture<Void> runAfterEitherSuccessAsync(CompletableFuture<?> cfThis,
 CompletionStage<?> other,
 Runnable action)

Returns a new CompletableFuture that, when either of given stages success, executes the given action using the default executor of parameter cfThis. Otherwise, both complete exceptionally, the returned CompletableFuture also does so, with a CompletionException holding an exception from either as its cause.

Parameters:

action - the action to perform before completing the returned CompletableFuture

runAfterEitherSuccessAsync

public static CompletableFuture<Void> runAfterEitherSuccessAsync(CompletableFuture<?> cfThis,
 CompletionStage<?> other,
 Runnable action,
 Executor executor)

Returns a new CompletableFuture that, when either of given stages success, executes the given action using the supplied executor. Otherwise, both complete exceptionally, the returned CompletableFuture also does so, with a CompletionException holding an exception from either as its cause.

Parameters:

action - the action to perform before completing the returned CompletableFuture

catching

public static <T,
X extends Throwable,
F extends CompletionStage<T>>
F catching(F cfThis,
 Class<X> exceptionType,
 Function<? super X,? extends T> fallback)

Returns a new CompletableFuture that, when the given stage completes exceptionally with the given exceptionType, is executed with the exception from the given stage(argument cfThis) as the argument to the supplied function. Otherwise, the returned stage contains the same result as the given stage.

"The exception from the given stage(argument cfThis)" means the cause of the ExecutionException thrown by get() or, if get() throws a different kind of exception, that exception itself; aka the exception is unwrapped by unwrapCfException(Throwable).

Parameters:

exceptionType - the exception type that triggers use of fallback. The exception type is matched against the exception from argument cfThis. To avoid hiding bugs and other unrecoverable errors, callers should prefer more specific types, avoiding Throwable.class in particular.

fallback - the Function to be called if cfThis fails with the expected exception type. The function's argument is the exception from cfThis.

See Also:

• unwrapCfException(Throwable)
• the equivalent Guava method catching()

catchingAsync

public static <T,
X extends Throwable,
F extends CompletionStage<T>>
F catchingAsync(F cfThis,
 Class<X> exceptionType,
 Function<? super X,? extends T> fallback)

Returns a new CompletableFuture that, when the given stage completes exceptionally with the given exceptionType, is executed with the exception from the given stage(argument cfThis) as the argument to the supplied function, using the default executor of parameter the given stage. Otherwise, the returned stage contains the same result as the given stage.

"The exception from the given stage(argument cfThis)" means the cause of the ExecutionException thrown by get() or, if get() throws a different kind of exception, that exception itself; aka the exception is unwrapped by unwrapCfException(Throwable).

Parameters:

exceptionType - the exception type that triggers use of fallback. The exception type is matched against the exception from argument cfThis. To avoid hiding bugs and other unrecoverable errors, callers should prefer more specific types, avoiding Throwable.class in particular.

fallback - the Function to be called if cfThis fails with the expected exception type. The function's argument is the exception from cfThis.

See Also:

• unwrapCfException(Throwable)
• the equivalent Guava method catching()

catchingAsync

public static <T,
X extends Throwable,
F extends CompletionStage<T>>
F catchingAsync(F cfThis,
 Class<X> exceptionType,
 Function<? super X,? extends T> fallback,
 Executor executor)

Returns a new CompletableFuture that, when the given stage completes exceptionally with the given exceptionType, is executed with the exception from the given stage(argument cfThis) as the argument to the supplied function, using the supplied Executor. Otherwise, the returned stage contains the same result as the given stage.

"The exception from the given stage(argument cfThis)" means the cause of the ExecutionException thrown by get() or, if get() throws a different kind of exception, that exception itself; aka the exception is unwrapped by unwrapCfException(Throwable).

Parameters:

exceptionType - the exception type that triggers use of fallback. The exception type is matched against the exception from argument cfThis. To avoid hiding bugs and other unrecoverable errors, callers should prefer more specific types, avoiding Throwable.class in particular.

fallback - the Function to be called if cfThis fails with the expected exception type. The function's argument is the exception from cfThis.

executor - the executor to use for asynchronous execution

See Also:

• unwrapCfException(Throwable)
• the equivalent Guava method catching()

exceptionallyAsync

public static <T,
F extends CompletionStage<T>> F exceptionallyAsync(F cfThis,
 Function<Throwable,? extends T> fn)

Returns a new CompletableFuture that, when the given stage completes exceptionally, is executed with the given stage's exception as the argument to the supplied function, using the default executor of parameter cfThis. Otherwise, if the given stage completes normally, then the returned stage also completes normally with the same value.

Just as catching Throwable is not best practice in general, this method handles the Throwable; Strongly recommend using catchingAsync(CompletionStage, Class, Function) instead in your business application.

Parameters:

fn - the function to use to compute the value of the returned CompletableFuture if given CompletionStage completed exceptionally

See Also:

• catchingAsync(CompletionStage, Class, Function)

exceptionallyAsync

public static <T,
F extends CompletionStage<T>> F exceptionallyAsync(F cfThis,
 Function<Throwable,? extends T> fn,
 Executor executor)

Returns a new CompletableFuture that, when the given stage completes exceptionally, is executed with the given stage's exception as the argument to the supplied function, using the supplied Executor. Otherwise, if the given stage completes normally, then the returned stage also completes normally with the same value.

Just as catching Throwable is not best practice in general, this method handles the Throwable; Strongly recommend using catchingAsync(CompletionStage, Class, Function, Executor) instead in your business application.

Parameters:

fn - the function to use to compute the value of the returned CompletableFuture if given CompletionStage completed exceptionally

executor - the executor to use for asynchronous execution

See Also:

• catchingAsync(CompletionStage, Class, Function, Executor)

cffuOrTimeout

public static <F extends CompletableFuture<?>> F cffuOrTimeout(F cfThis,
 long timeout,
 TimeUnit unit)

Returns a new CompletableFuture that is completed exceptionally with a TimeoutException when the given CompletableFuture is not completed before the given timeout; otherwise the returned CompletableFuture completed with the same successful result or exception of the given CompletableFuture.

Uses the default executor of parameter cfThis as executorWhenTimeout.

CAUTION: This method returns a new CompletableFuture instead of cfThis to avoid the subsequent usage of the SINGLE-thread ScheduledThreadPoolExecutor's thread; This behavior is DIFFERENT from the original CF method CompletableFuture#orTimeout and its backport method orTimeout. For more information, see the Javadoc of orTimeout and the demo DelayDysfunctionDemo.

Parameters:

timeout - how long to wait before completing exceptionally with a TimeoutException, in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

See Also:

• cffuOrTimeout(CompletableFuture, long, TimeUnit, Executor)

cffuOrTimeout

public static <F extends CompletableFuture<?>> F cffuOrTimeout(F cfThis,
 long timeout,
 TimeUnit unit,
 Executor executorWhenTimeout)

Returns a new CompletableFuture that is completed exceptionally with a TimeoutException when the given CompletableFuture is not completed before the given timeout; otherwise the returned CompletableFuture completed with the same successful result or exception of the given CompletableFuture.

CAUTION: This method returns a new CompletableFuture instead of cfThis to avoid the subsequent usage of the SINGLE-thread ScheduledThreadPoolExecutor's thread; This behavior is DIFFERENT from the original CF method CompletableFuture#orTimeout and its backport method orTimeout. For more information, see the Javadoc of orTimeout and the demo DelayDysfunctionDemo.

Parameters:

timeout - how long to wait before completing exceptionally with a TimeoutException, in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

executorWhenTimeout - the executor to use for asynchronous execution when the wait timed out

orTimeout

@Contract("_, _, _ -> param1")
public static <F extends CompletableFuture<?>> F orTimeout(F cfThis,
 long timeout,
 TimeUnit unit)

Exceptionally completes given CompletableFuture with a TimeoutException if not otherwise completed before the given timeout.

CAUTION: CompletableFuture#orTimeout and this backport method is UNSAFE!

When the wait timed out, the subsequent non-async actions of the dependent CompletableFutures are performed in CompletableFuture's internal SINGLE-thread ScheduledThreadPoolExecutor (including delay functionality). This means that the long-running subsequent non-async actions will block this executor thread, preventing it from handling other timeouts and delays, effectively breaking CompletableFuture's timeout and delay functionality.

Strongly recommend using the safe method cffuOrTimeout instead of CompletableFuture#orTimeout and this backport method. Using CompletableFuture#orTimeout and this backport method is appropriate only when:

• the returned CompletableFuture is only read explicitly(e.g. by get/join/resultNow methods),
• and/or all subsequent actions of dependent CompletableFutures are guaranteed to execute asynchronously (i.e., the dependent CompletableFutures are created using async methods).

In these cases, using these unsafe methods avoids an unnecessary thread switching when timeout occurs; However, these conditions are difficult to guarantee in practice, especially when the returned CompletableFuture is used by others' codes.

Note: Before Java 21(Java 20-), CompletableFuture#orTimeout method leaks if the future completes exceptionally; For more information, see issue JDK-8303742, PR review openjdk/jdk/13059 and JDK bugfix commit. The cffu backport logic (for Java 20-) has merged this JDK bugfix.

Parameters:

timeout - how long to wait before completing exceptionally with a TimeoutException, in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

Returns:

the given CompletableFuture

See Also:

• cffuOrTimeout(CompletableFuture, long, TimeUnit, Executor)

cffuCompleteOnTimeout

public static <T,
F extends CompletableFuture<? super T>>
F cffuCompleteOnTimeout(F cfThis,
 @Nullable
 T value,
 long timeout,
 TimeUnit unit)

Returns a new CompletableFuture that is completed normally with the given value when the given CompletableFuture is not completed before the given timeout; otherwise the returned CompletableFuture completed with the same successful result or exception of the given CompletableFuture.

Uses the default executor of parameter cfThis as executorWhenTimeout.

CAUTION: This method returns a new CompletableFuture instead of cfThis to avoid the subsequent usage of the SINGLE-thread ScheduledThreadPoolExecutor's thread; This behavior is DIFFERENT from the original CF method CompletableFuture#completeOnTimeout and its backport method completeOnTimeout. For more information, see the Javadoc of completeOnTimeout and the demo DelayDysfunctionDemo.

Parameters:

value - the value to use upon timeout

timeout - how long to wait before completing normally with the given value, in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

See Also:

• cffuCompleteOnTimeout(CompletableFuture, Object, long, TimeUnit, Executor)

cffuCompleteOnTimeout

public static <T,
F extends CompletableFuture<? super T>>
F cffuCompleteOnTimeout(F cfThis,
 @Nullable
 T value,
 long timeout,
 TimeUnit unit,
 Executor executorWhenTimeout)

Returns a new CompletableFuture that is completed normally with the given value when the given CompletableFuture is not completed before the given timeout; otherwise the returned CompletableFuture completed with the same successful result or exception of the given CompletableFuture.

CAUTION: This method returns a new CompletableFuture instead of cfThis to avoid the subsequent usage of the SINGLE-thread ScheduledThreadPoolExecutor's thread; This behavior is DIFFERENT from the original CF method CompletableFuture#completeOnTimeout and its backport method completeOnTimeout. For more information, see the Javadoc of completeOnTimeout and the demo DelayDysfunctionDemo.

Parameters:

value - the value to use upon timeout

timeout - how long to wait before completing normally with the given value, in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

executorWhenTimeout - the executor to use for asynchronous execution when the wait timed out

completeOnTimeout

@Contract("_, _, _, _ -> param1")
public static <T,
F extends CompletableFuture<? super T>>
F completeOnTimeout(F cfThis,
 @Nullable
 T value,
 long timeout,
 TimeUnit unit)

Completes given CompletableFuture with the given value if not otherwise completed before the given timeout.

CAUTION: CompletableFuture#completeOnTimeout and this backport method is UNSAFE!

When the wait timed out, the subsequent non-async actions of the dependent CompletableFutures are performed in CompletableFuture's internal SINGLE-thread ScheduledThreadPoolExecutor (including delay functionality). This means that the long-running subsequent non-async actions will block this executor thread, preventing it from handling other timeouts and delays, effectively breaking CompletableFuture's timeout and delay functionality.

Strongly recommend using the safe method cffuCompleteOnTimeout instead of CompletableFuture#completeOnTimeout and this backport method. Using CompletableFuture#completeOnTimeout and this backport method is appropriate only when:

• the returned CompletableFuture is only read explicitly(e.g. by get/join/resultNow methods),
• and/or all subsequent actions of dependent CompletableFutures are guaranteed to execute asynchronously (i.e., the dependent CompletableFutures are created using async methods).

In these cases, using these unsafe methods avoids an unnecessary thread switching when timeout occurs; However, these conditions are difficult to guarantee in practice, especially when the returned CompletableFuture is used by others' codes.

Parameters:

value - the value to use upon timeout

timeout - how long to wait before completing normally with the given value, in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

Returns:

the given CompletableFuture

See Also:

• cffuCompleteOnTimeout(CompletableFuture, Object, long, TimeUnit, Executor)

catchingCompose

public static <T,
X extends Throwable,
F extends CompletionStage<T>>
F catchingCompose(F cfThis,
 Class<X> exceptionType,
 Function<? super X,? extends CompletionStage<T>> fallback)

Returns a new CompletionStage that, when the given stage completes exceptionally with the given exceptionType, is composed using the results of the supplied function applied to the exception from the given stage(argument cfThis).

"The exception from the given stage(argument cfThis)" means the cause of the ExecutionException thrown by get() or, if get() throws a different kind of exception, that exception itself; aka the exception is unwrapped by unwrapCfException(Throwable).

Parameters:

exceptionType - the exception type that triggers use of fallback. The exception type is matched against the exception from argument cfThis. To avoid hiding bugs and other unrecoverable errors, callers should prefer more specific types, avoiding Throwable.class in particular.

fallback - the Function to be called if cfThis fails with the expected exception type. The function's argument is the exception from cfThis.

See Also:

• unwrapCfException(Throwable)
• the equivalent Guava method catchingAsync()

catchingComposeAsync

public static <T,
X extends Throwable,
F extends CompletionStage<T>>
F catchingComposeAsync(F cfThis,
 Class<X> exceptionType,
 Function<? super X,? extends CompletionStage<T>> fallback)

Returns a new CompletionStage that, when the given stage completes exceptionally with the given exceptionType, is composed using the results of the supplied function applied to the exception from the given stage(argument cfThis), using the default executor of parameter the given stage.

"The exception from the given stage(argument cfThis)" means the cause of the ExecutionException thrown by get() or, if get() throws a different kind of exception, that exception itself; aka the exception is unwrapped by unwrapCfException(Throwable).

Parameters:

exceptionType - the exception type that triggers use of fallback. The exception type is matched against the exception from argument cfThis. To avoid hiding bugs and other unrecoverable errors, callers should prefer more specific types, avoiding Throwable.class in particular.

fallback - the Function to be called if cfThis fails with the expected exception type. The function's argument is the exception from cfThis.

See Also:

• unwrapCfException(Throwable)
• the equivalent Guava method catchingAsync()

catchingComposeAsync

public static <T,
X extends Throwable,
F extends CompletionStage<T>>
F catchingComposeAsync(F cfThis,
 Class<X> exceptionType,
 Function<? super X,? extends CompletionStage<T>> fallback,
 Executor executor)

Returns a new CompletionStage that, when the given stage completes exceptionally with the given exceptionType, is composed using the results of the supplied function applied to the exception from the given stage(argument cfThis), using the supplied Executor.

"The exception from the given stage(argument cfThis)" means the cause of the ExecutionException thrown by get() or, if get() throws a different kind of exception, that exception itself; aka the exception is unwrapped by unwrapCfException(Throwable).

Parameters:

exceptionType - the exception type that triggers use of fallback. The exception type is matched against the exception from argument cfThis. To avoid hiding bugs and other unrecoverable errors, callers should prefer more specific types, avoiding Throwable.class in particular.

fallback - the Function to be called if cfThis fails with the expected exception type. The function's argument is the exception from cfThis.

executor - the executor to use for asynchronous execution

See Also:

• unwrapCfException(Throwable)
• the equivalent Guava method catchingAsync()

exceptionallyCompose

public static <T,
F extends CompletionStage<T>> F exceptionallyCompose(F cfThis,
 Function<Throwable,? extends CompletionStage<T>> fn)

Returns a new CompletableFuture that, when given CompletableFuture completes exceptionally, is composed using the results of the supplied function applied to the given stage's exception.

Just as catching Throwable is not best practice in general, this method handles the Throwable; Strongly recommend using catchingCompose(CompletionStage, Class, Function) instead in your business application.

Parameters:

fn - the function to use to compute the returned CompletableFuture if given CompletionStage completed exceptionally

See Also:

• catchingCompose(CompletionStage, Class, Function)

exceptionallyComposeAsync

public static <T,
F extends CompletionStage<T>> F exceptionallyComposeAsync(F cfThis,
 Function<Throwable,? extends CompletionStage<T>> fn)

Returns a new CompletableFuture that, when given CompletableFuture completes exceptionally, is composed using the results of the supplied function applied to the given stage's exception, using the default executor of parameter cfThis.

Just as catching Throwable is not best practice in general, this method handles the Throwable; Strongly recommend using catchingComposeAsync(CompletionStage, Class, Function) instead in your business application.

Parameters:

fn - the function to use to compute the returned CompletableFuture if given CompletionStage completed exceptionally

See Also:

• catchingComposeAsync(CompletionStage, Class, Function)

exceptionallyComposeAsync

public static <T,
F extends CompletionStage<T>> F exceptionallyComposeAsync(F cfThis,
 Function<Throwable,? extends CompletionStage<T>> fn,
 Executor executor)

Returns a new CompletableFuture that, when given CompletableFuture completes exceptionally, is composed using the results of the supplied function applied to the given stage's exception, using the supplied Executor.

Just as catching Throwable is not best practice in general, this method handles the Throwable; Strongly recommend using catchingComposeAsync(CompletionStage, Class, Function, Executor) instead in your business application.

Parameters:

fn - the function to use to compute the returned CompletableFuture if given CompletionStage completed exceptionally

executor - the executor to use for asynchronous execution

See Also:

• catchingComposeAsync(CompletionStage, Class, Function, Executor)

peek

@Contract("_, _ -> param1")
public static <T,
F extends CompletionStage<? extends T>>
F peek(F cfThis,
 BiConsumer<? super T,? super Throwable> action)

Peeks the result by executing the given action when the given stage completes, returns the given stage.

When the given stage is complete, the given action is invoked with the result(or null if none) and the exception (or null if none) of given stage as arguments.

NOTE: When using CompletionStage.whenComplete(BiConsumer), if the input stage completes normally but the supplied action throws an exception, the returned stage will contain a DIFFERENT result than the input stage. This subtle behavior of whenComplete can lead to bugs when you only want to peek at the stage's result (e.g. for logging) without modifying it.
In contrast, this peek method guarantees that the returned stage (which is the input stage) will maintain its original result, regardless of whether the supplied action throws an exception or not.

CAUTION: Since this method returns the input stage directly, the execution order between the given action and other actions added to the input stage cannot be guaranteed. The given action should be treated as "fire and forget" - do not make any assumptions about timing or execution sequence.

Unlike method CompletionStage.handle(BiFunction) and like method CompletionStage.whenComplete(BiConsumer), this method is not designed to translate completion outcomes.

Parameters:

action - the action to perform

Returns:

the given stage

See Also:

• CompletionStage.whenComplete(BiConsumer)
• Stream.peek(Consumer)

peekAsync

@Contract("_, _ -> param1")
public static <T,
F extends CompletionStage<? extends T>>
F peekAsync(F cfThis,
 BiConsumer<? super T,? super Throwable> action)

Peeks the result by executing the given action using the default executor of parameter cfThis when the given stage completes, returns the given stage.

When the given stage is complete, the given action is invoked with the result(or null if none) and the exception (or null if none) of given stage as arguments.

NOTE: When using CompletionStage.whenCompleteAsync(BiConsumer), if the input stage completes normally but the supplied action throws an exception, the returned stage will contain a DIFFERENT result than the input stage. This subtle behavior of whenComplete can lead to bugs when you only want to peek at the stage's result (e.g. for logging) without modifying it.
In contrast, this peekAsync method guarantees that the returned stage (which is the input stage) will maintain its original result, regardless of whether the supplied action throws an exception or not.

CAUTION: Since this method returns the input stage directly, the execution order between the given action and other actions added to the input stage cannot be guaranteed. The given action should be treated as "fire and forget" - do not make any assumptions about timing or execution sequence.

Unlike method CompletionStage.handleAsync(BiFunction) and like method CompletionStage.whenCompleteAsync(BiConsumer), this method is not designed to translate completion outcomes.

Parameters:

action - the action to perform

Returns:

the given stage

See Also:

• CompletionStage.whenCompleteAsync(BiConsumer)
• Stream.peek(Consumer)

peekAsync

@Contract("_, _, _ -> param1")
public static <T,
F extends CompletionStage<? extends T>>
F peekAsync(F cfThis,
 BiConsumer<? super T,? super Throwable> action,
 Executor executor)

Peeks the result by executing the given action using the supplied executor when the given stage completes, returns the given stage.

When the given stage is complete, the given action is invoked with the result(or null if none) and the exception (or null if none) of given stage as arguments.

NOTE: When using CompletionStage.whenCompleteAsync(BiConsumer, Executor), if the input stage completes normally but the supplied action throws an exception, the returned stage will contain a DIFFERENT result than the input stage. This subtle behavior of whenComplete can lead to bugs when you only want to peek at the stage's result (e.g. for logging) without modifying it.
In contrast, this peekAsync method guarantees that the returned stage (which is the input stage) will maintain its original result, regardless of whether the supplied action throws an exception or not.

CAUTION: Since this method returns the input stage directly, the execution order between the given action and other actions added to the input stage cannot be guaranteed. The given action should be treated as "fire and forget" - do not make any assumptions about timing or execution sequence.

Unlike method CompletionStage.handleAsync(BiFunction, Executor) and like method CompletionStage.whenCompleteAsync(BiConsumer, Executor), this method is not designed to translate completion outcomes.

Parameters:

action - the action to perform

Returns:

the given stage

See Also:

• CompletionStage.whenCompleteAsync(BiConsumer, Executor)
• Stream.peek(Consumer)

join

@Blocking
@Nullable
public static <T> T join(CompletableFuture<? extends T> cfThis,
 long timeout,
 TimeUnit unit)

Waits if necessary for at most the given time for the computation to complete and then retrieves its result value when complete, or throws an (unchecked) exception if completed exceptionally.

CAUTION: if the wait timed out, this method throws an (unchecked) CompletionException with the TimeoutException as its cause; NOT throws a (checked) TimeoutException like CompletableFuture.get(long, TimeUnit).

NOTE: Calling this method

result = CompletableFutureUtils.join(cf, timeout, unit);

is the same as:

result = cf.copy() // defensive copy to avoid writing this cf unexpectedly
     .orTimeout(timeout, unit)
     .join();

Parameters:

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

the result value

Throws:

CancellationException - if the computation was cancelled

CompletionException - if given future completed exceptionally or a completion computation threw an exception, or the wait timed out (with the TimeoutException as its cause)

See Also:

• CompletableFuture.join()

getSuccessNow

@Contract(pure=true)
@Nullable
public static <T> T getSuccessNow(CompletableFuture<? extends T> cfThis,
 @Nullable
 T valueIfNotSuccess)

Returns the result value if the given stage is completed normally, else returns the given valueIfNotSuccess.

This method is guaranteed not to throw CompletionException, ExecutionException, CancellationException and IllegalStateException.

Parameters:

valueIfNotSuccess - the value to return if not completed normally

Returns:

the result value, if completed normally, else the given valueIfNotSuccess

Throws:

NullPointerException - if the given CompletableFuture is null

resultNow

@Contract(pure=true)
@Nullable
public static <T> T resultNow(Future<? extends T> cfThis)

Returns the computed result without waiting.

This method is for cases where the caller knows that the task has already completed normally, for example, when filtering a stream of Future objects for the successful tasks and using a mapping operation to obtain a stream of results.

results = futures.stream()
     .filter(f -> f.state() == Future.State.SUCCESS)
     .map(Future::resultNow)
     .toList();

Returns:

the computed result

Throws:

IllegalStateException - if the task has not completed, or the task did not complete with a result

exceptionNow

@Contract(pure=true)
public static Throwable exceptionNow(Future<?> cfThis)

Returns the exception thrown by the task without waiting.

This method is for cases where the caller knows that the task has already completed with an exception.

Returns:

the exception thrown by the task

Throws:

IllegalStateException - if the task has not completed, the task completed normally, or the task was cancelled

state

@Contract(pure=true)
public static CffuState state(Future<?> cfThis)

Returns the computation state (CffuState). This method provides equivalent functionality to CompletableFuture.state() with backwards compatibility for Java 18-.

Returns:

the computation state

See Also:

• Future.state()

completeAsync

@Contract("_, _ -> param1")
public static <T,
F extends CompletableFuture<? super T>>
F completeAsync(F cfThis,
 Supplier<? extends T> supplier)

Completes given CompletableFuture with the result of the given Supplier function invoked from an asynchronous task using the default executor of parameter cfThis.

Parameters:

supplier - a function returning the value to be used to complete the given CompletableFuture

Returns:

the given CompletableFuture

See Also:

• CompletableFuture.completeAsync(Supplier)

completeAsync

@Contract("_, _, _ -> param1")
public static <T,
F extends CompletableFuture<? super T>>
F completeAsync(F cfThis,
 Supplier<? extends T> supplier,
 Executor executor)

Completes given CompletableFuture with the result of the given Supplier function invoked from an asynchronous task using the given executor.

Parameters:

supplier - a function returning the value to be used to complete the given CompletableFuture

executor - the executor to use for asynchronous execution

Returns:

the given CompletableFuture

See Also:

• CompletableFuture.completeAsync(Supplier, Executor)

completeExceptionallyAsync

@Contract("_, _ -> param1")
public static <F extends CompletableFuture<?>> F completeExceptionallyAsync(F cfThis,
 Supplier<? extends Throwable> supplier)

If not already completed, completes given CompletableFuture with the exception result of the given Supplier function invoked from an asynchronous task using the default executor of parameter cfThis.

Parameters:

supplier - a function returning the value to be used to complete the given CompletableFuture

Returns:

the given CompletableFuture

See Also:

• CompletableFuture.completeExceptionally(Throwable)

completeExceptionallyAsync

@Contract("_, _, _ -> param1")
public static <F extends CompletableFuture<?>> F completeExceptionallyAsync(F cfThis,
 Supplier<? extends Throwable> supplier,
 Executor executor)

If not already completed, completes given CompletableFuture with the exception result of the given Supplier function invoked from an asynchronous task using the given executor.

Parameters:

supplier - a function returning the value to be used to complete the given CompletableFuture

executor - the executor to use for asynchronous execution

Returns:

the given CompletableFuture

See Also:

• CompletableFuture.completeExceptionally(Throwable)

copy

@Contract(pure=true)
public static <T> CompletableFuture<T> copy(CompletableFuture<T> cfThis)

Returns a new CompletableFuture that is completed normally with the same value as this CompletableFuture when it completes normally. If this CompletableFuture completes exceptionally, then the returned CompletableFuture completes exceptionally with a CompletionException with this exception as cause. The behavior is equivalent to thenApply(x -> x). This method may be useful as a form of "defensive copying", to prevent clients from completing, while still being able to arrange dependent actions.

See Also:

• CompletableFuture.copy()

minimalCompletionStage

@Contract(pure=true)
public static <T> CompletionStage<T> minimalCompletionStage(CompletableFuture<T> cfThis)

Returns a new CompletionStage that is completed normally with the same value as given CompletableFuture when it completes normally, and cannot be independently completed or otherwise used in ways not defined by the methods of interface CompletionStage. If the given CompletableFuture completes exceptionally, then the returned CompletionStage completes exceptionally with a CompletionException with the given exception as a cause.

CAUTION: if run on old Java 8 (which does not support *minimal* CompletionStage), this method just returns a *normal* CompletableFuture instance which is NOT a *minimal* CompletionStage.

See Also:

• CompletableFuture.minimalCompletionStage()

defaultExecutor

@Contract(pure=true)
public static Executor defaultExecutor(CompletionStage<?> cfThis)

Returns the default Executor of parameter cfThis used for async methods that do not specify an Executor.

The default executor of CompletableFuture(NOT including the customized subclasses of CompletableFuture) uses the ForkJoinPool.commonPool() if it supports more than one parallel thread, or else an Executor using one thread per async task. CAUTION: This executor may be not suitable for common business use(io intensive).

See Also:

• CompletableFuture.defaultExecutor()

unwrapCfException

@Contract(value="null -> null; !null -> !null",
          pure=true)
@Nullable
public static Throwable unwrapCfException(@Nullable
 Throwable ex)

Unwraps CompletableFuture exception (CompletionException or ExecutionException) to its cause exception. If the input exception is not a CompletableFuture/ExecutionException or has no cause, contains a cyclic chain of CompletableFuture exceptions, or is null, returns the input exception.

Parameters:

ex - the exception to be unwrapped may be null

See Also:

• Guava method Throwables#getRootCause(), the loop detection code using fast and slow pointers is adapted from it

nonExSwallowedFunction

@Contract(value="null, _ -> null; !null, _ -> !null",
          pure=true)
@Nullable
public static <X extends Throwable,
T>
Function<X,T> nonExSwallowedFunction(@Nullable
 Function<? super X,? extends T> fn,
 boolean addSuppressedToOriginalEx)

Wraps an exception-handling Function to ensure that if the handling throws a new exception, the error context is preserved by calling Throwable.addSuppressed(java.lang.Throwable).

Example usage with CompletableFuture#exceptionally, CompletableFuture#exceptionallyCompose, CompletableFutureUtils#catching, or CompletableFutureUtils#catching:

 cf.exceptionally(nonExSwallowedFunction(fn, false));
 CompletableFutureUtils.catching(cf, exceptionType, nonExSwallowedFunction(fallback, false));

The methods exceptionally* in CompletableFuture and the methods CompletableFutureUtils#exceptionallyCompose* / catching* in CompletableFutureUtils do not incorporate the nonExSwallowed logic, to maintain consistent and predictable behavior with the standard CompletableFuture. It is recommended to use Cffu which has enhanced exception handling with the nonExSwallowed logic.

For more details on exception swallowing in exception handling methods, see the test cases in ExSwallowingOfExHandlingMethodsTests.

Parameters:

addSuppressedToOriginalEx - if true, the new exception is added as a suppressed exception to the original exception; otherwise, the original exception is added as a suppressed exception to the new exception

See Also:

• Errors should never pass silently. Unless explicitly silenced.

nonExSwallowedBiFunction

@Contract(value="null, _ -> null; !null, _ -> !null",
          pure=true)
@Nullable
public static <T,
X extends Throwable,
U>
BiFunction<T,X,U> nonExSwallowedBiFunction(@Nullable
 BiFunction<? super T,? super X,? extends U> fn,
 boolean addSuppressedToOriginalEx)

Wraps an exception-handling BiFunction to ensure that if the handling throws a new exception, the error context is preserved by calling Throwable.addSuppressed(java.lang.Throwable).

Example usage with CompletableFuture#handle:

cf.handle(nonExSwallowedBiFunction(fn, false));

The methods CompletableFuture#handle* in CompletableFuture do not incorporate the nonExSwallowed logic. It is recommended to use Cffu which has enhanced exception handling with the nonExSwallowed logic.

For more details on exception swallowing in exception handling methods, see the test cases in ExSwallowingOfExHandlingMethodsTests.

Parameters:

addSuppressedToOriginalEx - if true, the new exception is added as a suppressed exception to the original exception; otherwise, the original exception is added as a suppressed exception to the new exception

See Also:

• Errors should never pass silently. Unless explicitly silenced.

nonExSwallowedBiConsumer

@Contract(value="null, _ -> null; !null, _ -> !null",
          pure=true)
@Nullable
public static <T,
X extends Throwable>
BiConsumer<T,X> nonExSwallowedBiConsumer(@Nullable
 BiConsumer<? super T,? super X> action,
 boolean addSuppressedToOriginalEx)

Wraps an exception-handling BiConsumer to ensure that if the handling throws a new exception, the error context is preserved by calling Throwable.addSuppressed(java.lang.Throwable).

Example usage with CompletableFuture#whenComplete:

cf.whenComplete(nonExSwallowedBiConsumer(action, true));

The methods CompletableFuture#whenComplete* in CompletableFuture may not incorporate the nonExSwallowed logic. It is recommended to use Cffu which has enhanced exception handling with the nonExSwallowed logic.

For more details on exception swallowing in exception handling methods, see the test cases in ExSwallowingOfExHandlingMethodsTests.

Parameters:

addSuppressedToOriginalEx - if true, the new exception is added as a suppressed exception to the original exception; otherwise, the original exception is added as a suppressed exception to the new exception

See Also:

• Errors should never pass silently. Unless explicitly silenced.