Package org.springframework.web.servlet.handler

# Class AbstractUrlHandlerMapping

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

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`, `MatchableHandlerMapping`, `HandlerMapping`

Direct Known Subclasses:
  `AbstractDetectingUrlHandlerMapping`, `SimpleUrlHandlerMapping`

public abstract class AbstractUrlHandlerMapping extends AbstractHandlerMapping implements MatchableHandlerMapping
Abstract base class for URL-mapped `HandlerMapping` implementations.

Supports literal matches and pattern matches such as "/test/*", "/test/**", and others. For details on pattern syntax refer to `PathPattern` when parsed patterns are `enabled` or see `AntPathMatcher` otherwise. The syntax is largely the same but the `PathPattern` syntax is more tailored for web applications, and its implementation is more efficient.

All path patterns are checked in order to find the most exact match for the current request path where the "most exact" is the longest path pattern that matches the current request path.

Since:
  16.04.2003
Author:
  Juergen Hoeller, Arjen Poutsma

## Field Summary

### Fields inherited from class org.springframework.web.servlet.handler.AbstractHandlerMapping

`mappingsLogger`

### 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
`AbstractUrlHandlerMapping()`

## Method Summary

Modifier and Type
Method
Description
`protected Object`
`buildPathExposingHandler(Object rawHandler, String bestMatchingPattern, String pathWithinMapping, Map<String,String> uriTemplateVariables)`
Build a handler object for the given raw handler, exposing the actual handler, the `HandlerMapping.PATH_WITHIN_HANDLER_MAPPING_ATTRIBUTE`, as well as the `HandlerMapping.URI_TEMPLATE_VARIABLES_ATTRIBUTE` before executing the handler.
`protected void`
`exposePathWithinMapping(String bestMatchingPattern, String pathWithinMapping, HttpServletRequest request)`
Expose the path within the current mapping as request attribute.
`protected void`
`exposeUriTemplateVariables(Map<String,String> uriTemplateVariables, HttpServletRequest request)`
Expose the URI templates variables as request attribute.
`protected Object`
`getHandlerInternal(HttpServletRequest request)`
Look up a handler for the URL path of the given request.
`final Map<String,Object>`
`getHandlerMap()`
Return the handler mappings as a read-only Map, with the registered path or pattern as key and the handler object (or handler bean name in case of a lazy-init handler), as value.
`final Map<org.springframework.web.util.pattern.PathPattern,Object>`
`getPathPatternHandlerMap()`
Identical to `getHandlerMap()` but populated when parsed patterns are `enabled`; otherwise empty.
`Object`
`getRootHandler()`
Return the root handler for this handler mapping (registered for "/"), or `null` if none.
`protected Object`
`lookupHandler(String lookupPath, HttpServletRequest request)`
Look up a handler instance for the given URL path.
`protected Object`
`lookupHandler(org.springframework.http.server.RequestPath path, String lookupPath, HttpServletRequest request)`
Look up a handler instance for the given URL path.
`RequestMatchResult`
`match(HttpServletRequest request, String pattern)`
Determine whether the request matches the given pattern.
`void`
`registerHandler(String[] urlPaths, String beanName)`
Register the specified handler for the given URL paths.
`void`
`registerHandler(String urlPath, Object handler)`
Register the specified handler for the given URL path.
`void`
`setLazyInitHandlers(boolean lazyInitHandlers)`
Set whether to lazily initialize handlers.
`void`
`setPatternParser(org.springframework.web.util.pattern.PathPatternParser patternParser)`
Set the `PathPatternParser` to parse `patterns` with for URL path matching.
`void`
`setRootHandler(Object rootHandler)`
Set the root handler for this handler mapping, that is, the handler to be registered for the root path ("/").
`void`
`setUseTrailingSlashMatch(boolean useTrailingSlashMatch)`
Deprecated.
as of 6.0, see `PathPatternParser.setMatchOptionalTrailingSeparator(boolean)`
`protected boolean`
`supportsTypeLevelMappings()`
Indicates whether this handler mapping support type-level mappings.
`void`
`unregisterHandler(String urlPath)`
Remove the mapping for the handler registered for the given URL path.
`boolean`
`useTrailingSlashMatch()`
Whether to match to URLs irrespective of the presence of a trailing slash.
`protected void`
`validateHandler(Object handler, HttpServletRequest request)`
Validate the given handler against the current request.

### Methods inherited from class org.springframework.web.servlet.handler.AbstractHandlerMapping

`adaptInterceptor, detectMappedInterceptors, extendInterceptors, formatMappingName, getAdaptedInterceptors, getCorsConfiguration, getCorsConfigurationSource, getCorsHandlerExecutionChain, getCorsProcessor, getDefaultHandler, getHandler, getHandlerExecutionChain, getMappedInterceptors, getOrder, getPathMatcher, getPatternParser, getUrlPathHelper, hasCorsConfigurationSource, initApplicationContext, initInterceptors, initLookupPath, setAlwaysUseFullPath, setBeanName, setCorsConfigurations, setCorsConfigurationSource, setCorsProcessor, setDefaultHandler, setInterceptors, setOrder, setPathMatcher, setRemoveSemicolonContent, setUrlDecode, setUrlPathHelper, usesPathPatterns`

### 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`

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

