Package org.springframework.web.servlet.handler

# Class AbstractHandlerMapping

java.lang.Object
org.springframework.context.support.ApplicationObjectSupport
org.springframework.web.context.support.WebApplicationObjectSupport
org.springframework.web.servlet.handler.AbstractHandlerMapping

All Implemented Interfaces:
  `org.springframework.beans.factory.Aware`, `org.springframework.beans.factory.BeanNameAware`, `org.springframework.context.ApplicationContextAware`, `org.springframework.core.Ordered`, `org.springframework.web.context.ServletContextAware`, `HandlerMapping`

Direct Known Subclasses:
  `AbstractHandlerMethodMapping`, `AbstractUrlHandlerMapping`, `RouterFunctionMapping`

public abstract class AbstractHandlerMapping extends org.springframework.web.context.support.WebApplicationObjectSupport implements HandlerMapping, org.springframework.core.Ordered, org.springframework.beans.factory.BeanNameAware
Abstract base class for `HandlerMapping` implementations. Supports ordering, a default handler, and handler interceptors, including handler interceptors mapped by path patterns.

Note: This base class does not support exposure of the `HandlerMapping.PATH_WITHIN_HANDLER_MAPPING_ATTRIBUTE`. Support for this attribute is up to concrete subclasses, typically based on request URL mappings.

Since:
  07.04.2003
Author:
  Juergen Hoeller, Rossen Stoyanchev, Sam Brannen
See Also:
  - `getHandlerInternal(jakarta.servlet.http.HttpServletRequest)`
  - `setDefaultHandler(java.lang.Object)`
  - `setInterceptors(java.lang.Object...)`
  - `HandlerInterceptor`

## Field Summary

Fields
Modifier and Type
Field
Description
`protected final org.apache.commons.logging.Log`
`mappingsLogger`
Dedicated "hidden" logger for request mappings.

### Fields inherited from class org.springframework.context.support.ApplicationObjectSupport

`logger`

### Fields inherited from interface org.springframework.web.servlet.HandlerMapping

`BEST_MATCHING_HANDLER_ATTRIBUTE, BEST_MATCHING_PATTERN_ATTRIBUTE, INTROSPECT_TYPE_LEVEL_MAPPING, LOOKUP_PATH, MATRIX_VARIABLES_ATTRIBUTE, PATH_WITHIN_HANDLER_MAPPING_ATTRIBUTE, PRODUCIBLE_MEDIA_TYPES_ATTRIBUTE, URI_TEMPLATE_VARIABLES_ATTRIBUTE`

### Fields inherited from interface org.springframework.core.Ordered

`HIGHEST_PRECEDENCE, LOWEST_PRECEDENCE`

## Constructor Summary

Constructors
Constructor
Description
`AbstractHandlerMapping()`

## Method Summary

