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, 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

    • 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