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

    • 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