AbstractHandlerMapping (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

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, ApplicationContextAware, Ordered, ServletContextAware, HandlerMapping
  Direct Known Subclasses:
    AbstractHandlerMethodMapping, AbstractUrlHandlerMapping

      public abstract class AbstractHandlerMapping
      extends WebApplicationObjectSupport
      implements HandlerMapping, Ordered

  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)`, `setAlwaysUseFullPath(boolean)`, `setUrlDecode(boolean)`, `AntPathMatcher`, `setInterceptors(java.lang.Object[])`, `HandlerInterceptor`

- - ### Field Summary

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

      `logger`

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

      `BEST_MATCHING_PATTERN_ATTRIBUTE, INTROSPECT_TYPE_LEVEL_MAPPING, 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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected HandlerInterceptor` | `adaptInterceptor(Object interceptor)` Adapt the given interceptor object to the HandlerInterceptor interface.
    `protected void` | `detectMappedInterceptors(List<MappedInterceptor> mappedInterceptors)` Detects beans of type `MappedInterceptor` and adds 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 HandlerInterceptor[]` | `getAdaptedInterceptors()` Return the adapted interceptors as HandlerInterceptor array.
    `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()` Return the order value of this object, with a higher value meaning greater in terms of sorting.
    `PathMatcher` | `getPathMatcher()` Return the PathMatcher implementation to use for matching URL paths against registered URL patterns.
    `UrlPathHelper` | `getUrlPathHelper()` Return the UrlPathHelper implementation to use for resolution of lookup paths.
    `protected void` | `initApplicationContext()` Initializes the interceptors.
    `protected void` | `initInterceptors()` Initialize the specified interceptors, checking for `MappedInterceptor`s and adapting HandlerInterceptors where necessary.
    `void` | `setAlwaysUseFullPath(boolean alwaysUseFullPath)` Set if URL lookup should always use the full path within the current servlet context.
    `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)` Set the PathMatcher implementation to use for matching URL paths against registered URL patterns.
    `void` | `setRemoveSemicolonContent(boolean removeSemicolonContent)` Set if ";" (semicolon) content should be stripped from the request URI.
    `void` | `setUrlDecode(boolean urlDecode)` Set if context path and request URI should be URL-decoded.
    `void` | `setUrlPathHelper(UrlPathHelper urlPathHelper)` Set the UrlPathHelper to use for resolution of lookup paths.

    - ### 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, requiredContextClass, setApplicationContext`

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

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

- - ### Constructor Detail

    - #### AbstractHandlerMapping

          public AbstractHandlerMapping()

  - ### Method Detail

    - #### setOrder

          public final void setOrder(int order)

      Specify the order value for this HandlerMapping bean.

      Default value is `Integer.MAX_VALUE`, meaning that it's non-ordered.

      See Also:
        `Ordered.getOrder()`

    - #### getOrder

          public final int getOrder()

      Description copied from interface: `Ordered`
      Return the order value of this object, with a higher value meaning greater in terms of sorting.

      Normally starting with 0, with `Integer.MAX_VALUE` indicating the greatest value. Same order values will result in arbitrary positions for the affected objects.

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

      Specified by:
        `getOrder` in interface `Ordered`
      Returns:
        the order value

    - #### setDefaultHandler

          public void setDefaultHandler(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 Object getDefaultHandler()

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

    - #### setAlwaysUseFullPath

          public void setAlwaysUseFullPath(boolean alwaysUseFullPath)

      Set if URL lookup should always use the full path within the current servlet context. Else, the path within the current servlet mapping is used if applicable (that is, in the case of a ".../*" servlet mapping in web.xml).

      Default is "false".

      See Also:
        `UrlPathHelper.setAlwaysUseFullPath(boolean)`

    - #### setUrlDecode

          public void setUrlDecode(boolean urlDecode)

      Set if context path and request URI should be URL-decoded. Both are returned undecoded by the Servlet API, in contrast to the servlet path.

      Uses either the request encoding or the default encoding according to the Servlet spec (ISO-8859-1).

      See Also:
        `UrlPathHelper.setUrlDecode(boolean)`

    - #### setRemoveSemicolonContent

          public void setRemoveSemicolonContent(boolean removeSemicolonContent)

      Set if ";" (semicolon) content should be stripped from the request URI.
      See Also:
        `UrlPathHelper.setRemoveSemicolonContent(boolean)`

    - #### setUrlPathHelper

          public void setUrlPathHelper(UrlPathHelper urlPathHelper)

      Set the UrlPathHelper to use for resolution of lookup paths.

      Use this to override the default UrlPathHelper with a custom subclass, or to share common UrlPathHelper settings across multiple HandlerMappings and MethodNameResolvers.

    - #### getUrlPathHelper

          public UrlPathHelper getUrlPathHelper()

      Return the UrlPathHelper implementation to use for resolution of lookup paths.

    - #### setPathMatcher

          public void setPathMatcher(PathMatcher pathMatcher)

      Set the PathMatcher implementation to use for matching URL paths against registered URL patterns. Default is AntPathMatcher.
      See Also:
        `AntPathMatcher`

    - #### getPathMatcher

          public PathMatcher getPathMatcher()

      Return the PathMatcher implementation to use for matching URL paths against registered URL patterns.

    - #### 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, or `null` if none
      See Also:
        `adaptInterceptor(java.lang.Object)`, `HandlerInterceptor`, `WebRequestInterceptor`

    - #### 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<MappedInterceptor> mappedInterceptors)

      Detects beans of type `MappedInterceptor` and adds them to the list of mapped interceptors. This is done in addition to any `MappedInterceptor`s that may have been provided via `setInterceptors(Object[])`. Subclasses can override this method to change that.
      Parameters:
        `mappedInterceptors` - an empty list to add MappedInterceptor types to

    - #### initInterceptors

          protected void initInterceptors()

      Initialize the specified interceptors, checking for `MappedInterceptor`s and adapting HandlerInterceptors where necessary.
      See Also:
        `setInterceptors(java.lang.Object[])`, `adaptInterceptor(java.lang.Object)`

    - #### adaptInterceptor

          protected HandlerInterceptor adaptInterceptor(Object interceptor)

      Adapt the given interceptor object to the HandlerInterceptor interface.

      Supported interceptor types are HandlerInterceptor and WebRequestInterceptor. Each given WebRequestInterceptor will be wrapped in a WebRequestHandlerInterceptorAdapter. Can be overridden in subclasses.

      Parameters:
        `interceptor` - the specified interceptor object
      Returns:
        the interceptor wrapped as HandlerInterceptor
      See Also:
        `HandlerInterceptor`, `WebRequestInterceptor`, `WebRequestHandlerInterceptorAdapter`

    - #### getAdaptedInterceptors

          protected final HandlerInterceptor[] getAdaptedInterceptors()

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

    - #### getMappedInterceptors

          protected final MappedInterceptor[] getMappedInterceptors()

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

    - #### getHandler

          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

          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.

      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

    - #### getHandlerExecutionChain

          protected HandlerExecutionChain getHandlerExecutionChain(Object handler,
                                                       HttpServletRequest request)

      Build a HandlerExecutionChain for the given handler, including applicable interceptors.

      The default implementation simply builds a standard HandlerExecutionChain with the given handler, the handler mapping's common interceptors, and any `MappedInterceptor`s matching to the current request URL. 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, consider calling `super.getHandlerExecutionChain` 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()`