Before we begin our examination of these enhancements, let me point out that version 2.2 has been released as a specification only; no Web server yet supports it. Even Sun's official reference implementation is still perhaps a couple months away; it is expected to be released with source code as part of the Jakarta Project (see Resources for information on Jakarta). So be careful, boys and girls; don't try these code examples at home!

Java 2 Platform, Enterprise Edition
One of the first things one notices when reading the Java Servlet API 2.2 specification is that the term servlet engine has been replaced by servlet container. This minor change is indicative of a larger one: the Java Servlet API is now a required API of the Java 2 Platform, Enterprise Edition (J2EE) specification and, throughout J2EE's terminology, container is preferred over engine. The addition of servlets to J2EE has no real effect on pure servlet developers (except for the fact that we have to stop saying "engine"). But it does guarantee that enterprise developers using J2EE will always have support for servlets. (Lucky developers!)

Web applications
Java Servlet API 2.2 includes one new feature so significant it may change the way the Web works. That feature: Web applications.

A Web application, as defined in the servlet specification, is a

collection of servlets, JavaServer Pages (JSPs), HTML documents, images, and other Web resources that are set up in such a way as to be portably deployed across any servlet-enabled Web server. Installing a Web app is simple. Gone are the days of detailed instruction sheets telling you how to install third-party Web components, with different instructions for each type of Web server. With Web apps, the entire application can be contained in a single archive file and deployed by placing the file into a specific directory.

War: What is it good for?

Web app archive files have the extension .war, which stands for Web application archive.

War files are actually jar files (created using the jar utility) saved with an alternate extension. Using the jar format allows jar files to be stored in compressed form and have their contents digitally signed. The .war file extension was chosen over .jar to let people and tools know to treat them differently.

Inside a war file you might find a file listing like this:


index.html
howto.jsp
feedback.jsp
images/banner.gif
images/jumping.gif
WEB-INF/web.xml
WEB-INF/lib/jspbean.jar
WEB-INF/classes/MyServlet.class
WEB-INF/classes/com/mycorp/frontend/CorpServlet.class
WEB-INF/classes/com/mycorp/frontend/SupportClass.class


On install, a war file can be mapped to any URI prefix path on the server. The war file then handles all requests beginning with that prefix. For example, if the war file above were installed under the prefix /demo, the server would use it to handle all requests beginning with /demo. A request for /demo/index.html would serve the index.html file from the war file. A request for /demo/howto.jsp or /demo/images/banner.gif would also serve content from the war file.

About the WEB-INF directory
The WEB-INF directory is special. The files there are not served directly to the client; instead, they contain Java classes and configuration information for the Web app. The directory behaves like a jar file's META-INF directory; it contains metainformation about the archive contents.

The WEB-INF/classes directory contains the class files for this Web app's servlets and support classes. WEB-INF/lib contains classes stored in jar files. For convenience, Web server class loaders automatically look to WEB-INF/classes and WEB-INF/lib for their classes -- no extra install steps are necessary.

The servlets under WEB-INF in this Web app can be invoked using URIs like /demo/servlet/MyServlet and /demo/servlet/com.mycorp.frontend.CorpServlet. Notice how every request for this app begins with /demo, even requests for servlets.

The web.xml file in the WEB-INF directory is known as a deployment descriptor. This file contains configuration information about the Web app in which it resides. It's an XML file with a DTD (set of tags and structure) specified in detail as part of the Java Servlet API. The DTD contains over 50 tags, allowing you to specify any of the following:

Graphical icon files for the application

Useful for GUI manipulation.

A description of the app

Information on what the app does, who wrote it, where it can be found, and so on.

A flag indicating whether or not the app can be distributed

Distributed apps can be spread across multiple back-end servers to improve performance and add fail-over support, but such apps must be written according to stricter rules than their nondistributed counterparts. For example, objects placed into sessions for a distributed app should be serializable. This flag indicates whether the app has been written in accordance with the stricter rules.

Parameter information for the app

Essentially, these are init parameters for the application.

Registered servlet names

A place to register servlets and give them names. Previously, each server had a different process for registering servlets, making deployment difficult.

Servlet init parameters

Pass servlets parameters at initialization time. A new standard way to accomplish what used to be a server dependent process.

Servlet load order

Specifies which servlets are preloaded, and in what order.

URL mapping rules

