Default welcome page with Tomcat and Spring MVC

In my professional development, I felt that I had always neglected the field of web aplication development. To correct this I’ve started a little side project with Spring MVC, a web application to help a Toastmasters club’s Vice-President Education with their duties.

Between the official documentation and the Spring in Action book, I found the documentation on Spring MVC more than satisfactory.

I wanted my webapp to display a default, welcome page. And just for extra points, I wanted to use the Velocity framework instead of the default Java Server Pages.

So I defined my web.xml file thus:

<web-app>
  <display-name><a class="zem_slink" href="http://www.toastmasters.org/" title="Toastmasters International" rel="homepage">Toastmasters International</a> - Education Assistant</display-name>

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

  <servlet-mapping>
    <servlet-name>tmi-education</servlet-name>
    <url-pattern>*.htm</url-pattern>
  </servlet-mapping>

  <welcome-file-list>
    <welcome-file>home.htm</welcome-file>
  </welcome-file-list>

</web-app>

And the Spring configuration file looks like the following:

<beans>
  <bean id="velocityConfig" class="org.springframework.web.servlet.view.velocity.VelocityConfigurer">
    <property name="resourceLoaderPath" value="/WEB-INF/velocity/">
  </property>
  <bean id="viewResolver" class="org.springframework.web.servlet.view.velocity.VelocityViewResolver">
    <property name="suffix" value=".vm">
  </property>

  <bean id="urlMapping" class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
    <property name="mappings">
      <props>
        <prop key="/home.htm">/home.htm</prop>
      </props>
    </property>
  </bean>

  <bean name="/home.htm" class="org.springframework.web.servlet.mvc.UrlFilenameViewController">
  </bean>
</bean>

With this setup, any URL whose filename ends with .htm should be mapped to a .vm velocity template, looked up from the WEB-INF/velocity directory. In particular, /home.htm is served based on the home.vm template.

And yet, when I point the browser to the root URL http://localhost:8080/tmi-education, I don’t see the default page. All I get is a 404 error message. Even more surprisingly, http://localhost:8080/tmi-education/home.htm works perfectly.

So why wasn’t Tomcat serving up the right welcome page? After much fiddling, and based on examples from this blog post, I finally found that you must include the following snippet in your web.xml file (at least under Apache Tomcat/6.0.18):

<servlet-mapping>
  <servlet-name>tmi-education</servlet-name>
  <url-pattern>/home.htm</url-pattern>
</servlet-mapping>

With this in place, the default welcome page works right.