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

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:
    Aware, ApplicationContextAware, Ordered, ServletContextAware, HandlerMapping
  Direct Known Subclasses:
    AbstractDetectingUrlHandlerMapping, SimpleUrlHandlerMapping

      public abstract class AbstractUrlHandlerMapping
      extends AbstractHandlerMapping

  Abstract base class for URL-mapped `HandlerMapping` implementations. Provides infrastructure for mapping handlers to URLs and configurable URL lookup. For information on the latter, see "alwaysUseFullPath" property.

  Supports direct matches, e.g. a registered "/test" matches "/test", and various Ant-style pattern matches, e.g. a registered "/t*" pattern matches both "/test" and "/team", "/test/*" matches all paths in the "/test" directory, "/test/**" matches all paths below "/test". For details, see the `AntPathMatcher` javadoc.

  Will search all path patterns to find the most exact match for the current request path. The most exact match is defined as 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.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
    `AbstractUrlHandlerMapping()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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.
    `Map<String,Object>` | `getHandlerMap()` Return the registered handlers as an unmodifiable Map, with the registered path as key and the handler object (or handler bean name in case of a lazy-init handler) as value.
    `Object` | `getRootHandler()` Return the root handler for this handler mapping (registered for "/"), or `null` if none.
    `protected Object` | `lookupHandler(String urlPath, HttpServletRequest request)` Look up a handler instance for the given URL path.
    `protected void` | `registerHandler(String[] urlPaths, String beanName)` Register the specified handler for the given URL paths.
    `protected 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` | `setRootHandler(Object rootHandler)` Set the root handler for this handler mapping, that is, the handler to be registered for the root path ("/").
    `protected boolean` | `supportsTypeLevelMappings()` Indicates whether this handler mapping support type-level mappings.
    `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, getAdaptedInterceptors, getDefaultHandler, getHandler, getHandlerExecutionChain, getMappedInterceptors, getOrder, getPathMatcher, getUrlPathHelper, initApplicationContext, initInterceptors, setAlwaysUseFullPath, setDefaultHandler, setInterceptors, setOrder, setPathMatcher, setRemoveSemicolonContent, setUrlDecode, setUrlPathHelper`

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

    - #### AbstractUrlHandlerMapping

          public AbstractUrlHandlerMapping()

  - ### Method Detail

    - #### setRootHandler

          public void setRootHandler(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

          public Object getRootHandler()

      Return the root handler for this handler mapping (registered for "/"), or `null` if none.

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

    - #### getHandlerInternal

          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

          protected Object lookupHandler(String urlPath,
                             HttpServletRequest request)
                                  throws Exception

      Look up a handler instance for the given URL path.

      Supports direct matches, e.g. a registered "/test" matches "/test", and various Ant-style pattern matches, e.g. a registered "/t*" matches both "/test" and "/team". For details, see the AntPathMatcher class.

      Looks for the most exact pattern, where most exact is defined as the longest path pattern.

      Parameters:
        `urlPath` - URL the bean is mapped to
        `request` - current HTTP request (to expose the path within the mapping to)
      Returns:
        the associated handler instance, or `null` if not found
      Throws:
        `Exception`
      See Also:
        `exposePathWithinMapping(java.lang.String, java.lang.String, javax.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,
                                        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`

    - #### registerHandler

          protected void registerHandler(String[] urlPaths,
                             String beanName)
                                  throws 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:
        `BeansException` - if the handler couldn't be registered
        `IllegalStateException` - if there is a conflicting handler registered

    - #### registerHandler

          protected void registerHandler(String urlPath,
                             Object handler)
                                  throws 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:
        `BeansException` - if the handler couldn't be registered
        `IllegalStateException` - if there is a conflicting handler registered

    - #### getHandlerMap

          public final Map<String,Object> getHandlerMap()

      Return the registered handlers as an unmodifiable Map, with the registered path as key and the handler object (or handler bean name in case of a lazy-init handler) as value.
      See Also:
        `AbstractHandlerMapping.getDefaultHandler()`

    - #### supportsTypeLevelMappings

          protected boolean supportsTypeLevelMappings()

      Indicates whether this handler mapping support type-level mappings. Default to `false`.