Modifier and Type
Method
Description
`protected HandlerInterceptor`
`adaptInterceptor(Object interceptor)`
Adapt the given interceptor object to `HandlerInterceptor`.
`protected void`
`detectMappedInterceptors(List<HandlerInterceptor> mappedInterceptors)`
Detect beans of type `MappedInterceptor` and add them to the list of mapped interceptors.
`protected void`
`extendInterceptors(List<Object> interceptors)`
Extension hook that subclasses can override to register additional interceptors, given the configured interceptors (see `setInterceptors(java.lang.Object...)`).
`protected String`
`formatMappingName()`
`final HandlerInterceptor[]`
`getAdaptedInterceptors()`
Return all configured interceptors adapted to `HandlerInterceptor`.
`protected org.springframework.web.cors.CorsConfiguration`
`getCorsConfiguration(Object handler, HttpServletRequest request)`
Retrieve the CORS configuration for the given handler.
`org.springframework.web.cors.CorsConfigurationSource`
`getCorsConfigurationSource()`
Return the `configured` `CorsConfigurationSource`, if any.
`protected HandlerExecutionChain`
`getCorsHandlerExecutionChain(HttpServletRequest request, HandlerExecutionChain chain, org.springframework.web.cors.CorsConfiguration config)`
Update `HandlerExecutionChain` for CORS requests, inserting an interceptor at the start of the chain to perform CORS checks, and also using a no-op handler for preflight requests.
`org.springframework.web.cors.CorsProcessor`
`getCorsProcessor()`
Return the configured `CorsProcessor`.
`Object`
`getDefaultHandler()`
Return the default handler for this handler mapping, or `null` if none.
`final HandlerExecutionChain`
`getHandler(HttpServletRequest request)`
Look up a handler for the given request, falling back to the default handler if no specific one is found.
`protected HandlerExecutionChain`
`getHandlerExecutionChain(Object handler, HttpServletRequest request)`
Build a `HandlerExecutionChain` for the given handler, including applicable interceptors.
`protected abstract Object`
`getHandlerInternal(HttpServletRequest request)`
Look up a handler for the given request, returning `null` if no specific one is found.
`protected final MappedInterceptor[]`
`getMappedInterceptors()`
Return all configured `MappedInterceptor`s as an array.
`int`
`getOrder()`
`org.springframework.util.PathMatcher`
`getPathMatcher()`
Return the `configured` `PathMatcher`.
`org.springframework.web.util.pattern.PathPatternParser`
`getPatternParser()`
Return the `configured` `PathPatternParser`, or `null` otherwise which indicates that String pattern matching with `AntPathMatcher` is enabled instead.
`org.springframework.web.util.UrlPathHelper`
`getUrlPathHelper()`
Return the `configured` `UrlPathHelper`.
`protected boolean`
`hasCorsConfigurationSource(Object handler)`
Return `true` if there is a `CorsConfigurationSource` for this handler.
`protected void`
`initApplicationContext()`
Initializes the interceptors.
`protected void`
`initInterceptors()`
Initialize the specified interceptors adapting `WebRequestInterceptor`s to `HandlerInterceptor`.
`protected String`
`initLookupPath(HttpServletRequest request)`
Initialize the path to use for request mapping.
`void`
`setAlwaysUseFullPath(boolean alwaysUseFullPath)`
Deprecated.
as of 6.0, in favor of using `setUrlPathHelper(UrlPathHelper)`
`void`
`setBeanName(String name)`
`void`
`setCorsConfigurations(Map<String,org.springframework.web.cors.CorsConfiguration> corsConfigurations)`
Set "global" CORS configuration mappings.
`void`
`setCorsConfigurationSource(org.springframework.web.cors.CorsConfigurationSource source)`
Set a `CorsConfigurationSource` for "global" CORS config.
`void`
`setCorsProcessor(org.springframework.web.cors.CorsProcessor corsProcessor)`
Configure a custom `CorsProcessor` to use to apply the matched `CorsConfiguration` for a request.
`void`
`setDefaultHandler(Object defaultHandler)`
Set the default handler for this handler mapping.
`void`
`setInterceptors(Object... interceptors)`
Set the interceptors to apply for all handlers mapped by this handler mapping.
`void`
`setOrder(int order)`
Specify the order value for this HandlerMapping bean.
`void`
`setPathMatcher(org.springframework.util.PathMatcher pathMatcher)`
Configure the PathMatcher to use.
`void`
`setPatternParser(org.springframework.web.util.pattern.PathPatternParser patternParser)`
Set the `PathPatternParser` to parse `patterns` with for URL path matching.
`void`
`setRemoveSemicolonContent(boolean removeSemicolonContent)`
Deprecated.
as of 6.0, in favor of using `setUrlPathHelper(UrlPathHelper)`
`void`
`setUrlDecode(boolean urlDecode)`
Deprecated.
as of 6.0, in favor of using `setUrlPathHelper(UrlPathHelper)`
`void`
`setUrlPathHelper(org.springframework.web.util.UrlPathHelper urlPathHelper)`
Configure the UrlPathHelper to use for resolution of lookup paths.
`boolean`
`usesPathPatterns()`
Return "true" if this `HandlerMapping` has been `enabled` to use parsed `PathPattern`s.

### Methods inherited from class org.springframework.web.context.support.WebApplicationObjectSupport

`getServletContext, getTempDir, getWebApplicationContext, initApplicationContext, initServletContext, isContextRequired, setServletContext`

### Methods inherited from class org.springframework.context.support.ApplicationObjectSupport

`getApplicationContext, getMessageSourceAccessor, obtainApplicationContext, requiredContextClass, setApplicationContext`

### Methods inherited from class java.lang.Object

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

## Field Details

### mappingsLogger

protected final org.apache.commons.logging.Log mappingsLogger
Dedicated "hidden" logger for request mappings.

## Constructor Details

### AbstractHandlerMapping

public AbstractHandlerMapping()

## Method Details

### setDefaultHandler

public void setDefaultHandler(@Nullable Object defaultHandler)
Set the default handler for this handler mapping. This handler will be returned if no specific mapping was found.

Default is `null`, indicating no default handler.

### getDefaultHandler

@Nullable public Object getDefaultHandler()
Return the default handler for this handler mapping, or `null` if none.

### setPatternParser

public void setPatternParser(@Nullable org.springframework.web.util.pattern.PathPatternParser patternParser)
Set the `PathPatternParser` to parse `patterns` with for URL path matching. Parsed patterns provide a more modern and efficient alternative to String path matching via `AntPathMatcher`.

