Last checked and updated on April 20, 2026What Is New in Servlet 3.1
Servlet 3.1 introduces key enhancements focused on non-blocking I/O, security, and protocol handling. These updates provide developers with more powerful tools for building modern, high-performance web applications. The specification also clarifies and refines several existing features.
| Category | Key Changes |
|---|---|
| New Features | Non-blocking I/O for Read and Write, HTTP Upgrade Protocol Support |
| Security | Session ID Management Changes, Default Session Tracking Mode |
| Clarifications & Changes | Clarified SRV.4.7, Content-Length Handling, URL Parameters |
How did non-blocking I/O improve in Servlet 3.1?
Servlet 3.1 extends the non-blocking I/O API introduced in 3.0 to cover both reading and writing. You can now use ServletInputStream.setReadListener and the new ServletOutputStream.setWriteListener to handle I/O operations asynchronously.
This is a big deal for handling large file uploads or streaming responses without tying up a request thread. The container can now efficiently manage resources when a client has a slow network connection.
What is the HTTP Upgrade processing feature?
This feature allows a servlet to negotiate a protocol switch with a client, like upgrading an HTTP connection to a WebSocket. You handle this by overriding the new HttpServlet.service method that takes an HttpServletRequest and HttpServletResponse.
In practice, this gives you a standardized way to implement protocol upgrades directly within the servlet container, moving beyond basic HTTP without needing complex workarounds.
How were security enhancements addressed?
The specification made session ID management more robust. It now explicitly requires that session IDs be changed when the authentication state of a session changes, helping to prevent session fixation attacks.
It also changed the default session tracking mode from SSL to COOKIE, which is a more common and practical default for most web applications.
What clarifications were made for developers?
Several sections of the specification were clarified to avoid ambiguity. A key clarification was for SRV.4.7, which deals with the rules for composing the request path elements used for mapping requests to servlets.
Other tweaks included how the container handles the Content-Length header and the rules for parsing URL parameters, making container behavior more predictable across different implementations.
FAQ
Do I need to rewrite my servlets for 3.1?
No. Servlet 3.1 is fully backward compatible. Your existing servlets will work without modification. The new features are additive, giving you new tools to use when you need them.
When should I use the non-blocking I/O?
Use it when you need to handle many simultaneous, long-lived connections where threads might be waiting on slow clients. It's perfect for comet-style applications, large file transfers, or any streaming scenario.
How does the HTTP Upgrade help with WebSockets?
The WebSocket protocol itself uses an HTTP Upgrade handshake. This feature provides the standard hook within the servlet container to handle that initial handshake before switching to the WebSocket protocol for bidirectional communication.
What's the impact of the default session tracking mode change?
For most developers, it means less configuration. Since cookies are the most common method for session tracking, your application will likely work as expected without having to explicitly set the tracking mode.
Are there any changes to the deployment descriptor (web.xml)?
No, the schema for web.xml remains unchanged from Servlet 3.0. All new features are accessible programmatically through the existing and new APIs.