Package org.springframework.web.servlet

# Interface HandlerMapping

All Known Subinterfaces:
  `MatchableHandlerMapping`

All Known Implementing Classes:
  `AbstractDetectingUrlHandlerMapping`, `AbstractHandlerMapping`, `AbstractHandlerMethodMapping`, `AbstractUrlHandlerMapping`, `BeanNameUrlHandlerMapping`, `RequestMappingHandlerMapping`, `RequestMappingInfoHandlerMapping`, `RouterFunctionMapping`, `SimpleUrlHandlerMapping`

public interface HandlerMapping
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 `BeanNameUrlHandlerMapping` and `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 `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.

Author:
  Rod Johnson, Juergen Hoeller
See Also:
  - `Ordered`
  - `AbstractHandlerMapping`
  - `BeanNameUrlHandlerMapping`
  - `RequestMappingHandlerMapping`

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`BEST_MATCHING_HANDLER_ATTRIBUTE`
Name of the `HttpServletRequest` attribute that contains the mapped handler for the best matching pattern.
`static final String`
`BEST_MATCHING_PATTERN_ATTRIBUTE`
Name of the `HttpServletRequest` attribute that contains the best matching pattern within the handler mapping.
`static final String`
`INTROSPECT_TYPE_LEVEL_MAPPING`
Name of the boolean `HttpServletRequest` attribute that indicates whether type-level mappings should be inspected.
`static final String`
`LOOKUP_PATH`
Deprecated.
as of 5.3 in favor of `UrlPathHelper.PATH_ATTRIBUTE` and `ServletRequestPathUtils.PATH_ATTRIBUTE`.
`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.
`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.
`static final String`
`PRODUCIBLE_MEDIA_TYPES_ATTRIBUTE`
Name of the `HttpServletRequest` attribute that contains the set of producible MediaTypes applicable to the mapped handler.
`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 Type
Method
Description
`HandlerExecutionChain`
`getHandler(HttpServletRequest request)`
Return a handler and any interceptors for this request.
`default boolean`
`usesPathPatterns()`
Whether this `HandlerMapping` instance has been enabled to use parsed `PathPattern`s in which case the `DispatcherServlet` automatically `parses` the `RequestPath` to make it available for `access` in `HandlerMapping`s, `HandlerInterceptor`s, and other components.

## Field Details

### BEST_MATCHING_HANDLER_ATTRIBUTE

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

### LOOKUP_PATH

@Deprecated static final String LOOKUP_PATH
Deprecated.
as of 5.3 in favor of `UrlPathHelper.PATH_ATTRIBUTE` and `ServletRequestPathUtils.PATH_ATTRIBUTE`. To access the cached path used for request mapping, use `ServletRequestPathUtils.getCachedPathValue(ServletRequest)`.
Name of the `HttpServletRequest` attribute that contains the path used to look up the matching handler, which depending on the configured `UrlPathHelper` could be the full path or without the context path, decoded or not, etc.

Since:
  5.2

### PATH_WITHIN_HANDLER_MAPPING_ATTRIBUTE

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.

### BEST_MATCHING_PATTERN_ATTRIBUTE

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_MAPPING

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.

### URI_TEMPLATE_VARIABLES_ATTRIBUTE

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.

### MATRIX_VARIABLES_ATTRIBUTE

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

### PRODUCIBLE_MEDIA_TYPES_ATTRIBUTE

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.

## Method Details

### usesPathPatterns

default boolean usesPathPatterns()
Whether this `HandlerMapping` instance has been enabled to use parsed `PathPattern`s in which case the `DispatcherServlet` automatically `parses` the `RequestPath` to make it available for `access` in `HandlerMapping`s, `HandlerInterceptor`s, and other components.

Since:
  5.3

### getHandler

@Nullable 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` - current HTTP request
Returns:
  a HandlerExecutionChain instance containing handler object and any interceptors, or `null` if no mapping found
Throws:
  `Exception` - if there is an internal error