The DispatcherServlet

Spring’s web MVC framework is, like many other web MVC frameworks, request-driven,designed around a central Servlet that dispatches requests to controllers and offersother functionality that facilitates the development of web applications. Spring’sDispatcherServlet however, does more than just that. It is completely integrated withthe Spring IoC container and as such allows you to use every other feature that Springhas.

The request processing workflow of the Spring Web MVC DispatcherServlet is illustratedin the following diagram. The pattern-savvy reader will recognize that theDispatcherServlet is an expression of the "Front Controller" design pattern (this is apattern that Spring Web MVC shares with many other leading web frameworks).

The request processing workflow in Spring Web MVC (high level)

The DispatcherServlet is an actual Servlet (it inherits from the HttpServlet baseclass), and as such is declared in theweb.xml of your web application. You need tomap requests that you want theDispatcherServlet to handle, by using a URL mapping inthe sameweb.xml file. This is standard Java EE Servlet configuration; the followingexample shows such aDispatcherServlet declaration and mapping:

<web-app>
    <servlet>
        <servlet-name>example</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>example</servlet-name>
        <url-pattern>/example/*</url-pattern>
    </servlet-mapping>

</web-app>

In the preceding example, all requests starting with /example will be handled by theDispatcherServlet instance namedexample. In a Servlet 3.0+ environment, you alsohave the option of configuring the Servlet container programmatically. Below is the codebased equivalent of the aboveweb.xml example:

public class MyWebApplicationInitializer implements WebApplicationInitializer {

    @Override
    public void onStartup(ServletContext container) {
        ServletRegistration.Dynamic registration = container.addServlet("dispatcher", new DispatcherServlet());
        registration.setLoadOnStartup(1);
        registration.addMapping("/example/*");
    }

}

WebApplicationInitializer is an interface provided by Spring MVC that ensures yourcode-based configuration is detected and automatically used to initialize any Servlet 3container. An abstract base class implementation of this interace namedAbstractDispatcherServletInitializer makes it even easier to register theDispatcherServlet by simply specifying its servlet mapping.SeeCode-based Servlet container initialization for more details.

The above is only the first step in setting up Spring Web MVC. You now need to configurethe various beans used by the Spring Web MVC framework (over and above theDispatcherServlet itself).

As detailed in Section 5.15, “Additional Capabilities of the ApplicationContext”, ApplicationContext instances in Spring can bescoped. In the Web MVC framework, eachDispatcherServlet has its ownWebApplicationContext, which inherits all the beans already defined in the rootWebApplicationContext. These inherited beans can be overridden in the servlet-specificscope, and you can define new scope-specific beans local to a given Servlet instance.

Upon initialization of a DispatcherServlet, Spring MVC looks for a file named[servlet-name]-servlet.xml in theWEB-INF directory of your web application andcreates the beans defined there, overriding the definitions of any beans defined withthe same name in the global scope.

Consider the following DispatcherServlet Servlet configuration (in theweb.xml file):

<web-app>
    <servlet>
        <servlet-name>golfing</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>golfing</servlet-name>
        <url-pattern>/golfing/*</url-pattern>
    </servlet-mapping>
</web-app>

With the above Servlet configuration in place, you will need to have a file called/WEB-INF/golfing-servlet.xml in your application; this file will contain all of yourSpring Web MVC-specific components (beans). You can change the exact location of thisconfiguration file through a Servlet initialization parameter (see below for details).

It is also possible to have just one root context for single DispatcherServlet scenariosby setting an empty contextConfigLocation servlet init parameter, as shown below:

<web-app>
    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>/WEB-INF/root-context.xml</param-value>
    </context-param>
    <servlet>
        <servlet-name>dispatcher</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <param-value></param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>dispatcher</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>
</web-app>

The WebApplicationContext is an extension of the plainApplicationContext that hassome extra features necessary for web applications. It differs from a normalApplicationContext in that it is capable of resolving themes (seeSection 17.9, “Using themes”), and that it knows which Servlet it is associated with (by havinga link to theServletContext). The WebApplicationContext is bound in theServletContext, and by using static methods on theRequestContextUtils class you canalways look up the WebApplicationContext if you need access to it