Interface Handler<M>

Type Parameters:
M - the type of messages this handler supports (usually DeserializingMessage)
All Known Implementing Classes:
DefaultHandler, DocumentHandlerDecorator.DocumentHandler, Handler.DelegatingHandler, HandlerInterceptor.InterceptedHandler, HandlerInterceptor.PreparedInterceptedHandler, MutableHandler, SocketEndpointHandler, StatefulHandler
public interface Handler<M>
Represents a container for a message handler and the mechanism to resolve a HandlerInvoker for a given message.

A Handler encapsulates a target class and a provider for an instance of that class. It acts as a factory for HandlerInvoker instances that can be used to invoke the appropriate handler method for a given message.

This abstraction allows support for both stateless and stateful handlers:

  • Stateless: A singleton handler instance is reused for every message (e.g., typical application service).
  • Stateful: The handler instance is dynamically retrieved, e.g., from a repository, based on message content (e.g., aggregates or projections).

A handler may or may not be able to process a given message. If it can, it returns a non-empty Optional containing a HandlerInvoker; otherwise, it returns Optional.empty().

Handler Architecture

┌────────────────────┐
│  HandlerInspector  │
└────────┬───────────┘
         │ inspects target class
         ▼
┌────────────────────┐        creates        ┌──────────────────────┐
│  HandlerMatcher    │──────────────────────▶│     HandlerInvoker   │
└────────┬───────────┘                       └──────────────────────┘
         │ produces invoker if message
         │ matches a method
         ▼
┌────────────────────┐
│      Handler       │◀───────────── target instance
└────────────────────┘
See Also:

  • Method Details

    • getTargetClass

      Class<?> getTargetClass()
      Returns the class of the handler's target object. This may be used for reflective operations, logging, or framework-level behavior.
      Returns:
      the class of the handler's target

    • getInvoker

      Optional<HandlerInvoker> getInvoker(M message)
      Returns a HandlerInvoker capable of processing the given message, if available.
      Parameters:
      message - the message to be handled
      Returns:
      an optional HandlerInvoker if this handler can handle the message; otherwise Optional.empty()

    • getInvokerOrNull

      default HandlerInvoker getInvokerOrNull(M message)
      Returns a HandlerInvoker capable of processing the given message, or null when unavailable.

      This is a lower-allocation counterpart to getInvoker(Object) for internal hot paths. Implementations that can resolve an invoker without creating an Optional should override this method.

      Parameters:
      message - the message to be handled
      Returns:
      an invoker if this handler can handle the message; null otherwise

    • getHandlerMethodOrNull

      default HandlerMethod<M> getHandlerMethodOrNull(M message)
      Returns a reusable HandlerMethod capable of processing the given message, or null when unavailable.

      This is an optional lower-allocation path for handlers whose target and method plan can be reused across messages. Implementations that cannot expose a stable method should return null and rely on getInvokerOrNull(Object).

      Parameters:
      message - the message to be handled
      Returns:
      a handler method if this handler can handle the message through a reusable method; null otherwise

    • getHandlerMethodPlanOrNull

      default HandlerMethodPlan<M> getHandlerMethodPlanOrNull(M message)
      Returns a reusable plan for the handler method selected for this message.

      The default asks getHandlerMethodPlanner() to prepare the plan. A null result means that this handler cannot safely prepare the invocation, so the caller should use getInvokerOrNull(Object) or getHandlerMethodOrNull(Object) instead.

      Parameters:
      message - the message to match
      Returns:
      the prepared invocation plan, or null when preparation is unsupported or no method matches

    • getHandlerMethodPlanner

      default HandlerMethodPlanner<M> getHandlerMethodPlanner()
      Returns the planner used to select and prepare this handler's methods.

      The returned planner may be cached and invoked concurrently. The default returns null, which keeps implementations that only support regular per-message matching fully compatible.

      Returns:
      a thread-safe handler method planner, or null when this handler does not support preparation

    • or

      default Handler<M> or(Handler<M> next)
      Creates a composite handler that executes the current handler and then delegates to the specified next handler if the current handler cannot handle the message or does not provide an invoker.
      Parameters:
      next - the next handler to be invoked if this handler does not handle the message
      Returns:
      a new handler combining the current handler and the specified next handler