Package io.foldright.cffu

Class CompletableFutureUtils

java.lang.Object
io.foldright.cffu.CompletableFutureUtils
@ParametersAreNonnullByDefault @ReturnValuesAreNonnullByDefault public final class CompletableFutureUtils extends Object
This class contains the enhanced methods for CompletableFuture.
Author:
Jerry Lee (oldratlee at gmail dot com)

  • Method Details

    • allOfWithResult

      @Contract(pure=true) @SafeVarargs public static <T> CompletableFuture<List<T>> allOfWithResult(CompletableFuture<T>... cfs)
      Returns a new CompletableFuture with the results of all the given CompletableFutures, the new CompletableFuture is completed when all the given CompletableFutures complete. If any of the given CompletableFutures complete exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause. If no CompletableFutures are provided, returns a CompletableFuture completed with the value emptyList.

      Same to CompletableFuture.allOf(CompletableFuture[]), but the returned CompletableFuture contains the results of the given CompletableFutures.

      Parameters:
      cfs - the CompletableFutures
      Returns:
      a new CompletableFuture that is completed when all the given CompletableFutures complete
      Throws:
      NullPointerException - if the array or any of its elements are null
      See Also:

    • allOfFastFail

      @Contract(pure=true) public static CompletableFuture<Void> allOfFastFail(CompletableFuture<?>... cfs)
      Returns a new CompletableFuture that success when all the given CompletableFutures success, the results(CompletableFuture<Void>) of the given CompletableFutures are not reflected in the returned CompletableFuture, but may be obtained by inspecting them individually. If any of the given CompletableFutures complete exceptionally, then the returned CompletableFuture also does so *without* waiting other incomplete given CompletableFutures, with a CompletionException holding this exception as its cause. If no CompletableFutures are provided, returns a CompletableFuture completed with the value null.
      Parameters:
      cfs - the CompletableFutures
      Returns:
      a new CompletableFuture that success when all the given CompletableFutures success
      Throws:
      NullPointerException - if the array or any of its elements are null
      See Also:

    • allOfFastFailWithResult

      @Contract(pure=true) @SafeVarargs public static <T> CompletableFuture<List<T>> allOfFastFailWithResult(CompletableFuture<T>... cfs)
      Returns a new CompletableFuture with the results of all the given CompletableFutures, the new CompletableFuture success when all the given CompletableFutures success. If any of the given CompletableFutures complete exceptionally, then the returned CompletableFuture also does so *without* waiting other incomplete given CompletableFutures, with a CompletionException holding this exception as its cause. If no CompletableFutures are provided, returns a CompletableFuture completed with the value emptyList.

      Same to allOfFastFail(CompletableFuture[]), but the returned CompletableFuture contains the results of the given CompletableFutures.

      Parameters:
      cfs - the CompletableFutures
      Returns:
      a new CompletableFuture that success when all the given CompletableFutures success
      Throws:
      NullPointerException - if the array or any of its elements are null
      See Also:

    • anyOfWithType

      @Contract(pure=true) @SafeVarargs public static <T> CompletableFuture<T> anyOfWithType(CompletableFuture<T>... cfs)
      Returns a new CompletableFuture that is completed when any of the given CompletableFutures 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 CompletableFutures are provided, returns an incomplete CompletableFuture.

      Same as CompletableFuture.anyOf(CompletableFuture[]), but return result type is specified type instead of Object.

      Parameters:
      cfs - the CompletableFutures
      Returns:
      a new CompletableFuture that is completed with the result or exception from any of the given CompletableFutures when one completes
      Throws:
      NullPointerException - if the array or any of its elements are null
      See Also:

    • anyOfSuccess

      @Contract(pure=true) public static CompletableFuture<Object> anyOfSuccess(CompletableFuture<?>... cfs)
      Returns a new CompletableFuture that success when any of the given CompletableFutures success, with the same result. Otherwise, all the given CompletableFutures complete exceptionally, the returned CompletableFuture also does so, with a CompletionException holding an exception from any of the given CompletableFutures as its cause. If no CompletableFutures are provided, returns a new CompletableFuture that is already completed exceptionally with a CompletionException holding a NoCfsProvidedException as its cause.
      Parameters:
      cfs - the CompletableFutures
      Returns:
      a new CompletableFuture that success when any of the given CompletableFutures success, with the same result
      Throws:
      NullPointerException - if the array or any of its elements are null
      See Also:

    • anyOfSuccessWithType

      @Contract(pure=true) @SafeVarargs public static <T> CompletableFuture<T> anyOfSuccessWithType(CompletableFuture<T>... cfs)
      Returns a new CompletableFuture that success when any of the given CompletableFutures success, with the same result. Otherwise, all the given CompletableFutures complete exceptionally, the returned CompletableFuture also does so, with a CompletionException holding an exception from any of the given CompletableFutures as its cause. If no CompletableFutures are provided, returns a new CompletableFuture that is already completed exceptionally with a CompletionException holding a NoCfsProvidedException as its cause.

      Same as anyOfSuccess(CompletableFuture[]), but return result type is specified type instead of Object.

      Parameters:
      cfs - the CompletableFutures
      Returns:
      a new CompletableFuture that success when any of the given CompletableFutures success, with the same result
      Throws:
      NullPointerException - if the array or any of its elements are null
      See Also:

    • combine

      @Contract(pure=true) public static <T1, T2> CompletableFuture<Tuple2<T1,T2>> combine(CompletableFuture<T1> cf1, CompletableFuture<T2> cf2)
      Returns a new CompletableFuture that is completed when the given two CompletableFutures complete. If any of the given CompletableFutures complete exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause.
      Returns:
      a new CompletableFuture that is completed when the given 2 CompletableFutures complete
      Throws:
      NullPointerException - if any of the given CompletableFutures are null
      See Also:

    • combine

      @Contract(pure=true) public static <T1, T2, T3> CompletableFuture<Tuple3<T1,T2,T3>> combine(CompletableFuture<T1> cf1, CompletableFuture<T2> cf2, CompletableFuture<T3> cf3)
      Returns a new CompletableFuture that is completed when the given three CompletableFutures complete. If any of the given CompletableFutures complete exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause.
      Returns:
      a new CompletableFuture that is completed when the given 3 CompletableFutures complete
      Throws:
      NullPointerException - if any of the given CompletableFutures are null
      See Also:

    • combine

      @Contract(pure=true) public static <T1, T2, T3, T4> CompletableFuture<Tuple4<T1,T2,T3,T4>> combine(CompletableFuture<T1> cf1, CompletableFuture<T2> cf2, CompletableFuture<T3> cf3, CompletableFuture<T4> cf4)
      Returns a new CompletableFuture that is completed when the given 4 CompletableFutures complete. If any of the given CompletableFutures complete exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause.
      Returns:
      a new CompletableFuture that is completed when the given 4 CompletableFutures complete
      Throws:
      NullPointerException - if any of the given CompletableFutures are null
      See Also:

    • combine

      @Contract(pure=true) public static <T1, T2, T3, T4, T5> CompletableFuture<Tuple5<T1,T2,T3,T4,T5>> combine(CompletableFuture<T1> cf1, CompletableFuture<T2> cf2, CompletableFuture<T3> cf3, CompletableFuture<T4> cf4, CompletableFuture<T5> cf5)
      Returns a new CompletableFuture that is completed when the given 5 CompletableFutures complete. If any of the given CompletableFutures complete exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause.
      Returns:
      a new CompletableFuture that is completed when the given 5 CompletableFutures complete
      Throws:
      NullPointerException - if any of the given CompletableFutures are null
      See Also:

    • 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.
      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.
      Type Parameters:
      T - the type of the value
      Parameters:
      ex - the exception
      Returns:
      the exceptionally completed CompletionStage

    • 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

    • exceptionallyAsync

      public static <T> CompletableFuture<T> exceptionallyAsync(CompletableFuture<T> cf, Function<Throwable,? extends T> fn)
      Returns a new CompletionStage that, when given stage completes exceptionally, is executed with given stage's exception as the argument to the supplied function, using given stage's default asynchronous execution facility. Otherwise, if given stage completes normally, then the returned stage also completes normally with the same value.
      Parameters:
      fn - the function to use to compute the value of the returned CompletionStage if given CompletionStage completed exceptionally
      Returns:
      the new CompletionStage

    • exceptionallyAsync

      public static <T> CompletableFuture<T> exceptionallyAsync(CompletableFuture<T> cf, Function<Throwable,? extends T> fn, Executor executor)
      Returns a new CompletionStage that, when given stage completes exceptionally, is executed with given stage's exception as the argument to the supplied function, using the supplied Executor. Otherwise, if given stage completes normally, then the returned stage also completes normally with the same value.
      Parameters:
      fn - the function to use to compute the value of the returned CompletionStage if given CompletionStage completed exceptionally
      executor - the executor to use for asynchronous execution
      Returns:
      the new CompletionStage

    • orTimeout

      public static <T> CompletableFuture<T> orTimeout(CompletableFuture<T> cf, long timeout, TimeUnit unit)
      Exceptionally completes given CompletableFuture with a TimeoutException if not otherwise completed before the given timeout.
      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:
      given CompletableFuture

    • completeOnTimeout

      public static <T> CompletableFuture<T> completeOnTimeout(CompletableFuture<T> cf, @Nullable T value, long timeout, TimeUnit unit)
      Completes given CompletableFuture with the given value if not otherwise completed before the given timeout.
      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:
      given CompletableFuture

    • exceptionallyCompose

      public static <T> CompletableFuture<T> exceptionallyCompose(CompletableFuture<T> cf, Function<Throwable,? extends CompletionStage<T>> fn)
      Returns a new CompletionStage that, when given stage completes exceptionally, is composed using the results of the supplied function applied to given stage's exception.
      Parameters:
      fn - the function to use to compute the returned CompletionStage if given CompletionStage completed exceptionally
      Returns:
      the new CompletionStage

    • exceptionallyComposeAsync

      public static <T> CompletableFuture<T> exceptionallyComposeAsync(CompletableFuture<T> cf, Function<Throwable,? extends CompletionStage<T>> fn)
      Returns a new CompletionStage that, when given stage completes exceptionally, is composed using the results of the supplied function applied to given stage's exception, using given stage's default asynchronous execution facility.
      Parameters:
      fn - the function to use to compute the returned CompletionStage if given CompletionStage completed exceptionally
      Returns:
      the new CompletionStage

    • exceptionallyComposeAsync

      public static <T> CompletableFuture<T> exceptionallyComposeAsync(CompletableFuture<T> cf, Function<Throwable,? extends CompletionStage<T>> fn, Executor executor)
      Returns a new CompletionStage that, when given stage completes exceptionally, is composed using the results of the supplied function applied to given stage's exception, using the supplied Executor.
      Parameters:
      fn - the function to use to compute the returned CompletionStage if given CompletionStage completed exceptionally
      executor - the executor to use for asynchronous execution
      Returns:
      the new CompletionStage

    • cffuJoin

      @Blocking @Nullable public static <T> T cffuJoin(CompletableFuture<T> cf, 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.

      NOTE:
       call this method

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

      is same as: 

      result = cf.copy() // defensive copy to avoid writing this cf unexpectedly
     .orTimeout(timeout, unit)
     .join();
      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).
      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:

    • resultNow

      @Contract(pure=true) @Nullable public static <T> T resultNow(CompletableFuture<T> cf)
      Returns the computed result, without waiting.

      This method is for cases where the caller knows that the task has already completed successfully, 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();

    • exceptionNow

      @Contract(pure=true) public static <T> Throwable exceptionNow(CompletableFuture<T> cf)
      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
      See Also:

    • cffuState

      @Contract(pure=true) public static <T> CffuState cffuState(CompletableFuture<T> cf)
      Returns the computation state(CffuState), this method has java version compatibility logic, so you can invoke in old java 18-.
      Returns:
      the computation state
      See Also:

    • completeAsync

      public static <T> CompletableFuture<T> completeAsync(CompletableFuture<T> cf, Supplier<? extends T> supplier)
      Completes given CompletableFuture with the result of the given Supplier function invoked from an asynchronous task using the default executor.
      Parameters:
      supplier - a function returning the value to be used to complete given CompletableFuture
      Returns:
      given CompletableFuture

    • completeAsync

      public static <T> CompletableFuture<T> completeAsync(CompletableFuture<T> cf, 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 given CompletableFuture
      executor - the executor to use for asynchronous execution
      Returns:
      given CompletableFuture

    • minimalCompletionStage

      @Contract(pure=true) public static <T> CompletionStage<T> minimalCompletionStage(CompletableFuture<T> cf)
      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 given CompletableFuture completes exceptionally, then the returned CompletionStage completes exceptionally with a CompletionException with given exception as cause. 
      minimalStage.toCompletableFuture().join();
      Returns:
      the new CompletionStage

    • copy

      @Contract(pure=true) public static <T> CompletableFuture<T> copy(CompletableFuture<T> cf)
      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.
      Returns:
      the new CompletableFuture

    • newIncompleteFuture

      @Contract(pure=true) public static <T, U> CompletableFuture<U> newIncompleteFuture(CompletableFuture<T> cf)
      Returns a new incomplete CompletableFuture of the type to be returned by a CompletionStage method.
      Type Parameters:
      T - the type of the value
      Returns:
      a new CompletableFuture

    • defaultExecutor

      @Contract(pure=true) public static Executor defaultExecutor()
      Returns the default Executor used for async methods that do not specify an Executor. This class uses the ForkJoinPool.commonPool() if it supports more than one parallel thread, or else an Executor using one thread per async task.
      Returns:
      the executor