The Three Fatal Flaws of the Servlet Spec That Pushed Spring to Dominance

If you have ever worked with Java Web, you probably remember the painful migration from javax.servlet to jakarta.servlet, which forced a massive global replace of import statements. The author argues that this package‑name move is the best chance in the past two decades to discard long‑standing, obsolete clauses in the Servlet specification.

1. Full‑Annotation Scanning: Paying for Unused Code

Since Servlet 3.0, annotations like @WebServlet, @WebFilter and @WebListener allow developers to avoid web.xml. However, the container still performs a default full‑scan of WEB-INF/classes and every JAR on the classpath, looking for any annotated class, even if most of them are never used. The spec provides a metadata-complete="true" switch in web.xml to skip the scan, but the author notes that almost nobody configures it because they are unaware of its existence. In cloud‑native environments where containers must start in seconds and Serverless demands cold‑start speed, this “scan‑everything” approach becomes a clear liability.

2. Security Specification: Managing Something It Should Not

The spec defines security-constraint, login-config, security-role and, since Servlet 3.0, methods like request.authenticate(), login() and logout() for declarative authentication. In practice, almost no teams use this container‑native authentication; modern applications rely on OAuth2, JWT, SSO, and multi‑factor authentication. Consequently, frameworks such as Spring Security and Apache Shiro implement their own filter chains and ignore the servlet‑provided mechanisms. The author calls this part of the spec a “half‑finished” feature that the official ecosystem itself has abandoned.

3. Async Specification: Adding a Prosthetic Limb to a Synchronous Skeleton

The async API introduced in Servlet 3.0, such as AsyncContext.complete(), is easy to misuse. Forgetting to call complete() leaves the request hanging, filling the thread pool without any error log. The author provides a code snippet that shows the typical pattern and the pitfalls of double‑calling or never calling complete(). Servlet 3.1 added ReadListener and WriteListener for non‑blocking I/O, but the callback‑style design feels outdated even by 2014. The industry’s answer has been Reactive Streams (Publisher/Subscriber) and Spring WebFlux, which completely bypass the Servlet API and build a new reactive stack on top of Reactor Netty.

AsyncContext asyncContext = request.startAsync();
// business logic
asyncContext.complete();

Why Spring Rose

Spring’s success is not solely due to its IoC/DI/AOP philosophy; the servlet spec’s “anti‑business” design pushed developers toward a higher‑level framework. The author summarizes the relationship in a table‑style list:

Full‑annotation scanning → Spring Boot provides precise component scanning, lazy initialization, and AOT compilation for cloud‑native scenarios.

Security spec overreach → Spring Security builds its own filter chain and natively supports OAuth2, JWT, and SSO.

Half‑baked async API → Spring WebFlux abandons the Servlet API entirely, using Reactor Netty for a true reactive stack.

web.xml configuration → Spring Boot eliminates XML, favoring convention‑over‑configuration.

HttpSession single‑node assumption → Spring Session externalizes session state to Redis or JDBC.

The author concludes that each time the Servlet spec leaves a gap, the Spring ecosystem fills it, demonstrating that a specification that cannot serve its own ecosystem becomes a source of technical debt.

Breaking and Rebuilding

If a specification no longer serves modern workloads, the only dignified path is to deprecate or remove the obsolete clauses. The author advocates for a bold “break‑then‑rebuild” approach, suggesting that the spec should openly mark as deprecated the parts already superseded by Spring, cloud‑native, and reactive technologies.

Lightweight Alternatives

For projects still tied to the Servlet ecosystem but dissatisfied with heavyweight containers like Tomcat, the author mentions smart‑servlet , a Jakarta Servlet 6.x‑based lightweight container that can run with as little as 12 MB memory. The repository is https://gitee.com/smartboot/smart-servlet. For teams ready to abandon the Servlet spec entirely, Feat offers a zero‑Servlet, self‑developed communication kernel with native HTTP/2, WebSocket, and SSE support, plus a Spring‑Boot‑like development experience via the feat‑cloud module. Its repository is https://gitee.com/smartboot/feat.

Project repository: https://gitee.com/smartboot/smart-servlet

Project repository: https://gitee.com/smartboot/feat

The lifecycle of a technical specification should have a clear beginning and end; rather than repeatedly patching an outdated spec, it is better to retire it with dignity.