Class Invocation

java.lang.Object
io.fluxzero.sdk.tracking.handling.Invocation
public class Invocation extends Object
Tracks the lifecycle and identity of a single message handler invocation.

This class enables consistent tagging and correlation of all side effects (e.g. metrics, queries, event sourcing, message publication) produced during the execution of a handler. Each invocation is assigned a unique invocation ID. When available, it also keeps track of the active handler class so metadata and logging contexts can trace functional and non-functional effects back to the triggering handler.

Automatic Invocation Wrapping

The Fluxzero client automatically wraps all handler invocations using this class. This includes:
  • Local handlers (i.e. message handling in the publishing thread)
  • Tracked handlers (i.e. message tracking via the Fluxzero Runtime)

As a result, developers typically do not need to call performInvocation(Callable) directly, unless they are manually invoking a handler outside of the Fluxzero infrastructure.

Usage

When used manually, wrap handler logic with performInvocation(Callable) to activate an invocation context: 
Invocation.performInvocation(() -> {
    // handler logic
    Fluxzero.publishEvent(new SomeEvent());
    return result;
});

This ensures:

  • A consistent invocation ID is available throughout the thread
  • Any emitted messages, metrics, or queries can include that ID as a correlation token
  • Callbacks can be registered via whenHandlerCompletes(BiConsumer) to react to success/failure
See Also:

  • Method Details

    • performInvocation

      public static <V> V performInvocation(Callable<V> callable)
      Wraps the given Callable in an invocation context.

      This method ensures that callbacks registered via whenHandlerCompletes(BiConsumer) are executed upon completion of the callable.

      Parameters:
      callable - the task to run
      Returns:
      the callable result

    • performInvocation

      public static <V> V performInvocation(io.fluxzero.common.handling.HandlerInvoker handlerInvoker, Callable<V> callable)
      Wraps the given Callable in an invocation context for the supplied handler.
      Parameters:
      handlerInvoker - the handler that is being invoked
      callable - the task to run
      Returns:
      the callable result

    • performInvocation

      public static <V> V performInvocation(io.fluxzero.common.handling.HandlerDescriptor handlerDescriptor, Callable<V> callable)
      Wraps the given Callable in an invocation context for the supplied handler descriptor.
      Parameters:
      handlerDescriptor - the handler that is being invoked
      callable - the task to run
      Returns:
      the callable result

    • performInvocation

      public static <M> Object performInvocation(io.fluxzero.common.handling.HandlerMethod<? super M> handlerMethod, M message)
      Invokes the supplied reusable handler method inside an invocation context without allocating a per-message Callable adapter.
      Type Parameters:
      M - the message type
      Parameters:
      handlerMethod - the handler method that is being invoked
      message - the message to handle
      Returns:
      the handler result

    • getId

      public String getId()
      Returns this invocation's technical identifier, generating and retaining it on first access.

    • getCurrent

      public static Invocation getCurrent()
      Returns the current Invocation bound to this thread, or null if none exists.

    • observeDeferredResult

      public static CompletableFuture<Void> observeDeferredResult(CompletableFuture<Object> completion, Runnable progress)
      Transfers a deferred automatic handler result to the active tracking invocation, if it observes results. The returned completion represents error handling, not durability; dependencies must keep using the original completion. Local/manual invocations return null and retain their existing completion contract.
      Parameters:
      completion - original deferred handler result
      progress - releases deferred work when an error handler explicitly retries this invocation
      Returns:
      completion owned by tracking, or null when no observer is active

    • whenHandlerCompletes

      public static io.fluxzero.common.Registration whenHandlerCompletes(BiConsumer<Object, Throwable> callback)
      Registers a callback to be executed when the current handler invocation completes.

      If no invocation is active, the callback is executed immediately with null values.

      Parameters:
      callback - the handler result/error consumer
      Returns:
      a Registration handle to cancel the callback

    • awaitBeforeResultPublication

      public static void awaitBeforeResultPublication(CompletableFuture<?> completion)
      Registers asynchronous work that must complete before the current handler result is published.

      This method is intended for handler-completion callbacks, such as aggregate commit policies that start work after the handler returned but still want request results to reflect the committed state.

      Parameters:
      completion - completion to await before result publication; null is ignored

    • awaitBeforeResultPublication

      public static void awaitBeforeResultPublication(DeserializingMessage message, CompletableFuture<?> completion)
      Registers asynchronous work that must complete before the supplied message's handler result is published.
      Parameters:
      message - message whose result should wait for the completion
      completion - completion to await before result publication; null is ignored

    • resultPublicationBarrier

      public static CompletableFuture<Void> resultPublicationBarrier(DeserializingMessage message)
      Returns the barrier that must complete before the supplied message's handler result is published.
      Parameters:
      message - message whose result publication barrier should be resolved
      Returns:
      completion future, or an already completed future when no post-handler work was registered