Note: This property is mutually exclusive with the below properties, all of which are not necessary for parsed patterns and are ignored when a `PathPatternParser` is available:

- `setAlwaysUseFullPath(boolean)` -- parsed patterns always use the full path and consider the servletPath only when a Servlet is mapped by path prefix.
- `setRemoveSemicolonContent(boolean)` -- parsed patterns always ignore semicolon content for path matching purposes, but path parameters remain available for use in controllers via `@MatrixVariable`.
- `setUrlDecode(boolean)` -- parsed patterns match one decoded path segment at a time and therefore don't need to decode the full path.
- `setUrlPathHelper(org.springframework.web.util.UrlPathHelper)` -- for parsed patterns, the request path is parsed once in `DispatcherServlet` or in `ServletRequestPathFilter` using `ServletRequestPathUtils` and cached in a request attribute.
- `setPathMatcher(org.springframework.util.PathMatcher)` -- a parsed patterns encapsulates the logic for path matching and does need a `PathMatcher`.

By default, as of 6.0, this is set to a `PathPatternParser` instance with default settings and therefore use of parsed patterns is enabled. Set this to `null` to switch to String path matching via `AntPathMatcher` instead.

Parameters:
  `patternParser` - the parser to use
Since:
  5.3

### getPatternParser

@Nullable public org.springframework.web.util.pattern.PathPatternParser getPatternParser()
Return the `configured` `PathPatternParser`, or `null` otherwise which indicates that String pattern matching with `AntPathMatcher` is enabled instead.

Since:
  5.3

### setAlwaysUseFullPath

@Deprecated(since="6.0") public void setAlwaysUseFullPath(boolean alwaysUseFullPath)
Deprecated.
as of 6.0, in favor of using `setUrlPathHelper(UrlPathHelper)`
Shortcut to same property on the configured `UrlPathHelper`.

Note: This property is mutually exclusive with and ignored when `setPatternParser(PathPatternParser)` is set.

See Also:
  - `UrlPathHelper.setAlwaysUseFullPath(boolean)`

### setUrlDecode

@Deprecated(since="6.0") public void setUrlDecode(boolean urlDecode)
Deprecated.
as of 6.0, in favor of using `setUrlPathHelper(UrlPathHelper)`
Shortcut to same property on the underlying `UrlPathHelper`.

Note: This property is mutually exclusive with and ignored when `setPatternParser(PathPatternParser)` is set.

See Also:
  - `UrlPathHelper.setUrlDecode(boolean)`

### setRemoveSemicolonContent

@Deprecated(since="6.0") public void setRemoveSemicolonContent(boolean removeSemicolonContent)
Deprecated.
as of 6.0, in favor of using `setUrlPathHelper(UrlPathHelper)`
Shortcut to same property on the underlying `UrlPathHelper`.

Note: This property is mutually exclusive with and ignored when `setPatternParser(PathPatternParser)` is set.

See Also:
  - `UrlPathHelper.setRemoveSemicolonContent(boolean)`

### setUrlPathHelper

public void setUrlPathHelper(org.springframework.web.util.UrlPathHelper urlPathHelper)
Configure the UrlPathHelper to use for resolution of lookup paths.

Note: This property is mutually exclusive with and ignored when `setPatternParser(PathPatternParser)` is set.

### getUrlPathHelper

public org.springframework.web.util.UrlPathHelper getUrlPathHelper()
Return the `configured` `UrlPathHelper`.

### setPathMatcher

public void setPathMatcher(org.springframework.util.PathMatcher pathMatcher)
Configure the PathMatcher to use.

Note: This property is mutually exclusive with and ignored when `setPatternParser(PathPatternParser)` is set.

By default this is `AntPathMatcher`.

See Also:
  - `AntPathMatcher`

### getPathMatcher

public org.springframework.util.PathMatcher getPathMatcher()
Return the `configured` `PathMatcher`.

### setInterceptors

public void setInterceptors(Object... interceptors)
Set the interceptors to apply for all handlers mapped by this handler mapping.

Supported interceptor types are `HandlerInterceptor`, `WebRequestInterceptor`, and `MappedInterceptor`. Mapped interceptors apply only to request URLs that match its path patterns. Mapped interceptor beans are also detected by type during initialization.

Parameters:
  `interceptors` - array of handler interceptors
See Also:
  - `adaptInterceptor(java.lang.Object)`
  - `HandlerInterceptor`
  - `WebRequestInterceptor`
  - `MappedInterceptor`

### getAdaptedInterceptors