Standardized mappings from URLs to servlets. For example, allow /lite/* to be handled by LiteServer and *.jsp to be handled by JspServlet (a mapping needed to support JSPs). Note that a /lite/* mapping for this Web app would handle requests beginning with /demo/lite/.

Session timeout defaults

Specify how many minutes of client inactivity can go by before a session times out.

File extension to MIME type mappings

Override server defaults or add mappings not known to the server.

A welcome file list

An ordered list of files to look for when a request comes in for a directory without specifying the file. Often index.jsp, index.html, index.htm.

Error-handling rules

Specify Web pages to handle various kinds of errors. Pages can be registered based on error code (for example, 404 errors serve some specific page) or based on exception type (for example, if a servlet throws

javax.servlet.UnavailableException, display some explanatory page).

References to external data sources, such as JNDI

Add resources into the JNDI lookup table, like database connections. Allow the resources to be located by servlets using a simple name lookup.

Security constraints

Dictate which pages must be protected, and by what mechanism. Include built-in form-based authentication.

For those interested, the Web app DTD and a simple example web.xml file can be found in the Resources section. A full description of all the elements in the DTD would extend this article beyond a reasonable length, and may be of little interest in the long run, as these files are likely to be generated by graphical tools; thus, I will not describe the elements here.

The structure of the web.xml file is not in itself important; what interests us is the fact that having a deployment descriptor file allows configuration information to be specified in a server-independent manner, greatly simplifying the deployment process. Because of deployment descriptors, not only are simple servlets portable, but you can now transfer whole self-contained subsections of your site between servers.

As Java Servlet API 2.2 gains in popularity, it's likely that a commercial market for war files will develop. War files will become pluggable Web components, capable of being downloaded and installed and put to work right away -- no matter what your operating system or Web server. $19.95 for a site search engine, anyone?

Deployment descriptors also provide Web-hosting companies with a convenient way to support multiple customers on the same server. Customers can be given control over their individual domains. They can individually manage servlet registration, URL mappings, MIME types, and page-level security constraints -- without needing general access to the Web server.

Now let's take a look at how Web apps are implemented.

Web apps: A programmer's view
From a programmer's point of view, a Web app corresponds to one ServletContext object. All servlets inside a Web app share the same ServletContext instance. All Web servers have at least one context, called the default context. It handles requests whose URI paths match no other context prefix. (So, for example, it would handle requests for /index.html or /images/tile.gif.)

Parameter information for the Web app (specified in the deployment descriptor) is available using two new methods in ServletContext: getInitParameter() and getInitParameterNames(). These methods are modeled after their counterparts in GenericServlet. getInitParameter(String name) returns the string value of the specified parameter. getInitParameterNames() returns an enumeration containing the names of all the init parameters available to the app.

A servlet can determine the URI prefix of the context in which it's running using the new getContextPath() method in ServletRequest. This method returns a string representing the URI prefix of the context handling the request. The value starts with /, has no ending /, and, for the default context, is empty. For a request to /catalog/books/servlet/BuyNow, for example, the getContextPath() would return /catalog/books.

When using the context object to request resources, it's important to remember not to include the context path in the request. After all, the context knows its own path, and by not specifying the path in code, you ensure that the application can be moved to a different path prefix without recompiling. For example, when getting a RequestDispatcher to a servlet, use context.getRequestDispatcher("/servlet/BuyNow"). A request for /catalog/books/servlet/BuyNow would fail because the request is interpreted relative to the context root. The same goes for context.getResource() and context.getResourceAsStream().

The following servlet doGet() method demonstrates these context methods in action. Remember, this code won't compile against today's servers.

public void doGet(HttpServletRequest req, HttpServletResponse res)
                      throws ServletException, IOException {

  res.setContentType("text/plain");
  PrintWriter out = res.getWriter();

  out.println("My context path is: " + req.getContextPath());

  ServletContext context = getServletContext();
  out.println("My context instance is: " + context);

  out.println("My context parameters are:");
  Enumeration e = context.getInitParameterNames();
  while (e.hasMoreElements()) {
    String name = (String) e.nextElement();
    Object value = context.getAttribute(name);
    out.println(name + ": " + value);
  }

  // Now let's dispatch
  RequestDispatcher dispatcher =
    context.getRequestDispatcher("/servlet/BuyNow");
  dispatcher.include(req, res);
}



This code first prints the current context path, the context reference, the init parameters, and finally includes output from the BuyNow servlet.

Lifecycle clarifications
Some additional clarifications have been made in the Java Servlet API 2.2 specification pertaining to Web apps and the servlet lifecycle. It's now defined that, for servlets that don't implement SingleThreadModel, there's exactly one instance of a servlet per definition (that is, registered name) per context.

Previously, the server could optionally create multiple instances. This new, stricter rule allows servlets to use instance variables to hold state associated with a particular servlet definition. For example, counter servlets can store their count in instance variables, and each registered name for the counter can maintain its own count. (This was how nearly everyone wrote servlets with versions 2.0 and 2.1 of the API; the difference is that now this technique is guaranteed to work.)

It's also defined that Web servers must guarantee that servlets sharing information via user sessions or servlet contexts must not experience unexpected ClassCastExceptions. Such exceptions occurred previously due to servlets being loaded by different ClassLoader instances -- remember, classes loaded by two different class loaders cannot be cast to one another. In effect, this new rule means that, when one servlet class is reloaded, all the classes of the entire context have to be reloaded. This causes an unfortunate performance penalty, but one that should only be paid during development and that can be justified by the easier programming it allows.

Distributed applications
A few clarifications were also made in 2.2 with regards to distributed applications, in which application components can be spread across multiple back-end server machines.

The specification dictates that, for an app marked as distributable in its deployment descriptor, there will be a single ServletContext instance per JVM. This means the context attributes cannot be used to share global information. Global information in a distributed app needs to be stored externally from the Web server, as is the case in database or EJB component.

An app marked as distributable also has special rules for user sessions. Servers will use session affinity to efficiently manage user state across multiple back-end servers. This means that all requests that are part of a single session from a particular user are to be handled by only one JVM at a time. This in turn eliminates the need to constantly replicate session information across all the back-end servers. Responsibility for the session can be moved to another server between user requests, though in practical terms this is unlikely to occur frequently. Still, to enable the moving of a session, all objects placed into a session by servlets in a distributed app must implement Serializable. A Web server can throw an IllegalArgumentException if this condition is not met. Nondistributed apps, of course, can store any objects into the session.

Response buffering
One of the most useful features added in version 2.2 of the servlet API is response buffering. A servlet now has control over whether the server buffers its response, and may dictate how large a buffer the server can use.

In previous versions of the API, most Web servers implemented response buffering as a way to improve performance. Exactly how large that buffer was depended on the server. Generally, servers had buffers in the neighborhood of 8 KB. The important change for 2.2 is that a servlet now can specify a minimum buffer size for its output. This improves the flexibility of servlet error handling. How does this work? Well, the structure of HTTP dictates that the first line of an HTTP response includes a status code indicating the success or failure of the client request. To be sure to correctly set the status code, servlets have had to do full error checking before generating any output. If an error was encountered halfway through the response, it was just too bad. The response was already sent (or committed) and the status code and headers could not be changed.

A response buffer allows a servlet to write some amount of output with a guarantee that the response won't be immediately committed. If the servlet finds an error, the status code and headers can still be changed so long as the buffer has not been flushed.

Five new methods
Five methods were added to ServletResponse in order to support response buffering:

• The setBufferSize(int size) method tells the server the minimum buffer size that the servlet will accept; the value is given in bytes. The server may provide a larger buffer than requested if necessary -- it may want to keep buffers in 8 KB blocks, for example.

• The getBufferSize() method returns an int indicating how large the current buffer actually is. Larger buffers allow for more flexibility; smaller buffers save server memory and make the page appear to arrive to the client more quickly. Just make sure to specify the buffer size before writing output, as setBufferSize() will throw an IllegalStateException if you don't.

• The isCommitted() method returns a boolean indicating whether any part of the response has actually been sent. If this method returns true, it's too late to change the status code and headers.

• The reset() method can be used any time before commit to empty the buffer and unset the headers. reset() is automatically called by methods like sendError() and sendRedirect(). reset() throws an IllegalStateException if you try to reset a committed response.

• The final newly added method is flushBuffer(). It sends content in the buffer to the client and commits the response.

The following code snippet demonstrates how these methods can be put to use:

public void doGet(HttpServletRequest req, HttpServletResponse res)
                      throws ServletException, IOException {
  res.setBufferSize(16 * 1024);    // 16K buffer
  res.setContentType("text/html");
  PrintWriter out = res.getWriter();

  int size = res.getBufferSize();  // returns 16384 or greater

  out.println("The client won't see this");
  res.reset();
  out.println("Nor will the client see this!");
  res.reset();
  out.println("And this won't be seen if sendError() is called");
  if (req.getParameter("important_parameter") == null) {
    res.sendError(res.SC_BAD_REQUEST, "important_parameter needed");
  }
}



This servlet sets the buffer to 16 KB, then checks the buffer size. The returned size should be 16 KB or greater. Then the servlet tests out the reset() method by calling it both directly and via sendError().

Support for double headers
In the new version of the API, servlets have the ability to retrieve more information than ever before, and send a little more as well.

There's a new method in HttpServletRequest called getHeaders() that can return multiple values for a given header. This was needed because some headers, such as Accept-Language, can send multiple header values:

Accept-Language: en
Accept-Language: fr
Accept-Language: ja

Previously, servlets using getHeader() could retrieve only one value per header. With the new version of getHeaders(), a servlet can retrieve multiple values as an enumeration of string objects. Servlets have also been given the ability to send multiple values for the same response header using methods in HttpServletResponse. The new addHeader(String name, String value) method sets the header to the given value. While the traditional setHeader() method would replace any existing value or values, addHeader() leaves current settings alone and just sets an additional value. There's also addIntHeader(String name, int value) and addDateHeader(String name, long date).

Now this is just temporary
Another new piece of information was made available in 2.2, but this change didn't require a new method. The context object now contains a new standard attribute -- available using getAttribute(String name) -- called javax.servlet.context.tempdir. This attribute maps to a temporary directory where short-lived working files can be stored. Each context receives a different temporary directory. The following code shows how to write to a temp file in the temporary directory.

public void doGet(HttpServletRequest req, HttpServletResponse res)
                      throws ServletException, IOException {  
                      
  // The directory is given as a File object
  
  File dir = (File) getServletContext()
                    .getAttribute("javax.servlet.context.tempdir");

  // Construct a temp file in the temp dir (JDK 1.2 method)

  File f = File.createTempFile("xxx", ".tmp", dir);

  // Prepare to write to the file

  FileOutputStream fout = new FileOutputStream(f);

  // ...

}

First, this servlet locates its temporary directory. Then, it uses the createTempFile() method to create a temporary file in that directory with an xxx prefix and .tmp suffix. Finally it constructs a FileOutputStream to write to the temporary file.

No more amnesia
The last bit of new information available to a servlet is the servlet's own name. In the ServletConfig interface (which GenericServlet implements) there's a new method, getServletName(), that returns the servlet's registered name. If the servlet is unregistered, the method returns the servlet's class name. This method proves useful when logging and storing a servlet instance's state information into such resources as databases or servlet contexts.

As an example, the following code demonstrates how to use the servlet's name to retrieve a value from the servlet context, using the name as part of the lookup key.

public void doGet(HttpServletRequest req, HttpServletResponse res)
                      throws ServletException, IOException {
  String name = getServletName();  // inherited from GenericServlet
  ServletContext context = getServletContext();
  Object value = context.getAttribute(name + ".state");
}



So, where are you from?
Internationalization has become an important topic on the Web, and the new version of the API includes some enhancements that simplify the challenge of dealing with clients from multiple locales.

With Java Servlet API 2.2, a servlet can determine the preferred locale of the client using a few new convenience methods. HttpServletRequest has a getLocale() method that returns a java.util.Locale object, which in turn indicate the client's most preferred locale. This preference is based primarily on the Accept-Language header. There's a getLocales() method as well that returns an enumeration of Locale objects indicating all the acceptable locales for the client, with the most preferred first.

Accompanying these methods is a setLocale(Locale loc) method added to ServletResponse that allows a servlet to specify the locale of the response. The method automatically sets the Content-Language header and the Content-Type charset value. setLocale() should be called after setContentType() and before getWriter(). For example:

public void doGet(HttpServletRequest req, HttpServletResponse res)
                      throws ServletException, IOException {

  res.setContentType("text/html");
  Locale locale = req.getLocale();
  res.setLocale(locale);
  PrintWriter out = res.getWriter();

  // Write output based on locale.getLanguage()
}



Note that these methods aren't as powerful as the com.oreilly.servlet.LocaleNegotiator class (available in the Resources section).

Hark, who goes there?
Before Java Servlet API 2.2, servlets had very little control over server security. Page access restrictions were set up using server administration tools, and all a servlet could do was view the remote user's basic authentication login name by calling req.getRemoteUser(). Now, however, servlets have slick built-in support for portable role-based user authentication and authorization.

Using tags in the Web application deployment descriptor, security constraints can be set up to indicate that certain pages in the Web app are to be accessed only by users with certain credentials. Specifically, since this is role-based user authorization, access will only be granted to users who are part of a given role. For example, you might want to set up your site so that pages that display salary information can be restricted to only those users who are in a manager role.

The deployment descriptor specifies the type of access granted to each role, but does not specify that role to user or group mapping. That's done during deployment of the Web app, using server-specific tools. The ultimate mapping may come from many locations -- the Web server, the operating system, a relational database, and so on.

Two new methods were introduced in HttpServletRequest to support role-based authorization. The getUserPrincipal() method was added to return a java.security.Principal object holding the name of the current client user (or a null value if the client hasn't logged in). The isUserInRole(String role) method was added to return a boolean indicating if the current client is in the given role. Access can be granted or denied based on the value returned.

The final new security method in HttpServletRequest is isSecure(), which returns true if the request was made over a secure channel such as HTTPS. Here's a code snippet showing the new methods in action:

public void doGet(HttpServletRequest req, HttpServletResponse res)
                      throws ServletException, IOException {
  res.setContentType("text/plain");
  PrintWriter out = res.getWriter();

  out.println("The current user is: " + req.getUserPrincipal());
  out.println("Is the user a Manager? " + req.isUserInRole("Manager"));
  out.println("Is our connection secure? " + req.isSecure());
}



Nit-picky on parameters
If you look closely at the specification, you'll see that a much-needed clarification was made on how parameters are handled in API 2.2.

It's now guaranteed that parameters specified in the query string of a post request will be read and made available to servlets. Furthermore, in the event that any query string parameter names collide with post parameter names, the query string values are to be made available first via getParameterValues(), followed by the post values. Previously, it was legal for query string parameters to be ignored. Requiring their support allows portable use of post forms whose action tag includes a query string, such as:
<FORM METHOD="POST" ACTION="/servlet/Testing?a=b">
This clarification also allows a special query string parameter to be used for session tracking and passed even during post requests.

Better dispatching
Finally, Java Servlet API 2.2 provides more convenient request dispatching. There's a new getNamedDispatcher(String name) method in ServletContext that lets a servlet dispatch to a component specified by its registered name instead of a full URI path. This allows dispatching to a component that may not be publicly accessible on any URI path.

There's also a new getRequestDispatcher(String path) method in ServletRequest. This method can accept a relative URL target, unlike the getRequestDispatcher() method in ServletContext that only accepts a fully qualified URL. The relative path must still resolve to a component in the current context (that is, the same Web app); for dispatching to another Web app, you must get a handle to the other Web app context and use that handle to locate the RequestDispatcher.

Lastly, the sendRedirect(String url) method in HttpServletResponse has been changed so that it now supports relative URLs. Previously, the URL passed to sendRedirect() had to be absolute (beginning, for example, with "http://") because the HTTP specification dictates that all redirect URLs must be absolute. Of course, the HTTP spec didn't change for 2.2, but now sendRedirect() is smart enough to convert any relative URL passed in to an absolute URL on its way to the client. Snazzy.

Conclusion
As described in this article, Java Servlet API 2.2 includes many enhancements designed to make servlets part of a complete Web application framework. Whole subsections of Web sites will be able to be configured and deployed to any Web server that supports API 2.2.

Servlets can also be distributed across multiple back-end servers, or can indicate via their deployment descriptor that they'd rather stick to one machine. Response buffering has been added to make error handling more robust, HTTP header control has been improved, and request dispatching has been made easier with support for relative paths and named dispatchers.

All in all, there are 29 new methods, 2 new constants, and just 6 deprecated methods. For a cheat sheet on moving from 2.1 to 2.2, see the sidebar.

To be notified when new articles are added to the site, subscribe here.

Resources
A site dedicated to helping you learn about, develop, and use servlets:
  http://www.servlets.com/
That site accompanies my book, Java Servlet Programming, 2nd Edition (O'Reilly, 2001):
  http://www.servlets.com/jservlet2
Official home site for servlets:
  http://java.sun.com/products/servlet
The official Web app DTD:
  http://www.servlets.com/jservlet2/jservlet2-dtd.pdf
Project Jakarta, the open source servlet reference implementation:
  http://jakarta.apache.org/
Home page for com.oreilly.servlet.LocaleNegotiator:
  http://www.servlets.com/cos/
"Introducing the new Servlet API 2.1," Jason Hunter (JavaWorld, December 1998) -- describes differences between Java Servlet API 2.0 and 2.1:
  http://www.servlets.com/soapbox/servlet21.html
BrowserHawk4J, a commercial product I'm proud to have worked on:
  http://www.cyscape.com/products/bh4j