Application Events and Listeners

 

This section discusses how to configure and use Web Application events and listeners:

• Overview of Application Events and Listeners

• Servlet Context Events

• HTTP Session Events

• Configuring an Event Listener

• Writing a Listener Class

• Templates for Listener Classes

• Additional Resources

 

---

Overview of Application Events and Listeners

Application events provide notifications of a change in state of the servlet context (each Web Application uses its own servlet context) or of an HTTP session object. You write event listener classes that respond to these changes in state and you configure and deploy Application event and listener classes in a Web Application.

For servlet context events, the event listener classes can receive notification when the Web Application is deployed or is being undeployed (or when WebLogic Server shuts down), and when attributes are added, removed, or replaced.

For HTTP Session events, the event listener classes can receive notification when an HTTP session is activated or is about to be passivated, and when an HTTP session attribute is added, removed, or replaced.

Use Web Application events to:

• Manage database connections when a Web Application is deployed or shuts down

• Create counters

• Monitor the state of HTTP sessions and their attributes

Note: Application events are a new feature in the Java servlet specification, version 2.3 from Sun Microsystems. Version 2.3 is a proposed final draft of the servlet specification. If you are planning to use application events in your application, note that the specification has not been finalized and could change in the future.

The Servlet 2.3 specification is part of the J2EE 1.3 specification. To use J2EE 1.3 features, please see WebLogic Server 6.1 with J2EE 1.2 and J2EE 1.3 Functionality.

WebLogic Server 6.1 with J2EE 1.2 and J2EE 1.3 Functionality

BEA WebLogic Server 6.1 is the first e-commerce transaction platform to implement advanced J2EE 1.3 features. To comply with the rules governing J2EE, BEA Systems provides two separate downloads: one with J2EE 1.3 features enabled, and one that is limited to J2EE 1.2 features only. Both downloads offer the same container and differ only in the APIs that are available.

WebLogic Server 6.1 with J2EE 1.2 Plus Additional J2EE 1.3 Features

With this download, WebLogic Server defaults to running with J2EE 1.3 features enabled. These features include EJB 2.0, JSP 1.2, Servlet 2.3, and J2EE Connector Architecture 1.0. When you run WebLogic Server 6.1 with J2EE 1.3 features enabled, J2EE 1.2 applications are still fully supported. The J2EE 1.3 feature implementations use non-final versions of the appropriate API specifications. Therefore, application code developed for BEA WebLogic Server 6.1 that uses the new features of J2EE 1.3 may be incompatible with the J2EE 1.3 platform supported in future releases of BEA WebLogic Server.

WebLogic Server 6.1 with J2EE 1.2 Certification

With this download, WebLogic Server defaults to running with J2EE 1.3 features disabled and is fully compliant with the J2EE 1.2 specification and regulations.

 

---

Servlet Context Events

The following table lists the types of Servlet context events, the interface your event listener class must implement to respond to the event, and the methods invoked when the event occurs.

Type of Event	Interface	Method
Servlet context is created.	javax.servlet.ServletContextListener	contextInitialized()
Servlet context is about to be shut down.	javax.servlet.ServletContextListener	contextDestroyed()
An attribute is added.	javax.servlet. ServletContextAttributesListener	attributeAdded()
An attribute is removed.	javax.servlet. ServletContextAttributesListener	attributeRemoved()
An attribute is replaced.	javax.servlet. ServletContextAttributesListener	attributeReplaced()

 

---

HTTP Session Events

The following table lists the types of HTTP session events, the interface your event listener class must implement to respond to the event, and the methods invoked when the event occurs.

Type of Event	Interface	Method
An HTTP session is activated.	javax.servlet.http. HttpSessionListener	sessionCreated()
An HTTP session is about to be passivated.	javax.servlet.http. HttpSessionListener	sessionDestroyed()
An attribute is added.	javax.servlet.http. HttpSessionAttributeListener	attributeAdded()
An attribute is removed.	javax.servlet.http. HttpSessionAttributeListener	attributeRemoved()
An attribute is replaced.	javax.servlet.http. HttpSessionAttributeListener	attributeReplaced()