@Nullable public final HandlerInterceptor[] getAdaptedInterceptors()
Return all configured interceptors adapted to `HandlerInterceptor`.

Returns:
  the array of configured interceptors, or `null` if none are configured; this method also returns `null` if called too early, or more specifically before `ApplicationContextAware.setApplicationContext(org.springframework.context.ApplicationContext)`.

### getMappedInterceptors

@Nullable protected final MappedInterceptor[] getMappedInterceptors()
Return all configured `MappedInterceptor`s as an array.

Returns:
  the array of `MappedInterceptor`s, or `null` if none

### setCorsConfigurations

public void setCorsConfigurations(Map<String,org.springframework.web.cors.CorsConfiguration> corsConfigurations)
Set "global" CORS configuration mappings. The first matching URL pattern determines the `CorsConfiguration` to use which is then further `combined` with the `CorsConfiguration` for the selected handler.

This is mutually exclusive with `setCorsConfigurationSource(CorsConfigurationSource)`.

Since:
  4.2
See Also:
  - `setCorsProcessor(CorsProcessor)`

### setCorsConfigurationSource

public void setCorsConfigurationSource(org.springframework.web.cors.CorsConfigurationSource source)
Set a `CorsConfigurationSource` for "global" CORS config. The `CorsConfiguration` determined by the source is `combined` with the `CorsConfiguration` for the selected handler.

This is mutually exclusive with `setCorsConfigurations(Map)`.

Since:
  5.1
See Also:
  - `setCorsProcessor(CorsProcessor)`

### getCorsConfigurationSource

@Nullable public org.springframework.web.cors.CorsConfigurationSource getCorsConfigurationSource()
Return the `configured` `CorsConfigurationSource`, if any.

Since:
  5.3

### setCorsProcessor

public void setCorsProcessor(org.springframework.web.cors.CorsProcessor corsProcessor)
Configure a custom `CorsProcessor` to use to apply the matched `CorsConfiguration` for a request.

By default `DefaultCorsProcessor` is used.

Since:
  4.2

### getCorsProcessor

public org.springframework.web.cors.CorsProcessor getCorsProcessor()
Return the configured `CorsProcessor`.

### setOrder

public void setOrder(int order)
Specify the order value for this HandlerMapping bean.

The default value is `Ordered.LOWEST_PRECEDENCE`, meaning non-ordered.

See Also:
  - `Ordered.getOrder()`

### getOrder

public int getOrder()

Specified by:
  `getOrder` in interface `org.springframework.core.Ordered`

### setBeanName

public void setBeanName(String name)

Specified by:
  `setBeanName` in interface `org.springframework.beans.factory.BeanNameAware`

### formatMappingName

protected String formatMappingName()

### initApplicationContext

protected void initApplicationContext() throws org.springframework.beans.BeansException
Initializes the interceptors.

Overrides:
  `initApplicationContext` in class `org.springframework.context.support.ApplicationObjectSupport`
Throws:
  `org.springframework.beans.BeansException`
See Also:
  - `extendInterceptors(java.util.List)`
  - `initInterceptors()`

### extendInterceptors

protected void extendInterceptors(List<Object> interceptors)
Extension hook that subclasses can override to register additional interceptors, given the configured interceptors (see `setInterceptors(java.lang.Object...)`).

Will be invoked before `initInterceptors()` adapts the specified interceptors into `HandlerInterceptor` instances.

The default implementation is empty.

Parameters:
  `interceptors` - the configured interceptor List (never `null`), allowing to add further interceptors before as well as after the existing interceptors

### detectMappedInterceptors

protected void detectMappedInterceptors(List<HandlerInterceptor> mappedInterceptors)
Detect beans of type `MappedInterceptor` and add them to the list of mapped interceptors.

This is called in addition to any `MappedInterceptor`s that may have been provided via `setInterceptors(java.lang.Object...)`, by default adding all beans of type `MappedInterceptor` from the current context and its ancestors. Subclasses can override and refine this policy.

Parameters:
  `mappedInterceptors` - an empty list to add to

### initInterceptors

protected void initInterceptors()
Initialize the specified interceptors adapting `WebRequestInterceptor`s to `HandlerInterceptor`.

See Also:
  - `setInterceptors(java.lang.Object...)`
  - `adaptInterceptor(java.lang.Object)`

### adaptInterceptor

protected HandlerInterceptor adaptInterceptor(Object interceptor)
Adapt the given interceptor object to `HandlerInterceptor`.

By default, the supported interceptor types are `HandlerInterceptor` and `WebRequestInterceptor`. Each given `WebRequestInterceptor` is wrapped with `WebRequestHandlerInterceptorAdapter`.

