Application Life Cycle Events

The application events facility gives the web application developer greater control over the life cycle of the ServletContext and HttpSession and ServletRequest, allows for better code factorization, and increases efficiency in managing the resources that the web application uses.

10.1 Event Listeners

Application event listeners are classes that implement one or more of the servlet event listener interfaces. They are instantiated and registered in the web container at the time of the deployment of the web application. They are provided by the developer in the WAR.

Servlet event listeners support event notifications for state changes in the ServletContext, HttpSession and ServletRequest objects. Servlet context listeners are used to manage resources or state held at a platform level for the application. HTTP session listeners are used to manage state or resources associated with a series of requests made into a web application from the same client or user. Servlet request listeners are used to manage state across the life cycle of servlet requests.

There may be multiple listener classes listening to each event type, and the developer may specify the order in which the container invokes the listener beans for each event type.

10.1.1 Event Types and Listener Interfaces

Event types and the listener interfaces used to monitor them are shown in TABLE 10-1..

TABLE 10-1 Events and Listener Interfaces
Event Type	Description	Listener Interface
Servlet Context Events:
Lifecycle	The servlet context has just been created and is available to service its first request, or the servlet context is about to be shut down.	`javax.servlet.` `ServletContextListener`
Changes to attributes	Attributes on the servlet context have been added, removed, or replaced.	`javax.servlet.` `ServletContextAttributeListener`
HTTP Session Events:
Lifecycle	An `HttpSession` has been created, invalidated, or timed out.	`javax.servlet.http.` `HttpSessionListener`
Changes to attributes	Attributes have been added, removed, or replaced on an `HttpSession`.	`javax.servlet.http.` `HttpSessionAttributeListener`
Object binding	Object has been bound to or unbound from `HttpSession.`	`javax.servlet.http.` `HttpSessionBindingListener`
Servlet Request Events:
Lifecycle	A servlet request has started being processed by web components.	`javax.servlet.` `ServletRequestListener`
Changes to attributes	Attributes have been added, removed, or replaced on a `ServletRequest`.	`javax.servlet.` `ServletRequestAttributeListener`

10.1.2 An Example of Listener Use

To illustrate a use of the event scheme, consider a simple web application containing a number of servlets that make common use of a service exposed by some other application through a service registry. The developer has provided a servlet context listener class for management of the lookup of the service in the registry.

1. When the application starts up, the listener class is notified. The application looks up the service in the service registry and stores the service client stub in the servlet context.

2. Servlets in the application access the service as needed during activity in the web application using the service client stub stored in the servlet context.

3. When the application is removed from the web server, the listener class is notified and the service client stub is released.

10.2 Listener Class Configuration

10.2.1 Provision of Listener Classes

The developer of the web application provides listener classes implementing one or more of the listener classes in the javax.servlet API. Each listener class must have a public constructor taking no arguments. The listener classes are packaged into the WAR, under the WEB-INF/classes archive entry.

10.2.2 Deployment Declarations

Listener classes are declared in the web application deployment descriptor using the listener element. They are listed by class name in the order in which they are to be invoked.

10.2.3 Listener Registration

The web container creates an instance of each listener class and registers it for event notifications prior to the processing of the first request by the application. The web container registers the listener instances according to the interfaces they implement and the order in which they appear in the deployment descriptor. During web application execution, listeners are invoked in the order of their registration.

10.2.4 Notifications At Shutdown

On application shutdown, listeners are notified in reverse order to their declarations with notifications to session listeners preceding notifications to context listeners. Session listeners must be notified of session invalidations prior to context listeners being notified of application shutdown.

10.3 Deployment Descriptor Example

The following example is the deployment grammar for registering two servlet context life cycle listeners and a session listener.

Suppose that com.acme.MyConnectionManager and com.acme.MyLoggingModule both implement javax.servlet.ServletContextListener, and that com.acme.MyLoggingModule additionally implements javax.servlet.HttpSessionListener. Also, the developer wants com.acme.MyConnectionManager to be notified of servlet context life cycle events before com.acme.MyLoggingModule. CODE EXAMPLE 10-1 shows the deployment descriptor for this application:

CODE EXAMPLE 10-1 Deployment Descriptor Example
<web-app> <display-name>MyListeningApplication</display-name> <listener> <listener-class>com.acme.MyConnectionManager</listener-class> </listener> <listener> <listener-class>com.acme.MyLoggingModule</listener-class> </listener> <servlet> <display-name>RegistrationServlet</display-name> ...etc </servlet> </web-app>

CODE EXAMPLE 10-1 Deployment Descriptor Example

<web-app>
	<display-name>MyListeningApplication</display-name>
	<listener>
		<listener-class>com.acme.MyConnectionManager</listener-class>
	</listener>
	<listener>
		<listener-class>com.acme.MyLoggingModule</listener-class>
	</listener>
	<servlet>
	 	<display-name>RegistrationServlet</display-name>
	 	...etc
	</servlet>
</web-app>

10.4 Listener Instances and Threading

The container is required to complete instantiation of the listener classes in a web application prior to the start of execution of the first request into the application. The container must maintain a reference to each listener instance until the last request is serviced for the web application.

Attribute changes to ServletContext and HttpSession objects may occur concurrently. The container is not required to synchronize the resulting notifications to attribute listener classes. Listener classes that maintain state are responsible for the integrity of the data and should handle this case explicitly.

10.5 Listener Exceptions

Application code inside a listener may throw an exception during operation. Some listener notifications occur under the call tree of another component in the application. An example of this is a servlet that sets a session attribute, where the session listener throws an unhandled exception. The container must allow unhandled exceptions to be handled by the error page mechanism described in Section 9.7.2, Error Pages. If there is no error page specified for those exceptions, the container must ensure that a response is sent back with status 500. In this case, no more listeners under that event are called.

Some exceptions do not occur under the call stack of another component in the application. An example of this is a SessionListener that receives a notification that a session has timed out and throws an unhandled exception, or of a ServletContextListener that throws an unhandled exception during a notification of servlet context initialization, or of a ServletRequestListener that throws an unhandled exception during a notification of the initialization or the destruction of the request object. In this case, the developer has no opportunity to handle the exception. The container may respond to all subsequent requests to the web application with an HTTP status code 500 to indicate an application error.

Developers wishing normal processing to occur after a listener generates an exception must handle their own exceptions within the notification methods.

10.6 Session Events

Listener classes provide the developer with a way of tracking sessions within a web application. It is often useful in tracking sessions to know whether a session became invalid because the container timed out the session or because a web component within the application called the invalidate method. The distinction may be determined indirectly using listeners and the HttpSession API methods.