Package org.axonframework.common

Class FutureUtils

java.lang.Object
org.axonframework.common.FutureUtils
public final class FutureUtils extends Object
Utility class containing reusable functionality for interacting with the CompletableFuture.
Since:
5.0.0
Author:
Allard Buijze

  • Method Details

    • ignoreResult

      public static <T> Void ignoreResult(T toIgnore)
      Utility method that doesn't do anything. Its purpose is to simplify conversion of a CompletableFuture with any generic type to a CompletableFuture<Void>.

      Example: completableFuture.thenApply(FutureUtils::ignoreResult

      Type Parameters:
      T - The declared result of the CompletableFuture to ignore the result of.
      Parameters:
      toIgnore - The actual result of the CompletableFuture.
      Returns:
      null, as that's the only valid value for Void.

    • emptyCompletedFuture

      public static <T> CompletableFuture<T> emptyCompletedFuture()
      Creates a completed CompletableFuture with null as result.
      Type Parameters:
      T - The declared type to return in the CompletableFuture.
      Returns:
      A CompletableFuture that is completed with null.

    • allOrEmpty

      public static CompletableFuture<Void> allOrEmpty(List<CompletableFuture<Void>> futures)
      Combines the given futures into a single CompletableFuture that completes once all of them complete, returning an already completed future when futures is empty.

      This is a drop-in alternative to CompletableFuture.allOf(CompletableFuture[]) for code paths that routinely deal with empty collections, such as fan-out over a dynamic set of handlers, subscribers, or segments. It avoids allocating an array and a dependent future for a combination that has nothing to wait for.

      The returned future completes exceptionally with a CompletionException as soon as any of the given futures completes exceptionally, matching the behavior of CompletableFuture.allOf(CompletableFuture[]).

      Parameters:
      futures - the futures to combine
      Returns:
      a future that completes once every future in futures completes, or a completed future if futures is empty
      Since:
      5.3.0

    • alsoComplete

      public static <T> BiConsumer<T,Throwable> alsoComplete(CompletableFuture<T> future)
      Creates a function that can be passed to a CompletableFuture.whenComplete(BiConsumer) or CompletableFuture.whenCompleteAsync(BiConsumer) invocation, to complete the given future with the same result as the CompletableFuture that this function is passed to.
      Type Parameters:
      T - The declared type of result from the CompletableFuture.
      Parameters:
      future - The CompletableFuture to also complete.
      Returns:
      A function that completes another future with the same results.

    • unwrap

      public static Throwable unwrap(Throwable exception)
      Unwrap given exception from the exception-wrappers added by CompletableFuture.

      More specifically, if the given exception is a CompletionException or ExecutionException, it returns the cause. Otherwise, it will return the exception as-is.

      Parameters:
      exception - The exception to unwrap.
      Returns:
      The unwrapped exception if the given exception is of type CompletionException or ExecutionException. Otherwise, it is returned as is.

    • runFailing

      public static <T> CompletableFuture<T> runFailing(Supplier<CompletableFuture<T>> fn)
      Safely catches exceptions thrown by the given fn and returns a CompletableFuture that completes.
      Type Parameters:
      T - Type of the completable future.
      Parameters:
      fn - A lambda returning a CompletableFuture.
      Returns:
      A completable future that completes exceptionally if the given lambda throws an exception.

    • joinAndUnwrap

      public static <T> @Nullable T joinAndUnwrap(CompletableFuture<T> future)
      Joins a CompletableFuture and unwraps any CompletionException to throw the actual cause, preserving the exact exception type without wrapping checked exceptions.

      Applies a default safety-net timeout of 30 seconds. If the future does not complete within that window, a TimeoutException is thrown. Callers that expect longer completion times should use joinAndUnwrap(CompletableFuture, Duration) with an explicit timeout.

      Type Parameters:
      T - The type of the future's result.
      Parameters:
      future - The CompletableFuture to join.
      Returns:
      The result of the future.
      Throws:
      TimeoutException - if the future does not complete within the default timeout.
      Throwable - the unwrapped cause if the future completed exceptionally (exact type preserved).

    • joinAndUnwrap

      public static <T> T joinAndUnwrap(CompletableFuture<T> future, Duration timeout)
      Joins a CompletableFuture and unwraps any CompletionException to throw the actual cause, preserving the exact exception type without wrapping checked exceptions. If the future does not complete within the given timeout, a TimeoutException is thrown.

      This method uses CompletableFuture.orTimeout(long, TimeUnit) to enforce the deadline. On futures that are already complete (the common case), the timeout is a no-op.

      Type Parameters:
      T - The type of the future's result.
      Parameters:
      future - The CompletableFuture to join.
      timeout - The maximum time to wait for the future to complete.
      Returns:
      The result of the future, or null if the future completed with a null value.
      Throws:
      TimeoutException - if the future does not complete within the given timeout.
      Throwable - the unwrapped cause if the future completed exceptionally (exact type preserved).