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()

    • getCurrent

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

    • 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