Documentation Home

Using a web.xml

If you follow the instructions for Deploying a .war File then you will notice that you did not create a web.xml. This is because the Servlet 3.0 spec calls for bootstrapping the servlet context by classpath scanning and only requires an implementation of a ServletContextInitializer.

This classpath scanning can conflict with the Broadleaf class transformation (like in later versions of Tomcat 7) and it is sometimes necessary to create a web.xml even in a Servlet 3.0 container to disable this scanning.

To take advantage of this, first follow the instructions for deploying a .war file, with one difference. Instead of extending from the SpringBootServletInitializer, instead extend from the BroadleafBootServletContextInitializer.

Example final @SpringBootApplication class:

package com.mycompany.admin;

public class AdminApplication extends BroadleafBootServletContextInitializer {

    public static class BroadleafFrameworkConfiguration {}

    public static void main(String[] args) {, args);

    protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
        return application.sources(AdminApplication.class);


Then create the following src/main/webapp/WEB-INF/web.xml that disables the scanning and bootstraps the context:

<?xml version="1.0" encoding="UTF-8"?>
    xsi:schemaLocation=" ">

    <!-- Disable any ServletContextInitializer scanning -->
    <absolute-ordering />



Finally, since we have manually specified a ServletContextListener within web.xml, Tomcat and other servlet containers do not allow you to add more listeners programmatically. Thus, you must disable the automatic registration of these listeners if you have anydefined as beans within your project and instead define them directly within this web.xml.