Understanding Spring's Parent-Child Containers: Architecture, Startup Flow, and Common Pitfalls

Overview

Spring MVC applications use a hierarchical WebApplicationContext structure: a root (parent) context manages service and DAO beans, while a servlet-specific (child) context manages web MVC beans such as controllers and view resolvers. The child can access beans from the parent, but the parent cannot see child beans.

Why Use Parent‑Child Contexts

Separates concerns in a typical three‑tier J2EE architecture.

Allows independent configuration files (e.g., applicationContext.xml for services/DAOs and spring-servlet.xml for controllers).

Facilitates swapping the web framework (e.g., replacing Spring MVC with Struts) by only changing the child configuration.

Spring Startup Sequence

The root context is created by SpringServletContainerInitializer via the Servlet 3.0 SPI. ContextLoaderListener invokes initWebApplicationContext, which creates a ConfigurableWebApplicationContext, sets its parent (if any), refreshes it, and stores it under WebApplicationContext.ROOT_WEB_APPLICATION_CONTEXT_ATTRIBUTE.

public WebApplicationContext initWebApplicationContext(ServletContext servletContext) {
    if (servletContext.getAttribute(WebApplicationContext.ROOT_WEB_APPLICATION_CONTEXT_ATTRIBUTE) != null) {
        throw new IllegalStateException("Root context already present");
    }
    servletContext.log("Initializing Spring root WebApplicationContext");
    long startTime = System.currentTimeMillis();
    this.context = createWebApplicationContext(servletContext);
    if (this.context instanceof ConfigurableWebApplicationContext) {
        ConfigurableWebApplicationContext cwac = (ConfigurableWebApplicationContext) this.context;
        if (cwac.getParent() == null) {
            cwac.setParent(loadParentContext(servletContext));
        }
        configureAndRefreshWebApplicationContext(cwac, servletContext);
    }
    servletContext.setAttribute(WebApplicationContext.ROOT_WEB_APPLICATION_CONTEXT_ATTRIBUTE, this.context);
    logger.info("Root WebApplicationContext initialized in " + (System.currentTimeMillis() - startTime) + " ms");
    return this.context;
}

The child context is created by FrameworkServlet (e.g., DispatcherServlet) during its initServletBean phase, which calls the same method again, this time passing the previously created root context as the parent.

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

Verifying the Two Contexts

Implement ApplicationContextAware in a service bean and a controller. The service reports a parent context instance (e.g., XmlWebApplicationContext@3972) while the controller reports a different instance (e.g., XmlWebApplicationContext@4114), confirming distinct containers.

Common Configuration Questions

Why need parent‑child containers? They delineate framework boundaries, allowing separate bean definitions for the service layer (parent) and the web layer (child).

Can all classes be managed by the parent? No. If the child spring-servlet.xml does not scan controller packages, request mappings are not registered, resulting in 404 errors.

Can all needed classes be placed in the child? Yes, by configuring global component scanning in spring-servlet.xml. However, cross‑cutting concerns such as transactions or AOP must also be defined in the child, otherwise they may not work.

Can both containers manage the same classes? Technically possible but wasteful and error‑prone: duplicate bean definitions increase memory usage and can override parent‑defined proxies, breaking transaction or AOP behavior.

Key Takeaways

Understanding the parent‑child WebApplicationContext hierarchy helps diagnose issues like missing transactions or AOP failures. The root context is initialized by the servlet container via ContextLoaderListener, and each DispatcherServlet creates its own child context that inherits from the root. Proper configuration of component scanning and bean definitions in the appropriate context is essential for a functional Spring MVC application.