Published on ONJava.com (http://www.onjava.com/)
 See this if you're having trouble printing code examples

Servlet 2.3 API Features Exposed

by Stephanie Fesler

"It's a bird, it's a plane; no, it's the Servlet 2.3 specification"

Sun Microsystems released the proposed final draft of the Servlet 2.3 specification on October 20, 2000. There have been many changes in the specification between the 2.2 final version and the 2.3 proposed final draft. Some of the changes include

Along with the fixes and clarifications, the Servlet 2.3 proposed final draft specification adds new features -- for example, application lifecycle events and filtering -- to the Servlet arsenal.

Although the Servlet 2.3 specification is not yet in its final version, we do not have to wait any longer to play with the exciting new features defined by it. Apache's Tomcat has released a build, version 4.0 beta 1, that fully supports the Servlet 2.3 proposed final draft specification.

This article begins with an introduction to Servlet concepts (for those new to this area) and then takes an overview of each of the new features, the application lifecycle events, and Servlet filters.

Introduction to Servlet Concepts

The following are terms used throughout this article and are offered to the new arrival on the Servlet scene.

Schematic of the lifecycle of a Servlet.
Figure 1. The lifecycle of a Servlet.

Since a Servlet is a Java class, it gets compiled to platform independent bytecode in the .class file. After the Servlet is deployed and before any requests are made to it, the container is responsible for instantiating a Servlet object and initializing the Servlet. Once the Servlet has been initialized, it is ready to service client requests. At some point, the container can destroy the Servlet object and calls the destroy method on that Servlet object, freeing it up for garbage collection.

Overview of Application Lifecycle Events

The Servlet 2.3 proposed final draft specification defines application lifecycle events to provide Web Application developers more interaction with the ServletContext object and HttpSession objects. Web Application developers write event listeners so they can now be notified when lifecycle events happen (such as creation or destruction) or when attributes are modified in the ServletContext object or HttpSession objects.

Event listeners are Java classes that follow the JavaBeans design and are provided by the Web Application developer in the Web archive (.war) file. There are two types of event listeners, and both types apply to the ServletContext object and HttpSession objects. The two types are lifecycle events and changes to attributes events. Table 1 shows the types of events, a brief description, and the listener interface to implement. This table is taken from the Servlet 2.3 proposed final draft specification.

Table 1. Supported Event Types
Event Type Description Listener Interface
Servlet Context Events

The Servlet context has just been created and is available to service its first request, or the Servlet context is about to be shutdown.

Changes to Attributes

Attributes on the Servlet context has been added, removed, or replaced.

Http Session Events

An HttpSession has just been created, or has been invalidated or timed out.

Changes to Attributes

Attributes have been added, removed or replaced in an HttpSession object.


An interesting point is that there can be multiple listener classes listening to each event type and the Web application developer has the flexibility to define the order the event listener objects are invoked.

The container manages the lifecycle of event listeners. It is the container's responsibility to instantiate each of the listener classes in a Web Application before the execution of the first request into the Web Application. Also, each of the listener classes must be referenced until the Web Application services the last request.

Something important to note is that the container is not required to synchronize notifications to attribute listener classes. This means that attribute lists can change in both the ServletContext object and the HttpSession objects at the same time. If your listener bean maintains state, you have to synchronize access to critical code sections to ensure data integrity.

I defined a session earlier as a series of requests from the same client or user. How do you know when a session is ended? If the client exits the browser, does the browser send your application a little message letting you know? We all know that is not the case. Sessions either time out because the client has not made a request into the application in a specified amount of time, or the client logs off the site and you invalidate the session using the invalidate() method. Wouldn't it be nice to be able to distinguish between sessions that time out because they are invalidated with the invalidate() method or because they just timed out? Now there is sufficient API to allow Web Application developers to determine how a session was invalidated.

Overview of Servlet Filtering

Another exciting addition to the Servlet 2.3 specification is a lightweight framework for filtering Servlets and static content. A filter is defined as a reusable piece of code that can inspect or transform the content of an HTTP request or response. Filters can also be used to modify headers in the request and response. Many times people just think about filtering the requests coming into the application, but notice that filters can be associated with responses as well as requests.

It is also important to draw a distinction between filters and Servlets. Remember that a Servlet is a Java class that accepts requests and generates responses. Filters are different in that they don't actually generate a response. They may modify the headers in the response, but they don't generate the response from scratch like Servlets do.

The Web Application developer would write the filters by implementing the javax.servlet.Filter interface and package it within the Web archive (.war) file for the Web Application. Filters are defined within the deployment descriptor, web.xml, of the Web Application with <filter> tags. One really cool aspect of filters is that they can be associated with one Servlet or with a group of Servlets and static content by the way they are mapped in the web.xml deployment descriptor. But we are not going to go into much more programming in this article.

The Servlet 2.3 proposed final draft specification defines many functions of filters. Filters can

Web Application developers have quite a bit of flexibility with filters. Developers can associate multiple filters to a Servlet and define the order in which the filters are invoked. Again, all this is defined in the web.xml deployment descriptor of the Web Application.

The specification also gives a list of examples of filtering components.

As is the case with Servlets and application event listeners, the container is responsible for the lifetime of filters. At some point after a Web Application is deployed, and before an incoming request for a resource in the web application, the container must look through its list of filter mappings to locate the list of filters that must be associated with the requested resource. As the container goes through the list of filters that need to be applied to the requested resource, it ensures the filter object has been instantiated and the setConfig(FilterConfig config) method has been invoked for each filter object. The specification declares that there can only be one instance of a filter per JVM, and it is the container's responsibility to ensure there is only one instance of each filter per Java virtual machine.

Before the container can remove instances at the end of the lifetime of a web application, it must call the setFilterConfig() method in the filter passing in null to indicate the filter is being taken out of service.

The setConfig(FilterConfig config) method requires a javax.servlet.FilterConfig object as its parameter. It is the responsibility of the container to initialize this object with the filter name (as declared in the web.xml deployment descriptor) with a reference to the ServletContext for the Web Application and with the set of initialization parameters declared for the filter in the web.xml deployment descriptor.


The Servlet 2.3 proposed final draft specification was released on October 20, 2000. Apache's Tomcat version 4.0 beta 1 has full support of the Servlet 2.3 proposed final draft specification.

The two biggest additions to the specification are application lifecycle events and filters. Application lifecycle events give Web Application programmers greater interaction with the ServletContext object and the HttpSession objects. The filters allow the Web Application developer to transform the content of an HTTP request or response or modify header information.

The container manages the lifecycle of the servlets, application lifecycle events, and filters in the Web Application.

Stephanie Fesler is a BEA Systems expert on implementing various Java 2EE API.

Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.