Class WebHandlerMatcher

java.lang.Object

io.fluxzero.sdk.web.WebHandlerMatcher

All Implemented Interfaces:

HandlerMatcher<Object, DeserializingMessage>

public class WebHandlerMatcher
extends Object
implements HandlerMatcher<Object, DeserializingMessage>

Specialized HandlerMatcher that routes DeserializingMessages of type MessageType.WEBREQUEST to matching handler methods based on annotated URI patterns, HTTP methods, and optional origins.

This matcher is created internally by the HandlerFactory when registering a handler class that contains methods annotated for web request handling (e.g., @HandleWeb).

Routing Logic

The matcher builds an internal route table that maps:

• HTTP method (e.g., GET, POST)
• Normalized path (optionally prefixed by @Path at class or package level)
• Optional request origin (e.g., scheme and host) when specified in the handler method

During matching, the DefaultWebRequestContext is used to extract the URI path, method, and origin from the incoming request metadata.

WebPattern Matching

Each handler method may be associated with one or more WebPatterns, derived from WebParameters annotations. These patterns define the matchable paths and methods.

If multiple routes match the same request, the most specific route is selected. Literal path parts outrank path parameters, constrained path parameters outrank unconstrained parameters, and wildcard or catch-all routes are treated as fallbacks. For example, /a/b/c wins over /a/{value}/c, which wins over /a/*/c.

Support for @Path Annotations

This matcher also respects @Path annotations on the method, declaring class, or package level, combining those with the WebPattern#getPath() when routing requests.

Fallback to ANY Method

If no handler matches the exact request method, but any handlers exist that declare HttpRequestMethod.ANY, these are checked as a fallback.

Automatic HTTP Helpers

HEAD can fall back to a matching GET route, and OPTIONS can be generated from matching routes. A factory-scoped route registry ensures explicit HEAD, OPTIONS, or ANY handlers registered in another handler class win over generated helpers.

See Also:

• HandlerMatcher
• WebPattern
• WebRequest
• WebUtils.getWebPatterns(Class, Object, Executable)

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	WebHandlerMatcher(Object handler, List<HandlerInspector.MethodHandlerMatcher<DeserializingMessage>> methodHandlerMatchers, io.fluxzero.sdk.web.WebRouteRegistry routeRegistry)

Method Summary

Modifier and Type	Method	Description
boolean	canHandle(DeserializingMessage message)	Returns whether the given message can be handled by a handler instance of type T.
protected static WebHandlerMatcher	create(Object handler, Class<?> type, List<ParameterResolver<? super DeserializingMessage>> parameterResolvers, HandlerConfiguration<DeserializingMessage> config)
protected static WebHandlerMatcher	create(Object handler, Class<?> type, List<ParameterResolver<? super DeserializingMessage>> parameterResolvers, HandlerConfiguration<DeserializingMessage> config, io.fluxzero.sdk.web.WebRouteRegistry routeRegistry)
static WebHandlerMatcher	create(Object handler, List<ParameterResolver<? super DeserializingMessage>> parameterResolvers, HandlerConfiguration<DeserializingMessage> config)
static WebHandlerMatcher	create(Object handler, List<ParameterResolver<? super DeserializingMessage>> parameterResolvers, HandlerConfiguration<DeserializingMessage> config, Object routeRegistry)
static Object	createRouteRegistry()
Optional<HandlerInvoker>	getInvoker(Object target, DeserializingMessage message)	Attempts to resolve a HandlerInvoker for the given target instance and message.
Stream<Executable>	matchingMethods(DeserializingMessage message)	Returns a stream of methods from the target class that match the given message.
protected Optional<io.fluxzero.sdk.web.WebHandlerMatcher.WebRouteHandler>	methodMatcher(DeserializingMessage message)

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface HandlerMatcher

bindHandlerMethod, getInvokerOrNull, or

Constructor Details

WebHandlerMatcher

protected WebHandlerMatcher(Object handler,
 List<HandlerInspector.MethodHandlerMatcher<DeserializingMessage>> methodHandlerMatchers,
 io.fluxzero.sdk.web.WebRouteRegistry routeRegistry)

Method Details

create

public static WebHandlerMatcher create(Object handler,
 List<ParameterResolver<? super DeserializingMessage>> parameterResolvers,
 HandlerConfiguration<DeserializingMessage> config)

createRouteRegistry

public static Object createRouteRegistry()

create

protected static WebHandlerMatcher create(Object handler,
 Class<?> type,
 List<ParameterResolver<? super DeserializingMessage>> parameterResolvers,
 HandlerConfiguration<DeserializingMessage> config)

create

public static WebHandlerMatcher create(Object handler,
 List<ParameterResolver<? super DeserializingMessage>> parameterResolvers,
 HandlerConfiguration<DeserializingMessage> config,
 Object routeRegistry)

create

protected static WebHandlerMatcher create(Object handler,
 Class<?> type,
 List<ParameterResolver<? super DeserializingMessage>> parameterResolvers,
 HandlerConfiguration<DeserializingMessage> config,
 io.fluxzero.sdk.web.WebRouteRegistry routeRegistry)

canHandle

public boolean canHandle(DeserializingMessage message)

Description copied from interface: HandlerMatcher

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.

Specified by:

canHandle in interface HandlerMatcher<Object, DeserializingMessage>

Parameters:

message - the message to check

Returns:

true if the matcher may be able to produce an invoker for the given message

matchingMethods

public Stream<Executable> matchingMethods(DeserializingMessage message)

Description copied from interface: HandlerMatcher

Returns a stream of methods from the target class that match the given message. Typically used for diagnostics or documentation tools.

Specified by:

matchingMethods in interface HandlerMatcher<Object, DeserializingMessage>

Parameters:

message - the message to match against

Returns:

a stream of matching Executable handler methods

getInvoker

public Optional<HandlerInvoker> getInvoker(Object target,
 DeserializingMessage message)

Description copied from interface: HandlerMatcher

Attempts to resolve a HandlerInvoker for the given target instance and message.

Specified by:

getInvoker in interface HandlerMatcher<Object, DeserializingMessage>

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

methodMatcher

protected Optional<io.fluxzero.sdk.web.WebHandlerMatcher.WebRouteHandler> methodMatcher(DeserializingMessage message)