org.springframework.web.servlet.handler

## Class AbstractHandlerMethodMapping<T>

- 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.AbstractHandlerMethodMapping<T>

- Type Parameters:
    `T` - the mapping for a `HandlerMethod` containing the conditions needed to match the handler method to an incoming request.
  All Implemented Interfaces:
    Aware, BeanNameAware, InitializingBean, ApplicationContextAware, Ordered, ServletContextAware, HandlerMapping
  Direct Known Subclasses:
    RequestMappingInfoHandlerMapping

      public abstract class AbstractHandlerMethodMapping<T>
      extends AbstractHandlerMapping
      implements InitializingBean

  Abstract base class for `HandlerMapping` implementations that define a mapping between a request and a `HandlerMethod`.

  For each registered handler method, a unique mapping is maintained with subclasses defining the details of the mapping type `<T>`.

  Since:
    3.1
  Author:
    Arjen Poutsma, Rossen Stoyanchev, Juergen Hoeller, Sam Brannen

- - ### 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 and Description
    `AbstractHandlerMethodMapping()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `afterPropertiesSet()` Detects handler methods at initialization.
    `protected HandlerMethod` | `createHandlerMethod(Object handler, Method method)` Create the HandlerMethod instance.
    `protected void` | `detectHandlerMethods(Object handler)` Look for handler methods in the specified handler bean.
    `protected String[]` | `getCandidateBeanNames()` Determine the names of candidate beans in the application context.
    `protected CorsConfiguration` | `getCorsConfiguration(Object handler, HttpServletRequest request)` Retrieve the CORS configuration for the given handler.
    `protected Set<String>` | `getDirectPaths(T mapping)` Return the request mapping paths that are not patterns.
    `protected HandlerMethod` | `getHandlerInternal(HttpServletRequest request)` Look up a handler method for the given request.
    `Map<T,HandlerMethod>` | `getHandlerMethods()` Return a (read-only) map with all mappings and HandlerMethod's.
    `List<HandlerMethod>` | `getHandlerMethodsForMappingName(String mappingName)` Return the handler methods for the given mapping name.
    `protected abstract Comparator<T>` | `getMappingComparator(HttpServletRequest request)` Return a comparator for sorting matching mappings.
    `protected abstract T` | `getMappingForMethod(Method method, Class<?> handlerType)` Provide the mapping for a handler method.
    `protected Set<String>` | `getMappingPathPatterns(T mapping)` Deprecated. as of 5.3 in favor of providing non-pattern mappings via `getDirectPaths(Object)` instead
    `protected abstract T` | `getMatchingMapping(T mapping, HttpServletRequest request)` Check if a mapping matches the current request and return a (potentially new) mapping with conditions relevant to the current request.
    `HandlerMethodMappingNamingStrategy<T>` | `getNamingStrategy()` Return the configured naming strategy or `null`.
    `protected void` | `handleMatch(T mapping, String lookupPath, HttpServletRequest request)` Invoked when a matching mapping is found.
    `protected HandlerMethod` | `handleNoMatch(Set<T> mappings, String lookupPath, HttpServletRequest request)` Invoked when no matching mapping is not found.
    `protected void` | `handlerMethodsInitialized(Map<T,HandlerMethod> handlerMethods)` Invoked after all handler methods have been detected.
    `protected boolean` | `hasCorsConfigurationSource(Object handler)` Return `true` if there is a `CorsConfigurationSource` for this handler.
    `protected CorsConfiguration` | `initCorsConfiguration(Object handler, Method method, T mapping)` Extract and return the CORS configuration for the mapping.
    `protected void` | `initHandlerMethods()` Scan beans in the ApplicationContext, detect and register handler methods.
    `protected abstract boolean` | `isHandler(Class<?> beanType)` Whether the given type is a handler with handler methods.
    `protected HandlerMethod` | `lookupHandlerMethod(String lookupPath, HttpServletRequest request)` Look up the best-matching handler method for the current request.
    `protected void` | `processCandidateBean(String beanName)` Determine the type of the specified candidate bean and call `detectHandlerMethods(java.lang.Object)` if identified as a handler type.
    `protected void` | `registerHandlerMethod(Object handler, Method method, T mapping)` Register a handler method and its unique mapping.
    `void` | `registerMapping(T mapping, Object handler, Method method)` Register the given mapping.
    `void` | `setDetectHandlerMethodsInAncestorContexts(boolean detectHandlerMethodsInAncestorContexts)` Whether to detect handler methods in beans in ancestor ApplicationContexts.
    `void` | `setHandlerMethodMappingNamingStrategy(HandlerMethodMappingNamingStrategy<T> namingStrategy)` Configure the naming strategy to use for assigning a default name to every mapped handler method.
    `void` | `setPatternParser(PathPatternParser patternParser)` Enable use of pre-parsed `PathPattern`s as an alternative to String pattern matching with `AntPathMatcher`.
    `void` | `unregisterMapping(T mapping)` Un-register the given mapping.

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

      `adaptInterceptor, detectMappedInterceptors, extendInterceptors, formatMappingName, getAdaptedInterceptors, getCorsConfigurationSource, getCorsHandlerExecutionChain, getCorsProcessor, getDefaultHandler, getHandler, getHandlerExecutionChain, getMappedInterceptors, getOrder, getPathMatcher, getPatternParser, getUrlPathHelper, 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`

- - ### Constructor Detail

    - #### AbstractHandlerMethodMapping

          public AbstractHandlerMethodMapping()

  - ### Method Detail

    - #### setPatternParser

          public void setPatternParser(@Nullable
                                       PathPatternParser patternParser)

      Description copied from class: `AbstractHandlerMapping`
      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:

      - `AbstractHandlerMapping.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`.
      - `AbstractHandlerMapping.setRemoveSemicolonContent(boolean)` -- `PathPatterns` always ignore semicolon content for path matching purposes, but path parameters remain available for use in controllers via `@MatrixVariable`.
      - `AbstractHandlerMapping.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.
      - `AbstractHandlerMapping.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.
      - `AbstractHandlerMapping.setPathMatcher(org.springframework.util.PathMatcher)` -- patterns are parsed to `PathPatterns` and used instead of String matching with `PathMatcher`.

      By default this is not set.

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

    - #### setDetectHandlerMethodsInAncestorContexts

          public void setDetectHandlerMethodsInAncestorContexts(boolean detectHandlerMethodsInAncestorContexts)

      Whether to detect handler methods in beans in ancestor ApplicationContexts.

      Default is "false": Only beans in the current ApplicationContext are considered, i.e. only in the context that this HandlerMapping itself is defined in (typically the current DispatcherServlet's context).

      Switch this flag on to detect handler beans in ancestor contexts (typically the Spring root WebApplicationContext) as well.

      See Also:
        `getCandidateBeanNames()`

    - #### setHandlerMethodMappingNamingStrategy

          public void setHandlerMethodMappingNamingStrategy(HandlerMethodMappingNamingStrategy<T> namingStrategy)

      Configure the naming strategy to use for assigning a default name to every mapped handler method.

      The default naming strategy is based on the capital letters of the class name followed by "#" and then the method name, e.g. "TC#getFoo" for a class named TestController with method getFoo.

    - #### getNamingStrategy

          @Nullable
          public HandlerMethodMappingNamingStrategy<T> getNamingStrategy()

      Return the configured naming strategy or `null`.

    - #### getHandlerMethods

          public Map<T,HandlerMethod> getHandlerMethods()

      Return a (read-only) map with all mappings and HandlerMethod's.

    - #### getHandlerMethodsForMappingName

          @Nullable
          public List<HandlerMethod> getHandlerMethodsForMappingName(String mappingName)

      Return the handler methods for the given mapping name.
      Parameters:
        `mappingName` - the mapping name
      Returns:
        a list of matching HandlerMethod's or `null`; the returned list will never be modified and is safe to iterate.
      See Also:
        `setHandlerMethodMappingNamingStrategy(org.springframework.web.servlet.handler.HandlerMethodMappingNamingStrategy<T>)`

    - #### registerMapping

          public void registerMapping(T mapping,
                                      Object handler,
                                      Method method)

      Register the given mapping.

      This method may be invoked at runtime after initialization has completed.

      Parameters:
        `mapping` - the mapping for the handler method
        `handler` - the handler
        `method` - the method

    - #### unregisterMapping

          public void unregisterMapping(T mapping)

      Un-register the given mapping.

      This method may be invoked at runtime after initialization has completed.

      Parameters:
        `mapping` - the mapping to unregister

    - #### afterPropertiesSet

          public void afterPropertiesSet()

      Detects handler methods at initialization.
      Specified by:
        `afterPropertiesSet` in interface `InitializingBean`
      See Also:
        `initHandlerMethods()`

    - #### initHandlerMethods

          protected void initHandlerMethods()

      Scan beans in the ApplicationContext, detect and register handler methods.
      See Also:
        `getCandidateBeanNames()`, `processCandidateBean(java.lang.String)`, `handlerMethodsInitialized(java.util.Map<T, org.springframework.web.method.HandlerMethod>)`

    - #### getCandidateBeanNames

          protected String[] getCandidateBeanNames()

      Determine the names of candidate beans in the application context.
      Since:
        5.1
      See Also:
        `setDetectHandlerMethodsInAncestorContexts(boolean)`, `BeanFactoryUtils.beanNamesForTypeIncludingAncestors(org.springframework.beans.factory.ListableBeanFactory, org.springframework.core.ResolvableType)`

    - #### processCandidateBean

          protected void processCandidateBean(String beanName)

      Determine the type of the specified candidate bean and call `detectHandlerMethods(java.lang.Object)` if identified as a handler type.

      This implementation avoids bean creation through checking `BeanFactory.getType(java.lang.String)` and calling `detectHandlerMethods(java.lang.Object)` with the bean name.

      Parameters:
        `beanName` - the name of the candidate bean
      Since:
        5.1
      See Also:
        `isHandler(java.lang.Class<?>)`, `detectHandlerMethods(java.lang.Object)`

    - #### detectHandlerMethods

          protected void detectHandlerMethods(Object handler)

      Look for handler methods in the specified handler bean.
      Parameters:
        `handler` - either a bean name or an actual handler instance
      See Also:
        `getMappingForMethod(java.lang.reflect.Method, java.lang.Class<?>)`

    - #### registerHandlerMethod

          protected void registerHandlerMethod(Object handler,
                                               Method method,
                                               T mapping)

      Register a handler method and its unique mapping. Invoked at startup for each detected handler method.
      Parameters:
        `handler` - the bean name of the handler or the handler instance
        `method` - the method to register
        `mapping` - the mapping conditions associated with the handler method
      Throws:
        `IllegalStateException` - if another method was already registered under the same mapping

    - #### createHandlerMethod

          protected HandlerMethod createHandlerMethod(Object handler,
                                                      Method method)

      Create the HandlerMethod instance.
      Parameters:
        `handler` - either a bean name or an actual handler instance
        `method` - the target method
      Returns:
        the created HandlerMethod

    - #### initCorsConfiguration

          @Nullable
          protected CorsConfiguration initCorsConfiguration(Object handler,
                                                                      Method method,
                                                                      T mapping)

      Extract and return the CORS configuration for the mapping.

    - #### handlerMethodsInitialized

          protected void handlerMethodsInitialized(Map<T,HandlerMethod> handlerMethods)

      Invoked after all handler methods have been detected.
      Parameters:
        `handlerMethods` - a read-only map with handler methods and mappings.

    - #### getHandlerInternal

          @Nullable
          protected HandlerMethod getHandlerInternal(HttpServletRequest request)
                                                        throws Exception

      Look up a handler method for the given request.
      Specified by:
        `getHandlerInternal` in class `AbstractHandlerMapping`
      Parameters:
        `request` - current HTTP request
      Returns:
        the corresponding handler instance, or `null` if none found
      Throws:
        `Exception` - if there is an internal error

    - #### lookupHandlerMethod

          @Nullable
          protected HandlerMethod lookupHandlerMethod(String lookupPath,
                                                                HttpServletRequest request)
                                                         throws Exception

      Look up the best-matching handler method for the current request. If multiple matches are found, the best match is selected.
      Parameters:
        `lookupPath` - mapping lookup path within the current servlet mapping
        `request` - the current request
      Returns:
        the best-matching handler method, or `null` if no match
      Throws:
        `Exception`
      See Also:
        `handleMatch(Object, String, HttpServletRequest)`, `handleNoMatch(Set, String, HttpServletRequest)`

    - #### handleMatch

          protected void handleMatch(T mapping,
                                     String lookupPath,
                                     HttpServletRequest request)

      Invoked when a matching mapping is found.
      Parameters:
        `mapping` - the matching mapping
        `lookupPath` - mapping lookup path within the current servlet mapping
        `request` - the current request

    - #### handleNoMatch

          @Nullable
          protected HandlerMethod handleNoMatch(Set<T> mappings,
                                                          String lookupPath,
                                                          HttpServletRequest request)
                                                   throws Exception

      Invoked when no matching mapping is not found.
      Parameters:
        `mappings` - all registered mappings
        `lookupPath` - mapping lookup path within the current servlet mapping
        `request` - the current request
      Throws:
        `ServletException` - in case of errors
        `Exception`

    - #### hasCorsConfigurationSource

          protected boolean hasCorsConfigurationSource(Object handler)

      Description copied from class: `AbstractHandlerMapping`
      Return `true` if there is a `CorsConfigurationSource` for this handler.
      Overrides:
        `hasCorsConfigurationSource` in class `AbstractHandlerMapping`

    - #### getCorsConfiguration

          protected CorsConfiguration getCorsConfiguration(Object handler,
                                                           HttpServletRequest request)

      Description copied from class: `AbstractHandlerMapping`
      Retrieve the CORS configuration for the given handler.
      Overrides:
        `getCorsConfiguration` in class `AbstractHandlerMapping`
      Parameters:
        `handler` - the handler to check (never `null`).
        `request` - the current request.
      Returns:
        the CORS configuration for the handler, or `null` if none

    - #### isHandler

          protected abstract boolean isHandler(Class<?> beanType)

      Whether the given type is a handler with handler methods.
      Parameters:
        `beanType` - the type of the bean being checked
      Returns:
        "true" if this a handler type, "false" otherwise.

    - #### getMappingForMethod

          @Nullable
          protected abstract T getMappingForMethod(Method method,
                                                             Class<?> handlerType)

      Provide the mapping for a handler method. A method for which no mapping can be provided is not a handler method.
      Parameters:
        `method` - the method to provide a mapping for
        `handlerType` - the handler type, possibly a subtype of the method's declaring class
      Returns:
        the mapping, or `null` if the method is not mapped

    - #### getMappingPathPatterns

          @Deprecated
          protected Set<String> getMappingPathPatterns(T mapping)

      Deprecated. as of 5.3 in favor of providing non-pattern mappings via `getDirectPaths(Object)` instead
      Extract and return the URL paths contained in the supplied mapping.

    - #### getDirectPaths

          protected Set<String> getDirectPaths(T mapping)

      Return the request mapping paths that are not patterns.
      Since:
        5.3

    - #### getMatchingMapping

          @Nullable
          protected abstract T getMatchingMapping(T mapping,
                                                            HttpServletRequest request)

      Check if a mapping matches the current request and return a (potentially new) mapping with conditions relevant to the current request.
      Parameters:
        `mapping` - the mapping to get a match for
        `request` - the current HTTP servlet request
      Returns:
        the match, or `null` if the mapping doesn't match

    - #### getMappingComparator

          protected abstract Comparator<T> getMappingComparator(HttpServletRequest request)

      Return a comparator for sorting matching mappings. The returned comparator should sort 'better' matches higher.
      Parameters:
        `request` - the current request
      Returns:
        the comparator (never `null`)