Package org.ores.async

Class WrapFuture

java.lang.Object
org.ores.async.WrapFuture
public final class WrapFuture extends Object
Bridge between async.java's error-first callback shape and the JDK's promise primitive (CompletableFuture / CompletionStage).

Three adapters cover the common interop directions:

  • toFuture(Consumer) — async.java callback → CompletableFuture. Wrap a combinator invocation in a future at the boundary where you need to return a promise to a framework (Spring WebFlux, Akka HTTP, gRPC stub).
  • fromStage(CompletionStage) — CompletionStage → async.java Asyncc.AsyncTask. Useful when consuming a third-party promise-returning API (a JDBC async driver, an HTTP client) inside an async.java combinator.
  • fromCallable(Executor, Callable) — wrap a sync, possibly-blocking Callable as an async.java task, dispatching it onto the provided executor.

The toFuture idiom

The setup consumer receives an Asyncc.IAsyncCallback that is wired to complete the future. You can pass it directly as the final callback of any combinator: 

   CompletableFuture<List<String>> handle(Request req) {
       return WrapFuture.toFuture(c ->
           Asyncc.Parallel(List.of(
               cb -> exec.submit(() -> cb.success(fetchA(req))),
               cb -> exec.submit(() -> cb.success(fetchB(req)))
           ), c)
       );
   }

The callback c is fired exactly once by the combinator. If err != null, the future completes exceptionally (wrapping non-Throwable errors in a RuntimeException); otherwise it completes with the value.

The fromStage idiom

Wrap a third-party CompletionStage as an async.java task you can drop into any combinator's task position: 

   Asyncc.Parallel(List.of(
       WrapFuture.fromStage(db.queryAsync("SELECT ...")),
       WrapFuture.fromStage(redis.getAsync(key)),
       WrapFuture.fromStage(httpClient.sendAsync(req).thenApply(HttpResponse::body))
   ), (err, results) -> { /* ... */ });

Static-import convention

Pair with WrapErrFirst as a static import: 

   import static org.ores.async.WrapErrFirst.wrap;
   import static org.ores.async.WrapFuture.toFuture;
   import static org.ores.async.WrapFuture.fromStage;
Since:
0.2.7

  • Method Details

    • toFuture

      public static <V> CompletableFuture<V> toFuture(Consumer<Asyncc.IAsyncCallback<V,Throwable>> setup)
      Adapt an async.java combinator invocation into a CompletableFuture.

      The setup consumer is invoked synchronously with a callback that, when fired, completes the returned future. Pass this callback directly to any combinator as its final callback — the future then mirrors the combinator's outcome.

      Error type is fixed to Throwable (the natural match for CompletableFuture's completeExceptionally(Throwable)). For async.java combinators that use a non-Throwable error type, see toFutureAny(Consumer).

      Synchronous failure: if setup.accept(...) itself throws, the future completes exceptionally with that throwable.

      Usage

         CompletableFuture<List<String>> result = WrapFuture.toFuture(c ->
       Asyncc.<String, Throwable>Parallel(tasks, c)
   );
      Type Parameters:
      V - value type produced by the combinator
      Parameters:
      setup - a consumer that wires the supplied callback into a combinator
      Returns:
      a CompletableFuture that completes when the combinator's final callback fires

    • toFutureAny

      public static <V, E> CompletableFuture<V> toFutureAny(Consumer<Asyncc.IAsyncCallback<V,E>> setup)
      Generic-error-type variant of toFuture(Consumer). Use this when the underlying async.java combinator's error type is something other than Throwable (e.g. Object or a domain-specific error tag). Non-Throwable errors are wrapped in a RuntimeException for the future's exceptional completion.

      Most callers don't need this; prefer toFuture(Consumer).

      Type Parameters:
      V - value type
      E - error type
      Parameters:
      setup - a consumer that wires the supplied callback into a combinator

    • fromStage

      public static <V> Asyncc.AsyncTask<V,Throwable> fromStage(CompletionStage<V> stage)
      Adapt a CompletionStage to an async.java Asyncc.AsyncTask.

      The returned task, when invoked by a combinator, attaches a whenComplete handler to the stage that fires the combinator's per-task callback. Successful completion calls callback.success(value); exceptional completion calls callback.fail(err).

      The same stage instance can only be consumed by one task (a stage is a one-shot primitive). If you need to consume the same logical work from multiple combinator task positions, wrap each in its own Supplier.

      Type Parameters:
      V - value type produced by the stage
      Parameters:
      stage - a one-shot promise-shaped value
      Returns:
      an async.java task suitable for any combinator that accepts AsyncTask<V, Throwable>

    • fromCallable

      public static <V> Asyncc.AsyncTask<V,Throwable> fromCallable(Executor exec, Callable<V> callable)
      Adapt a synchronous (possibly blocking) Callable to an async.java task by dispatching it onto the provided executor.

      Equivalent to fromStage(CompletableFuture.supplyAsync(callable::call, exec)) but preserves checked exceptions from the callable's call() method as the failure.

      Type Parameters:
      V - value type produced by the callable
      Parameters:
      exec - executor to run the callable on
      callable - the synchronous work to perform
      Returns:
      an async.java task