Servlet 2.3: New features exposed

A full update on the latest Servlet API spec

1 2 3 Page 3
Page 3 of 3

API 2.3 also adds two new methods to ServletContext that let you obtain the name of the context and a list of all the resources it holds:

  • String context.getServletContextName(): Returns the name of the context as declared in the web.xml file.
  • java.util.Set context.getResourcePaths(): Returns all the resource paths available in the context, as an immutable set of String objects. Each String has a leading slash ('/') and should be considered relative to the context root.

There's also a new method on the response object to increase programmer control of the response buffer. API 2.2 introduced a res.reset() method to reset the response and clear the response body, headers, and status code. API 2.3 adds a res.resetBuffer() that clears just the response body:

  • void res.resetBuffer(): Clears the response buffer without clearing headers or the status code. If the response has already been committed, it throws an IllegalStateException.

And finally, after a lengthy debate by a group of experts, Servlet API 2.3 has clarified once and for all exactly what happens on a res.sendRedirect("/index.html") call for a servlet executing within a non-root context. The issue is that Servlet API 2.2 requires an incomplete path like "/index.html" to be translated by the servlet container into a complete path, but doesn't say how context paths are handled. If the servlet making the call is in a context at the path "/contextpath," should the redirect URI translate relative to the container root (http://server:port/index.html) or the context root (http://server:port/contextpath/index.html)? For maximum portability, it's imperative to define the behavior; after lengthy debate, the experts chose to translate relative to the container root. For those who want context relative, you can prepend the output from getContextPath() to your URI.

DTD clarifications

Finally, Servlet API 2.3 ties up a few loose ends regarding the web.xml deployment descriptor behavior. It's now mandated that you trim text values in the web.xml file before use. (In standard non-validated XML, all white space is generally preserved.) This rule ensures that the following two entries can be treated identically:




API 2.3 also allows an <auth-constraint> rule, so the special value "*" can be used as a <role-name> wildcard to allow all roles. That lets you write a rule, like the following, that lets all users enter as soon as they've been properly identified as belonging to any role in the Web application:

  <role-name>*</role-name>  <!-- allow all recognized roles -->

Lastly, it's been clarified that you can use a role name declared by a <security-role> rule as a parameter to the isUserInRole() method. For example, with the following snippet of a web.xml entry:

            mgr        <!-- name used by servlet -->
            manager    <!-- name used in deployment descriptor -->
<!-- ... -->

the servlet secret can call isUserInRole("mgr") or isUserInRole("manager") -- they will give the same behavior. Basically, security-role-ref acts to create an alias, but isn't necessary. That is what you'd naturally expect, but the API 2.2 specification could be interpreted as implying that you could only use roles explicitly declared in a <security-role-ref> alias rule. (If that doesn't make sense to you, don't worry about it; just be aware that things are now guaranteed to work as they should.)


As I've described in this article, Servlet API 2.3 includes an exciting new filter mechanism, an expanded lifecycle model, and new functionality to support internationalization, error handling, secure connections, and user roles. The specification document has also been tightened to remove ambiguities that could interfere with cross-platform deployment. All in all, there are 15 new classes (most involving the new lifecycle event model, the others involving filters), four methods added to existing classes, four new constant variables, and one deprecated class. For a cheat sheet on moving from 2.2 to 2.3, see the sidebar.

Jason Hunter is senior technologist with CollabNet, which provides tools and services for open source style collaboration. He is the author of Java Servlet Programming, 2nd Edition (O'Reilly), publisher of, a contributor to Apache Tomcat (he started on the project when it was still Sun internal), and a member of the expert groups responsible for Servlet/JSP and JAXP API development. He also holds a seat on the JCP Executive Committee overseeing the Java platform, as a representative of the Apache Software Foundation. Most recently he cocreated the open source JDOM library to enable optimized Java and XML integration.

Learn more about this topic

1 2 3 Page 3
Page 3 of 3