Interface HandlerMatcher<T,M>

Type Parameters:
T - the type of the handler instance
M - the type of the message
All Known Implementing Classes:
HandlerInspector.MethodHandlerMatcher, HandlerInspector.ObjectHandlerMatcher, WebHandlerMatcher
public interface HandlerMatcher<T,M>
Defines the logic to determine whether a given target object can handle a message, and how to invoke it.

A HandlerMatcher is a stateless strategy that inspects a target object and a message to:

Unlike a Handler, a HandlerMatcher does not resolve or manage instances. It simply inspects a provided target instance and message to resolve possible invocations.

See Also:

  • Method Details

    • canHandle

      boolean canHandle(M message)
      Returns whether the given message can be handled by a handler instance of type T. This is a lightweight check and may be used for fast filtering or diagnostics.
      Parameters:
      message - the message to check
      Returns:
      true if the matcher may be able to produce an invoker for the given message

    • matchingMethods

      Stream<Executable> matchingMethods(M message)
      Returns a stream of methods from the target class that match the given message. Typically used for diagnostics or documentation tools.
      Parameters:
      message - the message to match against
      Returns:
      a stream of matching Executable handler methods

    • getInvoker

      Optional<HandlerInvoker> getInvoker(T target, M message)
      Attempts to resolve a HandlerInvoker for the given target instance and message.
      Parameters:
      target - the handler object
      message - the message to be handled
      Returns:
      an optional invoker if the message is supported by the target; empty otherwise

    • getInvokerOrNull

      default HandlerInvoker getInvokerOrNull(T target, M message)
      Attempts to resolve a HandlerInvoker for the given target instance and message.

      This is a lower-allocation counterpart to getInvoker(Object, Object) for internal hot paths.

      Parameters:
      target - the handler object
      message - the message to be handled
      Returns:
      an invoker if the message is supported by the target; null otherwise

    • bindHandlerMethod

      default HandlerMethod<M> bindHandlerMethod(T target)
      Binds this matcher to a stable target instance, if it can expose a reusable method plan.

      Most matcher implementations may return null. Returning a method is only appropriate when the method metadata and target are stable for all matching messages.

      Parameters:
      target - the handler object
      Returns:
      a reusable handler method, or null when the matcher requires per-message invokers

    • prepareHandlerMethod

      default HandlerMethodPlan<M> prepareHandlerMethod(T target, M message)
      Selects and prepares a handler method on the supplied target for the given message.

      The default uses bindHandlerMethodPlanner(Object) when available. Returning null does not reject the message; it tells the caller to use regular per-message matching instead.

      Parameters:
      target - the object that contains the handler method
      message - the representative message
      Returns:
      the reusable invocation plan, or null when no method matches or safe preparation is unsupported

    • bindHandlerMethodPlanner

      default HandlerMethodPlanner<M> bindHandlerMethodPlanner(T target)
      Creates a planner whose invocation plans call handler methods on the supplied target instance.

      The planner may be cached and used concurrently. The default returns null, so matchers are not required to support prepared invocation.

      Parameters:
      target - the object that contains the handler methods
      Returns:
      a thread-safe planner bound to the target, or null when preparation is unsupported

    • bindPayloadHandlerMethodPlanner

      default HandlerMethodPlanner<M> bindPayloadHandlerMethodPlanner()
      Creates a planner for handler methods declared on the payload itself.

      The returned planner may be reused for many payload objects. Its plans must therefore obtain the target from HandlerInput.getPayload() for every invocation and must never retain the representative payload used to select the method.

      Returns:
      a thread-safe payload-target planner, or null when this matcher cannot safely prepare one

    • or

      default HandlerMatcher<T,M> or(HandlerMatcher<T,M> next)
      Combines this HandlerMatcher with another HandlerMatcher to form a composite matcher. The resulting matcher is capable of delegating matching responsibilities to both the current matcher and the provided next matcher.
      Parameters:
      next - the next HandlerMatcher to combine with the current matcher
      Returns:
      a new HandlerMatcher that combines the current matcher and the provided next matcher