`getHandler, usesPathPatterns`

### Methods inherited from interface org.springframework.web.servlet.handler.MatchableHandlerMapping

`getPatternParser`

## Constructor Details

### AbstractUrlHandlerMapping

public AbstractUrlHandlerMapping()

## Method Details

### setPatternParser

public void setPatternParser(@Nullable org.springframework.web.util.pattern.PathPatternParser patternParser)
Description copied from class: `AbstractHandlerMapping`
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:

- `AbstractHandlerMapping.setAlwaysUseFullPath(boolean)` -- parsed patterns always use the full path and consider the servletPath only when a Servlet is mapped by path prefix.
- `AbstractHandlerMapping.setRemoveSemicolonContent(boolean)` -- parsed patterns always ignore semicolon content for path matching purposes, but path parameters remain available for use in controllers via `@MatrixVariable`.
- `AbstractHandlerMapping.setUrlDecode(boolean)` -- parsed patterns match one decoded path segment at a time and therefore don't need to decode the full path.
- `AbstractHandlerMapping.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.
- `AbstractHandlerMapping.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.

Overrides:
  `setPatternParser` in class `AbstractHandlerMapping`
Parameters:
  `patternParser` - the parser to use

### setRootHandler

public void setRootHandler(@Nullable Object rootHandler)
Set the root handler for this handler mapping, that is, the handler to be registered for the root path ("/").

Default is `null`, indicating no root handler.

### getRootHandler

@Nullable public Object getRootHandler()
Return the root handler for this handler mapping (registered for "/"), or `null` if none.

### setUseTrailingSlashMatch

@Deprecated(since="6.0") public void setUseTrailingSlashMatch(boolean useTrailingSlashMatch)
Deprecated.
as of 6.0, see `PathPatternParser.setMatchOptionalTrailingSeparator(boolean)`
Whether to match to URLs irrespective of the presence of a trailing slash. If enabled a URL pattern such as "/users" also matches to "/users/".

The default value is `false`.

### useTrailingSlashMatch

public boolean useTrailingSlashMatch()
Whether to match to URLs irrespective of the presence of a trailing slash.

### setLazyInitHandlers

public void setLazyInitHandlers(boolean lazyInitHandlers)
Set whether to lazily initialize handlers. Only applicable to singleton handlers, as prototypes are always lazily initialized. Default is "false", as eager initialization allows for more efficiency through referencing the controller objects directly.

If you want to allow your controllers to be lazily initialized, make them "lazy-init" and set this flag to true. Just making them "lazy-init" will not work, as they are initialized through the references from the handler mapping in this case.

### registerHandler

public void registerHandler(String[] urlPaths, String beanName) throws org.springframework.beans.BeansException, IllegalStateException
Register the specified handler for the given URL paths.

Parameters:
  `urlPaths` - the URLs that the bean should be mapped to
  `beanName` - the name of the handler bean
Throws:
  `org.springframework.beans.BeansException` - if the handler couldn't be registered
  `IllegalStateException` - if there is a conflicting handler registered
Since:
  6.2

### registerHandler

public void registerHandler(String urlPath, Object handler) throws org.springframework.beans.BeansException, IllegalStateException
Register the specified handler for the given URL path.

Parameters:
  `urlPath` - the URL the bean should be mapped to
  `handler` - the handler instance or handler bean name String (a bean name will automatically be resolved into the corresponding handler bean)
Throws:
  `org.springframework.beans.BeansException` - if the handler couldn't be registered
  `IllegalStateException` - if there is a conflicting handler registered
Since:
  6.2

### unregisterHandler

public void unregisterHandler(String urlPath)
Remove the mapping for the handler registered for the given URL path.

Parameters:
  `urlPath` - the mapping to remove
Since:
  6.2

### getHandlerInternal

@Nullable protected Object getHandlerInternal(HttpServletRequest request) throws Exception
Look up a handler for the URL path of the given request.

