Top Description Fields Methods
org.springframework.web.servlet

public Interface HandlerMapping

Known Direct Subinterfaces
org.springframework.web.servlet.handler.MatchableHandlerMapping
Known Direct Implementers
org.springframework.web.servlet.handler.AbstractHandlerMapping
Imports
jakarta.servlet.ServletRequest, jakarta.servlet.http.HttpServletRequest, org.springframework.lang.Nullable
Interface to be implemented by objects that define a mapping between requests and handler objects.

This class can be implemented by application developers, although this is not necessary, as org.springframework.web.servlet.handler.BeanNameUrlHandlerMapping and org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping are included in the framework. The former is the default if no HandlerMapping bean is registered in the application context.

HandlerMapping implementations can support mapped interceptors but do not have to. A handler will always be wrapped in a HandlerExecutionChain instance, optionally accompanied by some HandlerInterceptor instances. The DispatcherServlet will first call each HandlerInterceptor's preHandle method in the given order, finally invoking the handler itself if all preHandle methods have returned true.

The ability to parameterize this mapping is a powerful and unusual capability of this MVC framework. For example, it is possible to write a custom mapping based on session state, cookie state or many other variables. No other MVC framework seems to be equally flexible.

Note

Implementations can implement the org.springframework.core.Ordered interface to be able to specify a sorting order and thus a priority for getting applied by DispatcherServlet. Non-Ordered instances get treated as the lowest priority.

Authors
Rod Johnson, Juergen Hoeller
See Also
org.springframework.core.Ordered, org.springframework.web.servlet.handler.AbstractHandlerMapping, org.springframework.web.servlet.handler.BeanNameUrlHandlerMapping, org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping

Field Summary

Modifier and TypeField and Description
public static final String
BEST_MATCHING_HANDLER_ATTRIBUTE

Name of the HttpServletRequest attribute that contains the mapped handler for the best matching pattern.

public static final String
BEST_MATCHING_PATTERN_ATTRIBUTE

Name of the HttpServletRequest attribute that contains the best matching pattern within the handler mapping.

public static final String
INTROSPECT_TYPE_LEVEL_MAPPING

Name of the boolean HttpServletRequest attribute that indicates whether type-level mappings should be inspected.

public static final String
LOOKUP_PATH

Deprecated as of 5.3 in favor of org.springframework.web.util.UrlPathHelper#PATH_ATTRIBUTE and org.springframework.web.util.ServletRequestPathUtils#PATH_ATTRIBUTE.
Name of the HttpServletRequest attribute that contains the path used to look up the matching handler, which depending on the configured org.springframework.web.util.UrlPathHelper could be the full path or without the context path, decoded or not, etc.
public static final String
MATRIX_VARIABLES_ATTRIBUTE

Name of the HttpServletRequest attribute that contains a map with URI variable names and a corresponding MultiValueMap of URI matrix variables for each.

public static final String
PATH_WITHIN_HANDLER_MAPPING_ATTRIBUTE

