Servlet Containers

What is a Servlet Container — and Why Does it Exist?

The previous page described a servlet container from the outside — what it accepts, routes, and executes. This page goes one level deeper: a Servlet Container is, specifically, the runtime that implements the Jakarta Servlet specification — a contract defining exactly what a Servlet is, how the container must call its lifecycle methods, and what objects (HttpServletRequest, HttpServletResponse, HttpSession) it must hand your code. Every Java web framework you'll ever use — Spring MVC, Spring Boot, JAX-RS implementations — is, underneath its annotations, a layer of code that itself runs as a Servlet and delegates down to your handler methods. Understanding this contract is what lets you reason about what a framework is actually doing when its abstractions leak.

// BEFORE — implementing the Servlet contract directly
public class OrderStatusServlet extends HttpServlet {

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {
        String orderId = req.getParameter("orderId");
        Order order = orderService.findById(Long.valueOf(orderId));

        resp.setContentType("application/json");
        resp.getWriter().write(objectMapper.writeValueAsString(order));
        // You are directly responsible for parsing the parameter, choosing the
        // content type, and serializing the response body by hand.
    }
}

// AFTER — Spring MVC's DispatcherServlet is ITSELF a Servlet that implements
// this exact contract, and delegates down to your annotated method
@GetMapping("/orders/{orderId}")
public Order getOrderStatus(@PathVariable Long orderId) {
    return orderService.findById(orderId);
    // Same servlet lifecycle underneath — init/service/destroy still happen,
    // parameter binding and JSON serialization are handled by the framework
    // layer sitting on top of that same contract, not by a different mechanism.
}

The Servlet Lifecycle — One Instance, Three Lifecycle Methods

// BAD — instance field shared across every concurrent request
public class UnsafeOrderServlet extends HttpServlet {
    private String currentCustomer;   // ONE field, shared by every thread calling doGet concurrently

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        currentCustomer = req.getParameter("customer");   // Thread A sets "alice"...
        // ...Thread B overwrites it with "bob" before Thread A reads it back below...
        resp.getWriter().println("Orders for: " + currentCustomer);   // could print the WRONG customer
    }
}

// GOOD — local variable, scoped to this single request/thread invocation
public class SafeOrderServlet extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        String currentCustomer = req.getParameter("customer");   // local — each thread gets its own
        resp.getWriter().println("Orders for: " + currentCustomer);
    }
}

Filters and Listeners — Cross-Cutting Concerns at the Container Level

Filters — intercept before and after

@WebFilter("/*")
public class RequestTimingFilter implements Filter {

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {

        long start = System.currentTimeMillis();
        try {
            chain.doFilter(request, response);   // pass control down the chain — every filter must call this
        } finally {
            long duration = System.currentTimeMillis() - start;
            log.info("Request completed in {}ms", duration);   // finally — runs even if the chain throws
        }
    }
}

Common uses: authentication checks before a protected resource is reached, response compression, character-encoding normalization, and CORS headers — all covered in dedicated pages elsewhere in this Bible (Authentication vs Authorization, CORS).

Listeners — reacting to container lifecycle events

@WebListener
public class InventorySyncListener implements ServletContextListener {

    @Override
    public void contextInitialized(ServletContextEvent event) {
        // Runs once when the application starts — start a background scheduler,
        // warm a cache, verify required configuration is present
    }

    @Override
    public void contextDestroyed(ServletContextEvent event) {
        // Runs once during shutdown — stop background threads cleanly before
        // the container finishes tearing down, so nothing is left running
        // against resources that are about to disappear
    }
}

Async Servlets — the Problem Virtual Threads Now Solve Differently

Before Java 21, a servlet handling a long-running operation — waiting on a slow downstream call, holding a connection open for Server-Sent Events — tied up one of the container's limited platform threads for the entire duration, exactly the scaling problem described on the previous page. Servlet 3.0 introduced asynchronous processing specifically to work around this: the servlet thread hands the request off and returns immediately, freeing itself to serve other requests, while the actual work completes elsewhere and finishes the response later.

@WebServlet(urlPatterns = "/orders/*", asyncSupported = true)
public class SlowReportServlet extends HttpServlet {

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) {
        AsyncContext asyncContext = req.startAsync();   // releases the container thread NOW

        reportingExecutor.submit(() -> {
            // Runs on a SEPARATE thread pool, not the container's request thread
            Report report = reportService.generateSlowReport();   // takes several seconds
            try {
                asyncContext.getResponse().getWriter().write(report.toJson());
            } catch (IOException e) {
                // handle appropriately
            } finally {
                asyncContext.complete();   // signals the container the response is finished
            }
        });
        // doGet() returns here — the request thread is immediately free for other work
    }
}

Popular Servlet Container Implementations

The javax to jakarta Package Migration

Oracle transferred Java EE governance to the Eclipse Foundation in 2017, and the project was renamed Jakarta EE. The package rename that trips people up, however, didn't happen at that moment — it came later, with Jakarta EE 9 in December 2020, when a trademark restriction on the javax/"Java" naming forced every specification package to move from javax.servlet to jakarta.servlet. Any code, tutorial, or dependency written before that point uses the old namespace; anything targeting Tomcat 10+, Spring Boot 3+, or Jakarta EE 9+ uses the new one — the two are source-incompatible, not just a version bump.

Best Practices and Common Pitfalls

Interview Questions