Parameters:
  `interceptor` - the interceptor
Returns:
  the interceptor downcast or adapted to HandlerInterceptor
See Also:
  - `HandlerInterceptor`
  - `WebRequestInterceptor`
  - `WebRequestHandlerInterceptorAdapter`

### usesPathPatterns

public boolean usesPathPatterns()
Return "true" if this `HandlerMapping` has been `enabled` to use parsed `PathPattern`s.

Specified by:
  `usesPathPatterns` in interface `HandlerMapping`

### getHandler

@Nullable public final HandlerExecutionChain getHandler(HttpServletRequest request) throws Exception
Look up a handler for the given request, falling back to the default handler if no specific one is found.

Specified by:
  `getHandler` in interface `HandlerMapping`
Parameters:
  `request` - current HTTP request
Returns:
  the corresponding handler instance, or the default handler
Throws:
  `Exception` - if there is an internal error
See Also:
  - `getHandlerInternal(jakarta.servlet.http.HttpServletRequest)`

### getHandlerInternal

@Nullable protected abstract Object getHandlerInternal(HttpServletRequest request) throws Exception
Look up a handler for the given request, returning `null` if no specific one is found. This method is called by `getHandler(jakarta.servlet.http.HttpServletRequest)`; a `null` return value will lead to the default handler, if one is set.

On CORS pre-flight requests this method should return a match not for the pre-flight request but for the expected actual request based on the URL path, the HTTP methods from the "Access-Control-Request-Method" header, and the headers from the "Access-Control-Request-Headers" header thus allowing the CORS configuration to be obtained via `getCorsConfiguration(Object, HttpServletRequest)`,

Note: This method may also return a pre-built `HandlerExecutionChain`, combining a handler object with dynamically determined interceptors. Statically specified interceptors will get merged into such an existing chain.

Parameters:
  `request` - current HTTP request
Returns:
  the corresponding handler instance, or `null` if none found
Throws:
  `Exception` - if there is an internal error

### initLookupPath

protected String initLookupPath(HttpServletRequest request)
Initialize the path to use for request mapping.

When parsed patterns are `enabled` a parsed `RequestPath` is expected to have been `parsed` externally by the `DispatcherServlet` or `ServletRequestPathFilter`.

Otherwise for String pattern matching via `PathMatcher` the path is `resolved` by this method.

Since:
  5.3

### getHandlerExecutionChain

protected HandlerExecutionChain getHandlerExecutionChain(Object handler, HttpServletRequest request)
Build a `HandlerExecutionChain` for the given handler, including applicable interceptors.

The default implementation builds a standard `HandlerExecutionChain` with the given handler, the common interceptors of the handler mapping, and any `MappedInterceptors` matching to the current request URL. Interceptors are added in the order they were registered. Subclasses may override this in order to extend/rearrange the list of interceptors.

NOTE: The passed-in handler object may be a raw handler or a pre-built `HandlerExecutionChain`. This method should handle those two cases explicitly, either building a new `HandlerExecutionChain` or extending the existing chain.

For simply adding an interceptor in a custom subclass, consider calling `super.getHandlerExecutionChain(handler, request)` and invoking `HandlerExecutionChain.addInterceptor(org.springframework.web.servlet.HandlerInterceptor)` on the returned chain object.

Parameters:
  `handler` - the resolved handler instance (never `null`)
  `request` - current HTTP request
Returns:
  the HandlerExecutionChain (never `null`)
See Also:
  - `getAdaptedInterceptors()`

### hasCorsConfigurationSource

protected boolean hasCorsConfigurationSource(Object handler)
Return `true` if there is a `CorsConfigurationSource` for this handler.

Since:
  5.2

### getCorsConfiguration

@Nullable protected org.springframework.web.cors.CorsConfiguration getCorsConfiguration(Object handler, HttpServletRequest request)
Retrieve the CORS configuration for the given handler.

Parameters:
  `handler` - the handler to check (never `null`).
  `request` - the current request.
Returns:
  the CORS configuration for the handler, or `null` if none
Since:
  4.2

### getCorsHandlerExecutionChain

protected HandlerExecutionChain getCorsHandlerExecutionChain(HttpServletRequest request, HandlerExecutionChain chain, @Nullable org.springframework.web.cors.CorsConfiguration config)
Update `HandlerExecutionChain` for CORS requests, inserting an interceptor at the start of the chain to perform CORS checks, and also using a no-op handler for preflight requests.

Parameters:
  `request` - the current request
  `chain` - the chain to update
  `config` - the CORS configuration applicable to the handler
Since:
  4.2