Mastering Servlet Registration in Spring Boot 2.3.9: From Annotations to Dynamic Registration

1. Servlet Registration

Method 1: Add

@ServletComponentScan

on the configuration class and annotate the servlet class with

@WebServlet("/hello")

. Corresponding annotations for filter and listener are

@WebFilter

and

@WebListener

.

<code>@SpringBootApplication
@ServletComponentScan
public class SpringBootComprehensiveApplication { }</code>

<code>@WebServlet("/hello")
public class MyServlet extends HttpServlet { }</code>

Method 2: Register a

ServletRegistrationBean

in a @Bean method, allowing injection of other beans and access to application properties.

<code>@Bean
public ServletRegistrationBean&lt;MyServlet&gt; servlet() {
    ServletRegistrationBean&lt;MyServlet&gt; servlet = new ServletRegistrationBean<>(new MyServlet());
    servlet.addUrlMappings("/hello");
    return servlet;
}</code>

Method 3: Dynamically register a servlet by implementing

ServletContextInitializer

(available since Servlet 3.0).

<code>@Component
public class DynamicRegServlet implements ServletContextInitializer {
    @Override
    public void onStartup(ServletContext servletContext) throws ServletException {
        ServletRegistration.Dynamic initServlet = servletContext.addServlet("myServlet", MyServlet.class);
        initServlet.addMapping("/hello");
    }
}</code>

Dynamic registration relies on the SPI mechanism and the

ServletContainerInitializer

interface.

2. Scanning Servlet Implementation Principle

In method 1, Spring scans the classpath for

@WebServlet

,

@WebFilter

, and

@WebListener

annotations and registers them via the bean registration process.

2.1 Import Core Classes

<code>@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Import(ServletComponentScanRegistrar.class)
public @interface ServletComponentScan { }
</code>

The

ServletComponentScanRegistrar

registers a

ServletComponentRegisteringPostProcessor

bean.

<code>class ServletComponentScanRegistrar implements ImportBeanDefinitionRegistrar {
    public void registerBeanDefinitions(AnnotationMetadata importingClassMetadata, BeanDefinitionRegistry registry) {
        Set<String> packagesToScan = getPackagesToScan(importingClassMetadata);
        if (registry.containsBeanDefinition(BEAN_NAME)) {
            updatePostProcessor(registry, packagesToScan);
        } else {
            addPostProcessor(registry, packagesToScan);
        }
    }
}
</code>

2.2 Register BeanFactory Post Processor

<code>class ServletComponentScanRegistrar implements ImportBeanDefinitionRegistrar {
    private void addPostProcessor(BeanDefinitionRegistry registry, Set<String> packagesToScan) {
        GenericBeanDefinition beanDefinition = new GenericBeanDefinition();
        beanDefinition.setBeanClass(ServletComponentRegisteringPostProcessor.class);
        beanDefinition.getConstructorArgumentValues().addGenericArgumentValue(packagesToScan);
        beanDefinition.setRole(BeanDefinition.ROLE_INFRASTRUCTURE);
        registry.registerBeanDefinition(BEAN_NAME, beanDefinition);
    }
}
</code>

2.3 Instantiate Scanning Components

The static block of

ServletComponentRegisteringPostProcessor

creates handlers for servlet, filter, and listener annotations.

<code>class ServletComponentRegisteringPostProcessor implements BeanFactoryPostProcessor, ApplicationContextAware {
    private static final List<ServletComponentHandler> HANDLERS;
    static {
        List<ServletComponentHandler> servletComponentHandlers = new ArrayList<>();
        servletComponentHandlers.add(new WebServletHandler());
        servletComponentHandlers.add(new WebFilterHandler());
        servletComponentHandlers.add(new WebListenerHandler());
        HANDLERS = Collections.unmodifiableList(servletComponentHandlers);
    }
}
</code>

Each handler extracts annotation attributes and registers a corresponding

ServletRegistrationBean

.

2.4 Find and Register Beans

The post‑processor scans candidate components, matches them with the handlers, and invokes

handle

to create bean definitions.

<code>abstract class ServletComponentHandler {
    void handle(AnnotatedBeanDefinition beanDefinition, BeanDefinitionRegistry registry) {
        Map<String, Object> attributes = beanDefinition.getMetadata()
            .getAnnotationAttributes(this.annotationType.getName());
        if (attributes != null) {
            doHandle(attributes, beanDefinition, registry);
        }
    }
}
</code>

2.5 Tomcat Registers the Servlet

During Spring Boot startup,

AnnotationConfigServletWebServerApplicationContext

creates the embedded web server and invokes all

ServletContextInitializer

beans, including

ServletRegistrationBean

, which registers the servlet with the servlet container.

<code>public abstract class RegistrationBean implements ServletContextInitializer, Ordered {
    @Override
    public final void onStartup(ServletContext servletContext) throws ServletException {
        if (!isEnabled()) {
            return;
        }
        register(description, servletContext);
    }
    protected abstract void register(String description, ServletContext servletContext);
}
</code>

Finally,

ServletRegistrationBean

adds the servlet to the

ServletContext

and configures URL mappings, load‑on‑startup, and multipart settings.