Interface HandlerInvoker

All Superinterfaces:
HandlerDescriptor
All Known Implementing Classes:
HandlerInspector.MethodHandlerMatcher.MethodHandlerInvoker, HandlerInvoker.DelegatingHandlerInvoker, HandlerInvoker.SimpleInvoker
public interface HandlerInvoker extends HandlerDescriptor
Represents an invocable handler method.

A HandlerInvoker is typically resolved by a Handler for a specific message, and is responsible for invoking the actual handler method, including any surrounding interceptors or decorators.

See Also:

  • Method Details

    • requiresBatchSegmentOrder

      default boolean requiresBatchSegmentOrder()
      Whether asynchronous invocations in one tracked batch must retain the generic message-segment order.

      The default is true. Framework invokers may return false only when they own a stricter ordering mechanism based on the actual state read and written by the invocation.

    • prepareAsyncInvocation

      default Registration prepareAsyncInvocation()
      Registers framework lifecycle state on the dispatching thread before this invocation moves to an asynchronous worker. The returned cleanup runs after invocation or when the worker handoff fails, and must leave lifecycle state that was consumed by the invocation untouched. Cleanup must not throw. The default returns null when no preparation is required. Preparation does not alter invocation-result or result-publication completion; an invoker must express those through its result and the owning publication mechanism.

    • noOp

      static HandlerInvoker noOp()
      Returns a no-op invoker that performs no action and returns null.

    • noOp

      static HandlerInvoker noOp(Class<?> targetClass, Executable method)
      Returns a no-op invoker associated with a handler method. This is useful for synthetic framework invocations that should still expose the user handler's metadata to decorators and interceptors.

    • run

      static HandlerInvoker run(ThrowingRunnable task)
      Wraps a ThrowingRunnable in a HandlerInvoker.
      Parameters:
      task - the task to run
      Returns:
      a HandlerInvoker that runs the given task

    • call

      static HandlerInvoker call(Callable<?> task)
      Wraps a Callable in a HandlerInvoker.
      Parameters:
      task - the task to call
      Returns:
      a HandlerInvoker that invokes the given callable

    • join

      static Optional<HandlerInvoker> join(List<? extends HandlerInvoker> invokers)
      Joins a list of invokers into a single composite invoker. The result of each invocation is combined using the provided combiner function.
      Parameters:
      invokers - a list of invokers to join
      Returns:
      an optional containing the combined invoker, or empty if the list is empty

    • andFinally

      default HandlerInvoker andFinally(HandlerInvoker other)
      Composes this invoker with another to be invoked in a finally block. The second invoker will always run, even if the first one fails.
      Parameters:
      other - the invoker to run after this one
      Returns:
      a combined invoker with finalization behavior

    • getTargetClass

      Class<?> getTargetClass()
      The target class that contains the handler method.
      Specified by:
      getTargetClass in interface HandlerDescriptor
      Returns:
      the declaring class of the handler

    • getMethod

      Executable getMethod()
      The Executable representing the handler method (can be a static or instance Method or Constructor).
      Specified by:
      getMethod in interface HandlerDescriptor
      Returns:
      the executable method

    • getMethodAnnotation

      <A extends Annotation> A getMethodAnnotation()
      Retrieves a specific annotation from the handler method, if present.
      Specified by:
      getMethodAnnotation in interface HandlerDescriptor
      Type Parameters:
      A - the annotation type
      Returns:
      the annotation instance, or null if not found

    • expectResult

      boolean expectResult()
      Indicates whether the handler method has a return value.

      This is based on the method's signature: if it returns void, this returns false; otherwise, it returns true.

      Specified by:
      expectResult in interface HandlerDescriptor
      Returns:
      true if the method returns a value; false if it is void

    • isPassive

      boolean isPassive()
      Indicates whether this handler operates in passive mode (i.e., results will not be published).
      Specified by:
      isPassive in interface HandlerDescriptor
      Returns:
      true if passive; otherwise false

    • wasSkipped

      default boolean wasSkipped()
      Indicates whether this invocation was deliberately skipped after handler selection.
      Returns:
      true if the underlying handler method was not invoked

    • invoke

      default Object invoke()
      Invokes the handler using the default result-combining strategy (returns the first result).
      Returns:
      the result of the handler invocation

    • invoke

      Object invoke(BiFunction<Object,Object,Object> resultCombiner)
      Invokes the handler and combines results using the given combiner function. Used when aggregating results from multiple invokers (e.g. join(List)).
      Parameters:
      resultCombiner - function to combine multiple results
      Returns:
      the combined result