Specified by:
  `getHandlerInternal` in class `AbstractHandlerMapping`
Parameters:
  `request` - current HTTP request
Returns:
  the handler instance, or `null` if none found
Throws:
  `Exception` - if there is an internal error

### lookupHandler

@Nullable protected Object lookupHandler(org.springframework.http.server.RequestPath path, String lookupPath, HttpServletRequest request) throws Exception
Look up a handler instance for the given URL path. This method is used when parsed `PathPattern`s are `enabled`.

Parameters:
  `path` - the parsed RequestPath
  `lookupPath` - the String lookupPath for checking direct hits
  `request` - current HTTP request
Returns:
  a matching handler, or `null` if not found
Throws:
  `Exception`
Since:
  5.3

### lookupHandler

@Nullable protected Object lookupHandler(String lookupPath, HttpServletRequest request) throws Exception
Look up a handler instance for the given URL path. This method is used when String pattern matching with `PathMatcher` is in use.

Parameters:
  `lookupPath` - the path to match patterns against
  `request` - current HTTP request
Returns:
  a matching handler, or `null` if not found
Throws:
  `Exception`
See Also:
  - `exposePathWithinMapping(java.lang.String, java.lang.String, jakarta.servlet.http.HttpServletRequest)`
  - `AntPathMatcher`

### validateHandler

protected void validateHandler(Object handler, HttpServletRequest request) throws Exception
Validate the given handler against the current request.

The default implementation is empty. Can be overridden in subclasses, for example to enforce specific preconditions expressed in URL mappings.

Parameters:
  `handler` - the handler object to validate
  `request` - current HTTP request
Throws:
  `Exception` - if validation failed

### buildPathExposingHandler

protected Object buildPathExposingHandler(Object rawHandler, String bestMatchingPattern, String pathWithinMapping, @Nullable Map<String,String> uriTemplateVariables)
Build a handler object for the given raw handler, exposing the actual handler, the `HandlerMapping.PATH_WITHIN_HANDLER_MAPPING_ATTRIBUTE`, as well as the `HandlerMapping.URI_TEMPLATE_VARIABLES_ATTRIBUTE` before executing the handler.

The default implementation builds a `HandlerExecutionChain` with a special interceptor that exposes the path attribute and URI template variables

Parameters:
  `rawHandler` - the raw handler to expose
  `pathWithinMapping` - the path to expose before executing the handler
  `uriTemplateVariables` - the URI template variables, can be `null` if no variables found
Returns:
  the final handler object

### exposePathWithinMapping

protected void exposePathWithinMapping(String bestMatchingPattern, String pathWithinMapping, HttpServletRequest request)
Expose the path within the current mapping as request attribute.

Parameters:
  `pathWithinMapping` - the path within the current mapping
  `request` - the request to expose the path to
See Also:
  - `HandlerMapping.PATH_WITHIN_HANDLER_MAPPING_ATTRIBUTE`

### exposeUriTemplateVariables

protected void exposeUriTemplateVariables(Map<String,String> uriTemplateVariables, HttpServletRequest request)
Expose the URI templates variables as request attribute.

Parameters:
  `uriTemplateVariables` - the URI template variables
  `request` - the request to expose the path to
See Also:
  - `HandlerMapping.PATH_WITHIN_HANDLER_MAPPING_ATTRIBUTE`

### match

@Nullable public RequestMatchResult match(HttpServletRequest request, String pattern)
Description copied from interface: `MatchableHandlerMapping`
Determine whether the request matches the given pattern. Use this method when `MatchableHandlerMapping.getPatternParser()` returns `null` which means that the `HandlerMapping` is using String pattern matching.

Specified by:
  `match` in interface `MatchableHandlerMapping`
Parameters:
  `request` - the current request
  `pattern` - the pattern to match
Returns:
  the result from request matching, or `null` if none

### getHandlerMap

public final Map<String,Object> getHandlerMap()
Return the handler mappings as a read-only Map, with the registered path or pattern as key and the handler object (or handler bean name in case of a lazy-init handler), as value.

See Also:
  - `AbstractHandlerMapping.getDefaultHandler()`

### getPathPatternHandlerMap

public final Map<org.springframework.web.util.pattern.PathPattern,Object> getPathPatternHandlerMap()
Identical to `getHandlerMap()` but populated when parsed patterns are `enabled`; otherwise empty.

Since:
  5.3

### supportsTypeLevelMappings

protected boolean supportsTypeLevelMappings()
Indicates whether this handler mapping support type-level mappings. Default to `false`.