Note: The Servlet 2.3 specification also contains the javax.servlet.http.HttpSessionBindingListener and the javax.servlet.http.HttpSessionActivationListener interfaces. These interfaces are implemented by objects that are stored as session attributes and do not require registration of an event listener in web.xml. For more information, see the Javadocs for these interfaces.

 

---

Configuring an Event Listener

To configure an event listener:

1. Open the web.xml deployment descriptor of the Web Application for which you are creating an event listener in a text editor, or use the Web Application Deployment Descriptor Editor that is integrated into the Administration Console. (For more information, see Web Application Deployment Descriptor Editor Help.) The web.xml file is located in the WEB-INF directory of your Web Application.

2. Add an event declaration using the <listener> element. The event declaration defines the listener class that is invoked when the event occurs. The <listener> element must directly follow the <filter> and <filter-mapping> elements and directly precede the <servlet> element. You can specify more than one listener class for each type of event. WebLogic Server invokes the event listeners in the order that they appear in the deployment descriptor (except for shutdown events, which are invoked in the reverse order). For example:

   <listener>
     <listener-class>myApp.myContextListenerClass</listener-class>
   </listener>
   

   <listener>
     <listener-class>myApp.mySessionAttributeListenerClass</listen
   er-class>
   </listener>
   

3. Write and deploy the Listener class. See the next section, Writing a Listener Class, for details.

 

---

Writing a Listener Class

To write a listener class:

1. Create a new class that implements the appropriate interface for the type of event your class responds to. For a list of these interfaces, see Servlet Context Events or HTTP Session Events. See Templates for Listener Classes for sample templates you can use to get started.

2. Create a public constructor that takes no arguments.

3. Implement the required methods of the interface. See the J2EE API Reference (Javadocs) for more information.

4. Copy the compiled event listener classes into the WEB-INF/classes directory of the Web Application, or package them into a jar file and copy the jar file into the WEB-INF/lib directory of the Web Application.

The following useful classes are passed into the listener methods in a listener class:

javax.servlet.http.HttpSessionEvent

provides access to the HTTP session object

javax.servlet.ServletContextEvent

provides access to the servlet context object.

javax.servlet.ServletContextAttributeEvent

provides access to servlet context and its attributes

javax.servlet.http.HttpSessionBindingEvent

provides access to an HTTP session and its attributes

 

---

Templates for Listener Classes

The following examples provide some basic templates for listener classes.

Servlet Context Listener Example

package myApp;
import javax.servlet.*;

public final class myContextListenerClass implements
   ServletContextListener {
    public void contextInitialized(ServletContextEvent event) {

      /* This method is called when the servlet context is
         initialized(when the Web Application is deployed). 
         You can initialize servlet context related data here.
      */ 

    }

    public void contextDestroyed(ServletContextEvent event) {

      /* This method is invoked when the Servlet Context 
         (the Web Application) is undeployed or 
         WebLogic Server shuts down.
      */			    

    }
}

HTTP Session Attribute Listener Example

package myApp;
import javax.servlet.*;

public final class mySessionAttributeListenerClass implements
   HttpSessionAttributeListener {

    public void attributeAdded(HttpSessionBindingEvent sbe) {
      /* This method is called when an attribute 
         is added to a session.
      */
    }

    public void attributeRemoved(HttpSessionBindingEvent sbe) {
      /* This method is called when an attribute
         is removed from a session.
      */
    }

    public void attributeReplaced(HttpSessionBindingEvent sbe) {
      /* This method is invoked when an attibute
         is replaced in a session.
      */
    }
}

 

---

Additional Resources

• Assembling and Configuring Web Applications

• Writing Web Application Deployment Descriptors

• Servlet 2.3 Specification from Sun Microsystems

• J2EE API Reference (Javadocs)

• The J2EE Tutorial from Sun Microsystems: