Package dev.tachyonmcp.api.server.features

Class HandlerFutures

java.lang.Object

dev.tachyonmcp.api.server.features.HandlerFutures

@InternalApi
public final class HandlerFutures
extends Object

Static utilities for common CompletionStage patterns.

Method Summary

Modifier and Type	Method	Description
static void	assumeVirtualThread()
static <R> CompletionStage<R>	completedOrFailed(Callable<? extends R> handler)	Adapts a synchronous handler body into a CompletionStage: a completed stage on success, a failed one carrying the thrown exception otherwise.
static <T, R> CompletionStage<R>	completeOn(CompletionStage<T> stage, Executor executor, BiFunction<? super T,Throwable,? extends R> fn)	Applies fn to the outcome of stage.
static <R> CompletionStage<Object>	invokeAndMap(String nullStageMessage, Callable<? extends @Nullable CompletionStage<? extends R>> invocation, Executor executor, BiFunction<? super R,@Nullable Throwable,@Nullable Object> resultMapper)	Invokes a handler, guards against a synchronous throw or a null returned stage, and maps the outcome via completeOn(java.util.concurrent.CompletionStage<T>, java.util.concurrent.Executor, java.util.function.BiFunction<? super T, java.lang.Throwable, ? extends R>).
static <T> T	joinInterruptibly(CompletionStage<T> stage)	Joins a CompletionStage via blocking .get(), restoring interrupt and unwrapping ExecutionException.
static Throwable	unwrap(Throwable throwable)	Unwraps a single level of CompletionException, returning the original cause when present.

Methods inherited from class java.lang.Object

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

Method Details

assumeVirtualThread

public static void assumeVirtualThread()

joinInterruptibly

public static <T> T joinInterruptibly(CompletionStage<T> stage)
                               throws Exception

Joins a CompletionStage via blocking .get(), restoring interrupt and unwrapping ExecutionException. For use on virtual threads where blocking is expected.

Type Parameters:

T - the result type

Parameters:

stage - the stage to join

Returns:

the result of the stage

Throws:

Exception - if the stage completed exceptionally

unwrap

public static Throwable unwrap(Throwable throwable)

Unwraps a single level of CompletionException, returning the original cause when present. Mirrors the unwrap a CompletionStage callback receives after an async hop.

Parameters:

throwable - the throwable to unwrap

Returns:

the original cause, or throwable itself if not a CompletionException

completeOn

public static <T,
R> CompletionStage<R> completeOn(CompletionStage<T> stage,
 Executor executor,
 BiFunction<? super T,Throwable,? extends R> fn)

Applies fn to the outcome of stage. Runs inline on the calling thread when the stage is already complete (the common case: sync handlers, already-resolved async ones) to avoid an unconditional executor hop; otherwise schedules fn on executor so a handler completing from a foreign thread doesn't leak that thread into response mapping.

Type Parameters:

T - the input result type

R - the output result type

Parameters:

stage - the stage whose outcome to map

executor - the executor for async completion

fn - the mapping function

Returns:

a new stage with the mapped result

completedOrFailed

public static <R> CompletionStage<R> completedOrFailed(Callable<? extends R> handler)

Adapts a synchronous handler body into a CompletionStage: a completed stage on success, a failed one carrying the thrown exception otherwise. Shared by the sync-handler internal adapters from synchronous feature functions.

Type Parameters:

R - the result type

Parameters:

handler - the synchronous handler body

Returns:

a completed or failed stage

invokeAndMap

public static <R> CompletionStage<Object> invokeAndMap(String nullStageMessage,
 Callable<? extends @Nullable CompletionStage<? extends R>> invocation,
 Executor executor,
 BiFunction<? super R,@Nullable Throwable,@Nullable Object> resultMapper)

Invokes a handler, guards against a synchronous throw or a null returned stage, and maps the outcome via completeOn(java.util.concurrent.CompletionStage<T>, java.util.concurrent.Executor, java.util.function.BiFunction<? super T, java.lang.Throwable, ? extends R>). Shared registry-dispatch skeleton: obtain the handler's stage safely, then compose the result without blocking. The mapper receives the failure cause already unwrapped (or null on success).

Type Parameters:

R - the handler result type

Parameters:

nullStageMessage - message for the NPE if invocation returns null

invocation - the handler invocation

executor - the executor for async completion

resultMapper - maps result or failure to the dispatch outcome

Returns:

a stage with the mapped result