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, 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
  See Also:
    `getHandlerInternal(javax.servlet.http.HttpServletRequest)`, `setDefaultHandler(java.lang.Object)`, `setInterceptors(java.lang.Object...)`, `HandlerInterceptor`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected 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 and Description
    `AbstractHandlerMapping()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and 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()`
    `protected HandlerInterceptor[]` | `getAdaptedInterceptors()` Return the adapted interceptors as `HandlerInterceptor` array.
    `protected CorsConfiguration` | `getCorsConfiguration(Object handler, HttpServletRequest request)` Retrieve the CORS configuration for the given handler.
    `CorsConfigurationSource` | `getCorsConfigurationSource()` Return the `configured` `CorsConfigurationSource`, if any.
    `protected HandlerExecutionChain` | `getCorsHandlerExecutionChain(HttpServletRequest request, HandlerExecutionChain chain, CorsConfiguration config)` Update the HandlerExecutionChain for CORS-related handling.
    `CorsProcessor` | `getCorsProcessor()` Return the configured `CorsProcessor`.
    `Object` | `getDefaultHandler()` Return the default handler for this handler mapping, or `null` if none.
    `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 MappedInterceptor[]` | `getMappedInterceptors()` Return all configured `MappedInterceptor`s as an array.
    `int` | `getOrder()` Get the order value of this object.
    `PathMatcher` | `getPathMatcher()` Return the `configured` `PathMatcher`.
    `PathPatternParser` | `getPatternParser()` Return the `configured` `PathPatternParser`, or `null` otherwise which indicates that String pattern matching with `AntPathMatcher` is enabled instead.
    `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)` Shortcut to same property on the configured `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(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)` Configure the PathMatcher to use.
    `void` | `setPatternParser(PathPatternParser patternParser)` Enable use of pre-parsed `PathPattern`s as an alternative to String pattern matching with `AntPathMatcher`.
    `void` | `setRemoveSemicolonContent(boolean removeSemicolonContent)` Shortcut to same property on the underlying `UrlPathHelper`.
    `void` | `setUrlDecode(boolean urlDecode)` Shortcut to same property on the underlying `UrlPathHelper`.
    `void` | `setUrlPathHelper(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 Detail

    - #### mappingsLogger

          protected final Log mappingsLogger

      Dedicated "hidden" logger for request mappings.

  - ### Constructor Detail

    - #### AbstractHandlerMapping

          public AbstractHandlerMapping()

  - ### Method Detail

    - #### 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
                                       PathPatternParser patternParser)

      Enable use of pre-parsed `PathPattern`s as an alternative to String pattern matching with `AntPathMatcher`. The syntax is largely the same but the `PathPattern` syntax is more tailored for web applications, and its implementation is more efficient.

      This property is mutually exclusive with the following others which are effectively ignored when this is set:

      - `setAlwaysUseFullPath(boolean)` -- `PathPatterns` always use the full path and ignore the servletPath/pathInfo which are decoded and partially normalized and therefore not comparable against the `requestURI`.
      - `setRemoveSemicolonContent(boolean)` -- `PathPatterns` always ignore semicolon content for path matching purposes, but path parameters remain available for use in controllers via `@MatrixVariable`.
      - `setUrlDecode(boolean)` -- `PathPatterns` match one decoded path segment at a time and never need the full decoded path which can cause issues due to decoded reserved characters.
      - `setUrlPathHelper(org.springframework.web.util.UrlPathHelper)` -- the request path is pre-parsed globally by the `DispatcherServlet` or by `ServletRequestPathFilter` using `ServletRequestPathUtils` and saved in a request attribute for re-use.
      - `setPathMatcher(org.springframework.util.PathMatcher)` -- patterns are parsed to `PathPatterns` and used instead of String matching with `PathMatcher`.

      By default this is not set.

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

    - #### getPatternParser

          @Nullable
          public PathPatternParser getPatternParser()

      Return the `configured` `PathPatternParser`, or `null` otherwise which indicates that String pattern matching with `AntPathMatcher` is enabled instead.
      Since:
        5.3

    - #### setAlwaysUseFullPath

          public void setAlwaysUseFullPath(boolean alwaysUseFullPath)

      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

          public void setUrlDecode(boolean urlDecode)

      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

          public void setRemoveSemicolonContent(boolean removeSemicolonContent)

      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(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 UrlPathHelper getUrlPathHelper()

      Return the `configured` `UrlPathHelper`.

    - #### setPathMatcher

          public void setPathMatcher(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 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`

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

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

    - #### getAdaptedInterceptors

          @Nullable
          protected final HandlerInterceptor[] getAdaptedInterceptors()

      Return the adapted interceptors as `HandlerInterceptor` array.
      Returns:
        the array of `HandlerInterceptor`s, or `null` if none

    - #### getMappedInterceptors

          @Nullable
          protected final MappedInterceptor[] getMappedInterceptors()

      Return all configured `MappedInterceptor`s as an array.
      Returns:
        the array of `MappedInterceptor`s, or `null` if none

    - #### 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(javax.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(javax.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 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 the HandlerExecutionChain for CORS-related handling.

      For pre-flight requests, the default implementation replaces the selected handler with a simple HttpRequestHandler that invokes the configured `setCorsProcessor(org.springframework.web.cors.CorsProcessor)`.

      For actual requests, the default implementation inserts a HandlerInterceptor that makes CORS-related checks and adds CORS headers.

      Parameters:
        `request` - the current request
        `chain` - the handler chain
        `config` - the applicable CORS configuration (possibly `null`)
      Since:
        4.2