Register ServletContextListener in Spring Boot

1. Introduction

Many applications need to perform specific actions during startup and shutdown. The Java Servlet API provides a convenient way to hook into these lifecycle events through the ServletContextListener interface. It receives notifications when the servlet context is created and destroyed, making it a good place for loading configuration data, starting background tasks, or initializing external resources.

While in Java EE applications this listener is typically registered via web.xml or, preferably, annotated with @WebListener, Spring Boot offers alternatives that avoid XML configuration and work with its embedded servlet containers.

In this tutorial, we’ll explore how to register a ServletContextListener in a Spring Boot application. We’ll implement a simple listener using Spring Boot 3.x and the Jakarta Servlet API and examine both annotation-based and programmatic registration methods.

2. Implementing a ServletContextListener

Let’s start by understanding the ServletContextListener. It’s an interface for receiving events about ServletContext lifecycle changes. ServletContextListener allows us to run code when the application starts and when it stops.

Therefore, it defines two callback methods – contextInitialized() and contextDestroyed(). The servlet container calls contextInitialized() when the web application starts and initialize the ServletContext. In contrast, it calls contextDestroyed() when the web application shuts down and is about to close the ServletContext.

To demonstrate, let’s create a simple listener that logs messages on those two events:

public class CustomLifecycleLoggingListener implements ServletContextListener {

    private final Logger log = LoggerFactory.getLogger(CustomLifecycleLoggingListener.class);

    @Override
    public void contextInitialized(ServletContextEvent sce) {
        log.info("Application started");
    }

    @Override
    public void contextDestroyed(ServletContextEvent sce) {
        log.info(" Application stopped");
    }
}

The container calls these methods once per application lifecycle, before and after the web application is active.

Now that we’ve our custom logic in place, let’s see how we can register this listener in a Spring Boot application.

3. Registering in Spring Boot

In a traditional Java EE application, the servlet container detects servlet listeners through the @WebListener annotation. On the other hand, when we run a Spring Boot application as an executable JAR, @WebListener classes aren’t detected automatically. Hence, we need to explicitly register them so that the contextInitialized() and contextDestroyed() methods are invoked.

Spring Boot offers two common ways to do this.

3.1. Using WebListener and ServletComponentScan Annotations

Let’s first use the @WebListener annotation in combination with the @ServletComponentScan.

This requires the Servlet API to be present on the classpath, and Spring Boot includes it automatically when using spring-boot-starter-web. We simply need to put the @WebListener annotation on the listener class and enable servlet component scanning in our Spring Boot application:

@SpringBootApplication
@ServletComponentScan
public class ServletContextListenerApplication {

    public static void main(String[] args) {
        SpringApplication.run(ServletContextListenerApplication.class, args);
    }
}

If we run the application, we can see the configured logs:

...
[main] INFO  o.s.b.w.s.c.ServletWebServerApplicationContext - Root WebApplicationContext: initialization completed in 636 ms
[main] INFO  c.b.s.CustomLifecycleLoggingListener - Application started
[main] DEBUG o.s.w.f.ServerHttpObservationFilter - Filter 'webMvcObservationFilter' configured for use
...

Summing up, this approach is closer to the traditional Java EE style and is a good choice if we want to preserve that familiar pattern.

3.2. Using ServletListenerRegistrationBean

Alternatively, we can register our listener using a ServletListenerRegistrationBean.

This approach avoids servlet annotations and keeps the configuration in Java code. Because it doesn’t rely on Servlet API scanning mechanism, it works even in projects without spring-boot-starter-web. It also supports both executable JAR and WAR deployments without requiring @ServletComponentScan:

@Configuration
public class CustomListenerConfiguration {

    @Bean
    public ServletListenerRegistrationBean<CustomLifecycleLoggingListener> lifecycleListener() {
        return new ServletListenerRegistrationBean<>(new CustomLifecycleLoggingListener());
    }
}

Spring’s component scanning detects the ListenerConfiguration class and registers the ServletListenerRegistrationBean it defines as a Spring bean. During application startup, Spring Boot registers the underlying CustomLifecycleLoggingListener class and calls its contextInitialized() and contextDestroyed() methods at the appropriate points in the application lifecycle.

4. Conclusion

In this article, we explored how to register a ServletContextListener in a Spring Boot application. We implemented a simple listener and demonstrated two registration approaches – using the @WebListener annotation with @ServletComponentScan, and a ServletListenerRegistrationBean.

While the first approach feels familiar if we’re coming from Java EE, it requires servlet component scanning and the Servlet API to be present on the classpath. On the other hand, ServletListenerRegistrationBean is a Spring Boot native way to register listeners. It avoids annotations and doesn’t depend on the Servlet API scanning.

There are also other ways to register listeners, such as manually adding them via servlet initialization code or XML configuration. Still, these are generally not recommended in modern Spring Boot applications. To conclude, if we’re building a new Spring Boot application or migrating code, ServletListenerRegistrationBean is the more flexible and portable option.