Name of the HttpServletRequest attribute that contains the path within the handler mapping, in case of a pattern match, or the full relevant URI (typically within the DispatcherServlet's mapping) else.

public static final String
PRODUCIBLE_MEDIA_TYPES_ATTRIBUTE

Name of the HttpServletRequest attribute that contains the set of producible MediaTypes applicable to the mapped handler.

public static final String
URI_TEMPLATE_VARIABLES_ATTRIBUTE

Name of the HttpServletRequest attribute that contains the URI templates map, mapping variable names to values.

Method Summary

Modifier and TypeMethod and Description
public HandlerExecutionChain

Returns:

a HandlerExecutionChain instance containing handler object and any interceptors, or null if no mapping found
getHandler(HttpServletRequest
current HTTP request
request)

Return a handler and any interceptors for this request.

public default boolean
usesPathPatterns()

Whether this HandlerMapping instance has been enabled to use parsed org.springframework.web.util.pattern.PathPatterns in which case the DispatcherServlet automatically parses the RequestPath to make it available for access in HandlerMappings, HandlerInterceptors, and other components.

Field Detail

BEST_MATCHING_HANDLER_ATTRIBUTEback to summary
public static final String BEST_MATCHING_HANDLER_ATTRIBUTE

Name of the HttpServletRequest attribute that contains the mapped handler for the best matching pattern.

Since
4.3.21
BEST_MATCHING_PATTERN_ATTRIBUTEback to summary
public static final String BEST_MATCHING_PATTERN_ATTRIBUTE

Name of the HttpServletRequest attribute that contains the best matching pattern within the handler mapping.

Note

This attribute is not required to be supported by all HandlerMapping implementations. URL-based HandlerMappings will typically support it, but handlers should not necessarily expect this request attribute to be present in all scenarios.

INTROSPECT_TYPE_LEVEL_MAPPINGback to summary
public static final String INTROSPECT_TYPE_LEVEL_MAPPING

Name of the boolean HttpServletRequest attribute that indicates whether type-level mappings should be inspected.

Note

This attribute is not required to be supported by all HandlerMapping implementations.

LOOKUP_PATHback to summary
public static final String LOOKUP_PATH

Deprecated

as of 5.3 in favor of org.springframework.web.util.UrlPathHelper#PATH_ATTRIBUTE and org.springframework.web.util.ServletRequestPathUtils#PATH_ATTRIBUTE. To access the cached path used for request mapping, use org.springframework.web.util.ServletRequestPathUtils#getCachedPathValue(ServletRequest).

Name of the HttpServletRequest attribute that contains the path used to look up the matching handler, which depending on the configured org.springframework.web.util.UrlPathHelper could be the full path or without the context path, decoded or not, etc.

Annotations
@Deprecated
Since
5.2
MATRIX_VARIABLES_ATTRIBUTEback to summary
public static final String MATRIX_VARIABLES_ATTRIBUTE

Name of the HttpServletRequest attribute that contains a map with URI variable names and a corresponding MultiValueMap of URI matrix variables for each.

Note

This attribute is not required to be supported by all HandlerMapping implementations and may also not be present depending on whether the HandlerMapping is configured to keep matrix variable content

PATH_WITHIN_HANDLER_MAPPING_ATTRIBUTEback to summary
public static final String PATH_WITHIN_HANDLER_MAPPING_ATTRIBUTE

Name of the HttpServletRequest attribute that contains the path within the handler mapping, in case of a pattern match, or the full relevant URI (typically within the DispatcherServlet's mapping) else.

Note

This attribute is not required to be supported by all HandlerMapping implementations. URL-based HandlerMappings will typically support it, but handlers should not necessarily expect this request attribute to be present in all scenarios.

PRODUCIBLE_MEDIA_TYPES_ATTRIBUTEback to summary
public static final String PRODUCIBLE_MEDIA_TYPES_ATTRIBUTE

Name of the HttpServletRequest attribute that contains the set of producible MediaTypes applicable to the mapped handler.

Note

This attribute is not required to be supported by all HandlerMapping implementations. Handlers should not necessarily expect this request attribute to be present in all scenarios.

URI_TEMPLATE_VARIABLES_ATTRIBUTEback to summary
public static final String URI_TEMPLATE_VARIABLES_ATTRIBUTE

Name of the HttpServletRequest attribute that contains the URI templates map, mapping variable names to values.

Note

This attribute is not required to be supported by all HandlerMapping implementations. URL-based HandlerMappings will typically support it, but handlers should not necessarily expect this request attribute to be present in all scenarios.

Method Detail

getHandlerback to summary
public HandlerExecutionChain getHandler(HttpServletRequest request) throws Exception

Return a handler and any interceptors for this request. The choice may be made on request URL, session state, or any factor the implementing class chooses.

The returned HandlerExecutionChain contains a handler Object, rather than even a tag interface, so that handlers are not constrained in any way. For example, a HandlerAdapter could be written to allow another framework's handler objects to be used.

Returns null if no match was found. This is not an error. The DispatcherServlet will query all registered HandlerMapping beans to find a match, and only decide there is an error if none can find a handler.

Parameters
request:HttpServletRequest

current HTTP request

Returns:HandlerExecutionChain

a HandlerExecutionChain instance containing handler object and any interceptors, or null if no mapping found

Annotations
@Nullable
Exceptions
Exception:
if there is an internal error
usesPathPatternsback to summary
public default boolean usesPathPatterns()

Whether this HandlerMapping instance has been enabled to use parsed org.springframework.web.util.pattern.PathPatterns in which case the DispatcherServlet automatically parses the RequestPath to make it available for access in HandlerMappings, HandlerInterceptors, and other components.

Since
5.3