Understand web.xml in Spring MVC project

The deployment descriptor file web.xml is the entry point to understand all configurations for a Spring MVC project.

In many cases, there are 2 type of  xml configuration files in a Spring MVC project:

• web.xml – Describe how to deploy the web application to any Java Servlet container.
• context configuration xml – Configuration file to create Spring Application context, one or more.  

1. What is web.xml

The /WEB-INF/web.xml file is used to define how to deploy the web module to a Servlet container like JBoss, Tomcat, Glassfish or any other servlet container. It’s defined by Sun since Java 1.4 ( or 1.2?  not  so sure) and part of the Java Servlet specification. The file name and locations can not be changed.

Basically web.xml tell container all servlets in the web application with <servlet> element , then tell container when to use which servlet by the url mapping  with <servlet-mapping> element.

Here is a reference of all elements in web.xml from Oracle WebLogic  document.

In Spring MVC project, for most cast, there is only one servlet org.springframework.web.servlet.DispatcherServlet. Let this DispatcherServlet handle all the requests. After container hands over the request to DispatcherServlet, the income http request formally enters the Spring world.  A controller will be chosen to handle the request according to @RequestMapping.

2. What is context configuration xml

In XML style configured Spring MVC project, there will be at least one xml to configure Spring MVC WebApplicatonContext. As Spring document says, there are 2 type of WebApplicationContext:

• Root WebApplicationContext
• Servlet WebApplicationContext

All servlets, althrough in most case only one DispatcherServlet, share root context. Each Servlet has its private context. Spring tries to locate a bean first in Servlet context, if not found, then search root context. A Spring MVC project can use both or just any one of them. In practical there really isn’t much difference between which context(s) is used.

The default configuration file for root WebApplicatonContext is /WEB-INF/applicationContext.xml

The default configuration file for servlet WebApplicatonContext is /WEB-INF/[servletName]-servlet.xml

The files’ name and location can be changed in web.xml.

3. More details with demo project

This is the directory hierarchy of the demo project.

It’s created in Eclipse as maven project with simple “maven-archetype-webapp” archetype.

In this demo, both root context and servlet private context are used just for demo. Service/Repository beans are registered in root context. Controller beans are registered in servlet private context. Define all beans in just one context is fine also.

The root context configuration file applicationContext.xml list below:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:beans="http://www.springframework.org/schema/beans"
  xmlns:context="http://www.springframework.org/schema/context"
  xsi:schemaLocation="
    http://www.springframework.org/schema/beans 
    http://www.springframework.org/schema/beans/spring-beans.xsd 
    http://www.springframework.org/schema/context 
    http://www.springframework.org/schema/context/spring-context.xsd">

  <!-- register service/persistence beans in root context -->
  <context:component-scan base-package="com.shengwang.demo.service" />
  
</beans>

The servlet private context configuration file dispatcher-servlet.xml list below:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:beans="http://www.springframework.org/schema/beans"
  xmlns:context="http://www.springframework.org/schema/context" 
  xsi:schemaLocation="
    http://www.springframework.org/schema/beans 
    http://www.springframework.org/schema/beans/spring-beans.xsd 
    http://www.springframework.org/schema/context 
    http://www.springframework.org/schema/context/spring-context.xsd">

  <!-- register controller in servlet private context -->
  <context:component-scan base-package="com.shengwang.demo.controller"/>  
  
</beans>

These 2 spring configuration are just for demo. In real use you need more configuration in them like persistence, security, etc.

The web.xml list below:

<web-app xmlns="http://java.sun.com/xml/ns/javaee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
        http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
        version="3.0">
  <display-name>Demo for understanding web.xml of spring mvc project</display-name>
  
  <!-- ===================================================== -->
  <!--  1. Create root context with spring listener          -->
  <!--     Remove this means only use servlet contxt         -->
  <!-- ===================================================== -->
  <listener>
    <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
  </listener>
  
  <!-- ===================================================== -->
  <!-- Can modify default root context config file           -->
  <!-- ===================================================== -->
  <!-- 
  <context-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>/WEB-INF/root-context.xml</param-value>
  </context-param>
   -->


  <!-- ===================================================== -->
  <!--  2. Define servlet with private context               -->
  <!-- ===================================================== -->
  <servlet>
    <servlet-name>dispatcher</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <!-- ================================================= -->
    <!-- Set contextConfigLocation to empty                -->
    <!-- means only use root context                       -->
    <!-- ================================================= -->
    <!--
    <init-param>
      <param-name>contextConfigLocation</param-name>
      <param-value></param-value>
    </init-param>
     -->
    <load-on-startup>1</load-on-startup>
  </servlet>
  <!-- ===================================================== -->
  <!-- One servlet, the dispatcher, to rule it all           -->
  <!-- ===================================================== -->
  <servlet-mapping>
    <servlet-name>dispatcher</servlet-name>
    <url-pattern>/</url-pattern>
  </servlet-mapping>

</web-app>

The listener ContextLoaderListener is used to create root WebApplicationContext, <context-param>can be used to change config file location. 

<servlet> and <servlet-mapping>  work in pairs. The only servlet in this demo is named dispatcher, so the default servlet private context file is /WEB-INF/dispatcher-servlet.xml, it will handle all income request because its url-pattern is “/”, which means it’s the default servlet for all request not handled by other servlets. Since there is only one  servlet dispatcher, so in fact it will handle all requests.