Add servlet mapping to dispatch servlet

DispatchServlet is front controller that routes traffic to controllers and various components within Spring. Here I will show how to change the dispatch servlet-mapping in spring boot and servlet 3.0.

Detailed Video Notes

Getting started

A default configured spring boot application wants to serve all content from the root of your application. It will register the dispatchServlet to handle any request from root '/'' if spring context contains only a single Servlet. It does this by using the DispatcherServletAutoConfiguration.class that detects if DispatchServlet.class is on your class path.


Recently I was involved in a project where infrastructure required the need to append multiple servlet mappings to Spring's DispatchServlet. As you may know, the DispatcherServlet is a front controller in Spring MVC that dispatches requests to controllers. In a servlet 2.0 world we would modified the web.xml with a servlet mapping then we would be on our way. Using spring boot and servlet 3.0 it took a bit more understanding and configuration. In this screencast we will show how to override the default DispatchServlet and append multiple servletmappings through java config and servlet 3.0.

Project set up


We will use spring STS to create a project generated from a spring starter project. We will select web and velocity as a style which will include the necessary starter projects in our pom.xml

Modifying dispatchServlet path


The DispatcherServletAutoConfiguration.class will check if a bean named dispatchServlet exist in context, if it does it won't create one. So we will create a @Bean through java config named dispatchServlet to override the default. Next we create a bean that will return a ServletRegistrationBean. A ServletRegistrationBean is a class within spring-boot that allows you to register a servlet within the servlet 3.0 container but it wraps it in a Spring Bean friendly design otherwise you would have to work with ServletRegistration.Dynamic directly.

Within the dispatcherServletRegistration method we will create a ServletRegistrationBean passing in the dispatcherServlet and the URLs we wished to map. The last step before returning the bean is we need to set the name of the servlet. Since DispatcherServletAutoConfiguration contains a name of the bean we will use that constant to set the value.

public DispatcherServlet dispatcherServlet() {
    return new DispatcherServlet();

 * Register dispatcherServlet programmatically
 * @return ServletRegistrationBean
public ServletRegistrationBean dispatcherServletRegistration() {

    ServletRegistrationBean registration = new ServletRegistrationBean(
            dispatcherServlet(), "/levelup/*");


    return registration;

Registering a controller


Lets register a controller for demonstration purposes that will go to /tutorials and will use velocity as a templating engine. If you choose, spring boot currently supports autoconfiguration for velocity, freemarker, thymeleaf and groovy templates that you could plug in place of velocity.

public class TutorialsController {

  public String index (Model model) {

    model.addAttribute("name", "Justin");

    return "tutorials";


Creating a velocity template

Next we will create a template that will used by the TutorialsController index method.

<!DOCTYPE html>
<meta charset="UTF-8">
<title>Java tutorials</title>

hello ${name}


Running the results


We will fire up our server and access http://localhost:8080. You will notice the root of the application doesn't provide a mapping to / the root context anymore. Now with the servlet mapping in place the root is http://localhost:8080/levelup.

Thanks for joining in today’s level up lunch, have a great day!