org.springframework.web.servlet

Class DispatcherServlet

  • All Implemented Interfaces:
    java.io.Serializable, Servlet, ServletConfig, Aware, ApplicationContextAware, EnvironmentAware, EnvironmentCapable


    public class DispatcherServlet
    extends FrameworkServlet
    Central dispatcher for HTTP request handlers/controllers, e.g. for web UI controllers or HTTP-based remote service exporters. Dispatches to registered handlers for processing a web request, providing convenient mapping and exception handling facilities.

    This servlet is very flexible: It can be used with just about any workflow, with the installation of the appropriate adapter classes. It offers the following functionality that distinguishes it from other request-driven web MVC frameworks:

    • It is based around a JavaBeans configuration mechanism.
    • It can use any HandlerMapping implementation - pre-built or provided as part of an application - to control the routing of requests to handler objects. Default is BeanNameUrlHandlerMapping and RequestMappingHandlerMapping. HandlerMapping objects can be defined as beans in the servlet's application context, implementing the HandlerMapping interface, overriding the default HandlerMapping if present. HandlerMappings can be given any bean name (they are tested by type).
    • It can use any HandlerAdapter; this allows for using any handler interface. Default adapters are HttpRequestHandlerAdapter, SimpleControllerHandlerAdapter, for Spring's HttpRequestHandler and Controller interfaces, respectively. A default RequestMappingHandlerAdapter will be registered as well. HandlerAdapter objects can be added as beans in the application context, overriding the default HandlerAdapters. Like HandlerMappings, HandlerAdapters can be given any bean name (they are tested by type).
    • The dispatcher's exception resolution strategy can be specified via a HandlerExceptionResolver, for example mapping certain exceptions to error pages. Default are ExceptionHandlerExceptionResolver, ResponseStatusExceptionResolver, and DefaultHandlerExceptionResolver. These HandlerExceptionResolvers can be overridden through the application context. HandlerExceptionResolver can be given any bean name (they are tested by type).
    • Its view resolution strategy can be specified via a ViewResolver implementation, resolving symbolic view names into View objects. Default is InternalResourceViewResolver. ViewResolver objects can be added as beans in the application context, overriding the default ViewResolver. ViewResolvers can be given any bean name (they are tested by type).
    • If a View or view name is not supplied by the user, then the configured RequestToViewNameTranslator will translate the current request into a view name. The corresponding bean name is "viewNameTranslator"; the default is DefaultRequestToViewNameTranslator.
    • The dispatcher's strategy for resolving multipart requests is determined by a MultipartResolver implementation. Implementations for Apache Commons FileUpload and Servlet 3 are included; the typical choice is CommonsMultipartResolver. The MultipartResolver bean name is "multipartResolver"; default is none.
    • Its locale resolution strategy is determined by a LocaleResolver. Out-of-the-box implementations work via HTTP accept header, cookie, or session. The LocaleResolver bean name is "localeResolver"; default is AcceptHeaderLocaleResolver.
    • Its theme resolution strategy is determined by a ThemeResolver. Implementations for a fixed theme and for cookie and session storage are included. The ThemeResolver bean name is "themeResolver"; default is FixedThemeResolver.

    NOTE: The @RequestMapping annotation will only be processed if a corresponding HandlerMapping (for type-level annotations) and/or HandlerAdapter (for method-level annotations) is present in the dispatcher. This is the case by default. However, if you are defining custom HandlerMappings or HandlerAdapters, then you need to make sure that a corresponding custom RequestMappingHandlerMapping and/or RequestMappingHandlerAdapter is defined as well - provided that you intend to use @RequestMapping.

    A web application can define any number of DispatcherServlets. Each servlet will operate in its own namespace, loading its own application context with mappings, handlers, etc. Only the root application context as loaded by ContextLoaderListener, if any, will be shared.

    As of Spring 3.1, DispatcherServlet may now be injected with a web application context, rather than creating its own internally. This is useful in Servlet 3.0+ environments, which support programmatic registration of servlet instances. See the DispatcherServlet(WebApplicationContext) javadoc for details.

    Author:
    Rod Johnson, Juergen Hoeller, Rob Harrop, Chris Beams, Rossen Stoyanchev
    See Also:
    HttpRequestHandler, Controller, ContextLoaderListener, Serialized Form
    • Field Detail

      • MULTIPART_RESOLVER_BEAN_NAME

        public static final java.lang.String MULTIPART_RESOLVER_BEAN_NAME
        Well-known name for the MultipartResolver object in the bean factory for this namespace.
        See Also:
        Constant Field Values
      • LOCALE_RESOLVER_BEAN_NAME

        public static final java.lang.String LOCALE_RESOLVER_BEAN_NAME
        Well-known name for the LocaleResolver object in the bean factory for this namespace.
        See Also:
        Constant Field Values
      • THEME_RESOLVER_BEAN_NAME

        public static final java.lang.String THEME_RESOLVER_BEAN_NAME
        Well-known name for the ThemeResolver object in the bean factory for this namespace.
        See Also:
        Constant Field Values
      • HANDLER_MAPPING_BEAN_NAME

        public static final java.lang.String HANDLER_MAPPING_BEAN_NAME
        Well-known name for the HandlerMapping object in the bean factory for this namespace. Only used when "detectAllHandlerMappings" is turned off.
        See Also:
        setDetectAllHandlerMappings(boolean), Constant Field Values
      • HANDLER_ADAPTER_BEAN_NAME

        public static final java.lang.String HANDLER_ADAPTER_BEAN_NAME
        Well-known name for the HandlerAdapter object in the bean factory for this namespace. Only used when "detectAllHandlerAdapters" is turned off.
        See Also:
        setDetectAllHandlerAdapters(boolean), Constant Field Values
      • HANDLER_EXCEPTION_RESOLVER_BEAN_NAME

        public static final java.lang.String HANDLER_EXCEPTION_RESOLVER_BEAN_NAME
        Well-known name for the HandlerExceptionResolver object in the bean factory for this namespace. Only used when "detectAllHandlerExceptionResolvers" is turned off.
        See Also:
        setDetectAllHandlerExceptionResolvers(boolean), Constant Field Values
      • REQUEST_TO_VIEW_NAME_TRANSLATOR_BEAN_NAME

        public static final java.lang.String REQUEST_TO_VIEW_NAME_TRANSLATOR_BEAN_NAME
        Well-known name for the RequestToViewNameTranslator object in the bean factory for this namespace.
        See Also:
        Constant Field Values
      • VIEW_RESOLVER_BEAN_NAME

        public static final java.lang.String VIEW_RESOLVER_BEAN_NAME
        Well-known name for the ViewResolver object in the bean factory for this namespace. Only used when "detectAllViewResolvers" is turned off.
        See Also:
        setDetectAllViewResolvers(boolean), Constant Field Values
      • FLASH_MAP_MANAGER_BEAN_NAME

        public static final java.lang.String FLASH_MAP_MANAGER_BEAN_NAME
        Well-known name for the FlashMapManager object in the bean factory for this namespace.
        See Also:
        Constant Field Values
      • INPUT_FLASH_MAP_ATTRIBUTE

        public static final java.lang.String INPUT_FLASH_MAP_ATTRIBUTE
        Name of request attribute that holds a read-only Map<String,?> with "input" flash attributes saved by a previous request, if any.
        See Also:
        RequestContextUtils.getInputFlashMap(HttpServletRequest)
      • EXCEPTION_ATTRIBUTE

        public static final java.lang.String EXCEPTION_ATTRIBUTE
        Name of request attribute that exposes an Exception resolved with an HandlerExceptionResolver but where no view was rendered (e.g. setting the status code).
      • PAGE_NOT_FOUND_LOG_CATEGORY

        public static final java.lang.String PAGE_NOT_FOUND_LOG_CATEGORY
        Log category to use when no mapped handler is found for a request.
        See Also:
        Constant Field Values
      • pageNotFoundLogger

        protected static final Log pageNotFoundLogger
        Additional logger to use when no mapped handler is found for a request.
    • Method Detail

      • setDetectAllHandlerMappings

        public void setDetectAllHandlerMappings(boolean detectAllHandlerMappings)
        Set whether to detect all HandlerMapping beans in this servlet's context. Otherwise, just a single bean with name "handlerMapping" will be expected.

        Default is "true". Turn this off if you want this servlet to use a single HandlerMapping, despite multiple HandlerMapping beans being defined in the context.

      • setDetectAllHandlerAdapters

        public void setDetectAllHandlerAdapters(boolean detectAllHandlerAdapters)
        Set whether to detect all HandlerAdapter beans in this servlet's context. Otherwise, just a single bean with name "handlerAdapter" will be expected.

        Default is "true". Turn this off if you want this servlet to use a single HandlerAdapter, despite multiple HandlerAdapter beans being defined in the context.

      • setDetectAllHandlerExceptionResolvers

        public void setDetectAllHandlerExceptionResolvers(boolean detectAllHandlerExceptionResolvers)
        Set whether to detect all HandlerExceptionResolver beans in this servlet's context. Otherwise, just a single bean with name "handlerExceptionResolver" will be expected.

        Default is "true". Turn this off if you want this servlet to use a single HandlerExceptionResolver, despite multiple HandlerExceptionResolver beans being defined in the context.

      • setDetectAllViewResolvers

        public void setDetectAllViewResolvers(boolean detectAllViewResolvers)
        Set whether to detect all ViewResolver beans in this servlet's context. Otherwise, just a single bean with name "viewResolver" will be expected.

        Default is "true". Turn this off if you want this servlet to use a single ViewResolver, despite multiple ViewResolver beans being defined in the context.

      • setThrowExceptionIfNoHandlerFound

        public void setThrowExceptionIfNoHandlerFound(boolean throwExceptionIfNoHandlerFound)
        Set whether to throw a NoHandlerFoundException when no Handler was found for this request. This exception can then be caught with a HandlerExceptionResolver or an @ExceptionHandler controller method.

        Note that if DefaultServletHttpRequestHandler is used, then requests will always be forwarded to the default servlet and a NoHandlerFoundException would never be thrown in that case.

        Default is "false", meaning the DispatcherServlet sends a NOT_FOUND error through the Servlet response.

        Since:
        4.0
      • setCleanupAfterInclude

        public void setCleanupAfterInclude(boolean cleanupAfterInclude)
        Set whether to perform cleanup of request attributes after an include request, that is, whether to reset the original state of all request attributes after the DispatcherServlet has processed within an include request. Otherwise, just the DispatcherServlet's own request attributes will be reset, but not model attributes for JSPs or special attributes set by views (for example, JSTL's).

        Default is "true", which is strongly recommended. Views should not rely on request attributes having been set by (dynamic) includes. This allows JSP views rendered by an included controller to use any model attributes, even with the same names as in the main JSP, without causing side effects. Only turn this off for special needs, for example to deliberately allow main JSPs to access attributes from JSP views rendered by an included controller.

      • initStrategies

        protected void initStrategies(ApplicationContext context)
        Initialize the strategy objects that this servlet uses.

        May be overridden in subclasses in order to initialize further strategy objects.

      • getThemeSource

        @Nullable
        public final ThemeSource getThemeSource()
        Return this servlet's ThemeSource, if any; else return null.

        Default is to return the WebApplicationContext as ThemeSource, provided that it implements the ThemeSource interface.

        Returns:
        the ThemeSource, if any
        See Also:
        FrameworkServlet.getWebApplicationContext()
      • getMultipartResolver

        @Nullable
        public final MultipartResolver getMultipartResolver()
        Obtain this servlet's MultipartResolver, if any.
        Returns:
        the MultipartResolver used by this servlet, or null if none (indicating that no multipart support is available)
      • getHandlerMappings

        @Nullable
        public final java.util.List<HandlerMapping> getHandlerMappings()
        Return the configured HandlerMapping beans that were detected by type in the WebApplicationContext or initialized based on the default set of strategies from DispatcherServlet.properties.

        Note: This method may return null if invoked prior to onRefresh(ApplicationContext).

        Returns:
        an immutable list with the configured mappings, or null if not initialized yet
        Since:
        5.0
      • getDefaultStrategies

        protected <T> java.util.List<T> getDefaultStrategies(ApplicationContext context,
                                                             java.lang.Class<T> strategyInterface)
        Create a List of default strategy objects for the given strategy interface.

        The default implementation uses the "DispatcherServlet.properties" file (in the same package as the DispatcherServlet class) to determine the class names. It instantiates the strategy objects through the context's BeanFactory.

        Parameters:
        context - the current WebApplicationContext
        strategyInterface - the strategy interface
        Returns:
        the List of corresponding strategy objects
      • doDispatch

        protected void doDispatch(HttpServletRequest request,
                                  HttpServletResponse response)
                           throws java.lang.Exception
        Process the actual dispatching to the handler.

        The handler will be obtained by applying the servlet's HandlerMappings in order. The HandlerAdapter will be obtained by querying the servlet's installed HandlerAdapters to find the first that supports the handler class.

        All HTTP methods are handled by this method. It's up to HandlerAdapters or handlers themselves to decide which methods are acceptable.

        Parameters:
        request - current HTTP request
        response - current HTTP response
        Throws:
        java.lang.Exception - in case of any kind of processing failure
      • getHandler

        @Nullable
        protected HandlerExecutionChain getHandler(HttpServletRequest request)
                                                      throws java.lang.Exception
        Return the HandlerExecutionChain for this request.

        Tries all handler mappings in order.

        Parameters:
        request - current HTTP request
        Returns:
        the HandlerExecutionChain, or null if no handler could be found
        Throws:
        java.lang.Exception
      • noHandlerFound

        protected void noHandlerFound(HttpServletRequest request,
                                      HttpServletResponse response)
                               throws java.lang.Exception
        No handler found -> set appropriate HTTP response status.
        Parameters:
        request - current HTTP request
        response - current HTTP response
        Throws:
        java.lang.Exception - if preparing the response failed
      • getHandlerAdapter

        protected HandlerAdapter getHandlerAdapter(java.lang.Object handler)
                                            throws ServletException
        Return the HandlerAdapter for this handler object.
        Parameters:
        handler - the handler object to find an adapter for
        Throws:
        ServletException - if no HandlerAdapter can be found for the handler. This is a fatal error.
      • processHandlerException

        @Nullable
        protected ModelAndView processHandlerException(HttpServletRequest request,
                                                                 HttpServletResponse response,
                                                                 @Nullable
                                                                 java.lang.Object handler,
                                                                 java.lang.Exception ex)
                                                          throws java.lang.Exception
        Determine an error ModelAndView via the registered HandlerExceptionResolvers.
        Parameters:
        request - current HTTP request
        response - current HTTP response
        handler - the executed handler, or null if none chosen at the time of the exception (for example, if multipart resolution failed)
        ex - the exception that got thrown during handler execution
        Returns:
        a corresponding ModelAndView to forward to
        Throws:
        java.lang.Exception - if no error ModelAndView found
      • render

        protected void render(ModelAndView mv,
                              HttpServletRequest request,
                              HttpServletResponse response)
                       throws java.lang.Exception
        Render the given ModelAndView.

        This is the last stage in handling a request. It may involve resolving the view by name.

        Parameters:
        mv - the ModelAndView to render
        request - current HTTP servlet request
        response - current HTTP servlet response
        Throws:
        ServletException - if view is missing or cannot be resolved
        java.lang.Exception - if there's a problem rendering the view
      • getDefaultViewName

        @Nullable
        protected java.lang.String getDefaultViewName(HttpServletRequest request)
                                                         throws java.lang.Exception
        Translate the supplied request into a default view name.
        Parameters:
        request - current HTTP servlet request
        Returns:
        the view name (or null if no default found)
        Throws:
        java.lang.Exception - if view name translation failed
      • resolveViewName

        @Nullable
        protected View resolveViewName(java.lang.String viewName,
                                                 @Nullable
                                                 java.util.Map<java.lang.String,java.lang.Object> model,
                                                 java.util.Locale locale,
                                                 HttpServletRequest request)
                                          throws java.lang.Exception
        Resolve the given view name into a View object (to be rendered).

        The default implementations asks all ViewResolvers of this dispatcher. Can be overridden for custom resolution strategies, potentially based on specific model attributes or request parameters.

        Parameters:
        viewName - the name of the view to resolve
        model - the model to be passed to the view
        locale - the current locale
        request - current HTTP servlet request
        Returns:
        the View object, or null if none found
        Throws:
        java.lang.Exception - if the view cannot be resolved (typically in case of problems creating an actual View object)
        See Also:
        ViewResolver.resolveViewName(java.lang.String, java.util.Locale)