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:

Aware, BeanNameAware, ApplicationContextAware, Ordered, ServletContextAware, HandlerMapping

Direct Known Subclasses:

AbstractHandlerMethodMapping, AbstractUrlHandlerMapping, RouterFunctionMapping

public abstract class AbstractHandlerMapping
extends WebApplicationObjectSupport
implements HandlerMapping, Ordered, 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 @Nullable []	getAdaptedInterceptors()	Return all configured interceptors adapted to HandlerInterceptor.
protected @Nullable CorsConfiguration	getCorsConfiguration(Object handler, HttpServletRequest request)	Retrieve the CORS configuration for the given handler.
@Nullable CorsConfigurationSource	getCorsConfigurationSource()	Return the configured CorsConfigurationSource, if any.
protected HandlerExecutionChain	getCorsHandlerExecutionChain(HttpServletRequest request, HandlerExecutionChain chain, @Nullable 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.
CorsProcessor	getCorsProcessor()	Return the configured CorsProcessor.
@Nullable Object	getDefaultHandler()	Return the default handler for this handler mapping, or null if none.
final @Nullable 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 @Nullable Object	getHandlerInternal(HttpServletRequest request)	Look up a handler for the given request, returning null if no specific one is found.
protected final MappedInterceptor @Nullable []	getMappedInterceptors()	Return all configured MappedInterceptors as an array.
int	getOrder()	Get the order value of this object.
PathMatcher	getPathMatcher()	Deprecated, for removal: This API element is subject to removal in a future version. use of PathMatcher and UrlPathHelper is deprecated for use at runtime in web modules in favor of parsed patterns with PathPatternParser.
@Nullable PathPatternParser	getPatternParser()	Return the configured PathPatternParser, or null otherwise which indicates that String pattern matching with AntPathMatcher is enabled instead.
UrlPathHelper	getUrlPathHelper()	Deprecated, for removal: This API element is subject to removal in a future version. use of PathMatcher and UrlPathHelper is deprecated for use at runtime in web modules in favor of parsed patterns with PathPatternParser.
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 WebRequestInterceptors 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)	Set the name of the bean in the bean factory that created this bean.
void	setCorsConfigurations(Map<String,CorsConfiguration> corsConfigurations)	Set "global" CORS configuration mappings.
void	setCorsConfigurationSource(CorsConfigurationSource source)	Set a CorsConfigurationSource for "global" CORS config.
void	setCorsProcessor(CorsProcessor corsProcessor)	Configure a custom CorsProcessor to use to apply the matched CorsConfiguration for a request.
void	setDefaultHandler(@Nullable 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(PathMatcher pathMatcher)	Deprecated, for removal: This API element is subject to removal in a future version. use of PathMatcher and UrlPathHelper is deprecated for use at runtime in web modules in favor of parsed patterns with PathPatternParser.
void	setPatternParser(@Nullable 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(UrlPathHelper urlPathHelper)	Deprecated, for removal: This API element is subject to removal in a future version. use of PathMatcher and UrlPathHelper is deprecated for use at runtime in web modules in favor of parsed patterns with PathPatternParser.
boolean	usesPathPatterns()	Return "true" if this HandlerMapping has been enabled to use parsed PathPatterns.

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

public @Nullable Object getDefaultHandler()

Return the default handler for this handler mapping, or null if none.

setPatternParser

public void setPatternParser(@Nullable 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

public @Nullable 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

@Deprecated(since="7.0",
            forRemoval=true)
public void setUrlPathHelper(UrlPathHelper urlPathHelper)

Deprecated, for removal: This API element is subject to removal in a future version.

use of PathMatcher and UrlPathHelper is deprecated for use at runtime in web modules in favor of parsed patterns with PathPatternParser.

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

@Deprecated(since="7.0",
            forRemoval=true)
public UrlPathHelper getUrlPathHelper()

Deprecated, for removal: This API element is subject to removal in a future version.

use of PathMatcher and UrlPathHelper is deprecated for use at runtime in web modules in favor of parsed patterns with PathPatternParser.

Return the configured UrlPathHelper.

setPathMatcher

@Deprecated(since="7.0",
            forRemoval=true)
public void setPathMatcher(PathMatcher pathMatcher)

Deprecated, for removal: This API element is subject to removal in a future version.

use of PathMatcher and UrlPathHelper is deprecated for use at runtime in web modules in favor of parsed patterns with PathPatternParser.

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

@Deprecated(since="7.0",
            forRemoval=true)
public PathMatcher getPathMatcher()

Deprecated, for removal: This API element is subject to removal in a future version.

use of PathMatcher and UrlPathHelper is deprecated for use at runtime in web modules in favor of parsed patterns with PathPatternParser.

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

public final HandlerInterceptor @Nullable [] 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

protected final MappedInterceptor @Nullable [] getMappedInterceptors()

Return all configured MappedInterceptors as an array.

Returns:

the array of MappedInterceptors, or null if none

setCorsConfigurations

public void setCorsConfigurations(Map<String,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(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

public @Nullable CorsConfigurationSource getCorsConfigurationSource()

Return the configured CorsConfigurationSource, if any.

Since:

5.3

setCorsProcessor

public void setCorsProcessor(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 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()

Description copied from interface: Ordered

Get the order value of this object.

Higher values are interpreted as lower priority. As a consequence, the object with the lowest value has the highest priority (somewhat analogous to Servlet load-on-startup values).

Same order values will result in arbitrary sort positions for the affected objects.

Specified by:

getOrder in interface Ordered

Returns:

the order value

See Also:

• Ordered.HIGHEST_PRECEDENCE
• Ordered.LOWEST_PRECEDENCE

setBeanName

public void setBeanName(String name)

Description copied from interface: BeanNameAware

Set the name of the bean in the bean factory that created this bean.

Invoked after population of normal bean properties but before an init callback such as InitializingBean.afterPropertiesSet() or a custom init-method.

Specified by:

setBeanName in interface BeanNameAware

Parameters:

name - the name of the bean in the factory. Note that this name is the actual bean name used in the factory, which may differ from the originally specified name: in particular for inner bean names, the actual bean name might have been made unique through appending "#..." suffixes. Use the BeanFactoryUtils.originalBeanName(String) method to extract the original bean name (without suffix), if desired.

formatMappingName

protected String formatMappingName()

initApplicationContext

protected void initApplicationContext()
                               throws BeansException

Initializes the interceptors.

Overrides:

initApplicationContext in class ApplicationObjectSupport

Throws:

ApplicationContextException - in case of initialization errors

BeansException - if thrown by ApplicationContext methods

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 MappedInterceptors 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 WebRequestInterceptors 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 PathPatterns.

Specified by:

usesPathPatterns in interface HandlerMapping

getHandler

public final @Nullable 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

protected abstract @Nullable 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

protected @Nullable 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 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