Chapter 7 Developing Lifecycle Listeners

This chapter provides a basic overview, and a description of various features of lifecycle listeners in Sun Java System Web Server 7.0. It includes the following sections:

• Server Lifecycle Events

• The LifecycleListener Interface

• The LifecycleEvent Class

• The Server Lifecycle Event Context

• Deploying a Lifecycle Module

• Considerations for Lifecycle Modules

• Sample Lifecycle Configuration

Server Lifecycle Events

Sun Java System Web Server 7.0 goes through different events in its lifecycle:

• init - This event includes reading configuration, initializing built-in subsystems, naming, security and logging services, and creating the web container.

• startup - loading and initializing deployed applications.

• service - The server is ready to service requests shut down: stopping and destroying loaded applications. The system is preparing to shut down.

• terminating - The container is being closed, which terminates the built-in subsystems and server runtime environment.

• reconfig - A transient server state in which a server thread is dynamically reconfiguring while the rest of the server in the service state. This state can occur several times during the life of the server.

The LifecycleListener Interface

Sun Java System Web Server 7.0 enables you to write classes and customize various phases of the server lifecycle. For instance, you may have a startup code that ensures a remote data source is available for the applications. Such classes are notified by server lifecycle events. The Sun Java System Web Server 7.0 defines a LifecycleListener interface that users can implement and register with the Server.

The syntax of this interface is as follows public void handleEvent(LifecycleEvent event): receives a lifecycle event.

In its event parameter, the programmatic interface for LifecycleListener provides the following features to the implementation classes:

• Access to initialization parameters

• A handler to the server run time environment for naming, logging and accessing resources

• Exception-handling mechanics

The LifecycleEvent Class

The LifecycleEventclass is an interface from the point of view to the developer, even if programmatically it is a class. This interface is the means by which these events are represented. This class informs you of the kind of event that happened through the getEventType() method and the data associated with the event (through the getData() method).

The Server Lifecycle Event Context

The LifecycleEventContext interface provides an access to the server runtime environment including the JNDI naming context and logging service. The following methods are defined in this interface:

• public String[] getCmdLineArgs()- Returns the server command line arguments.

• public javax.naming.Context getNamingContext()- Returns the naming context.

• public String getInstallRoot()- Returns the installation root.

• public String getInstanceName()- Returns the server instance name.

• public void log(java.util.logging.Level level, String message)- Logs the message to the server log, with verbosity level.

• public void log(java.util.logging.Level level, String message, Throwable throwable)- Logs the message and the stack trace for throwable, with verbosity level.

The following two methods are also used by this interface to keep backward compatibility with the 6.1 version of Web Server:

• public void log(String message, Throwable throwable): - Logs the message and the stack trace for throwable, with verbosity level.

• public javax.naming.Context getInitialContext() - Similar to getNamingContext()

Deploying a Lifecycle Module

Server lifecycle listener classes are visible in the serve applications management area. You can add, delete, update, enable, and disable listener classes and set their parameters. Sun Java System Web Server 7.0 will not support dynamic deployment of startup and shutdown classes. Any changes to these classes or their configuration requires server restart.

Table 7–1 Elements of the lifecycle

Configurable element / attribute	Data type and Units	Range of values	Remarks
lifecycle-module.name	String	Any non-null/non-empty unique string in lifecycle modules.	Must be specified while registering this lifecycle module.
lifecycle-module.class	String	Fully qualified Java class name.	Must implement the LifecycleListener interface.
lifecycle-module.enabled	Boolean	true or false.	Default is true.
lifecycle-module.load-order	Integer	0-100 Reserved. 100-MAXINT.	Order of loading the lifecycle event listeners in numerical order. Choose a load-order greater than or equal to 100 to avoid conflicts with internal lifecycle modules.
lifecycle-module.is-failure-fatal	Boolean	true or false	If you want the server to treat exceptions thrown from the listener classes as fatal and prevent continuation of normal startup, set this element to true.
lifecycle-module.class-path	String	Optional	Points to the user-specified classpath for the listener class.
lifecycle-module.description	Element	Optional	Describes the lifecycle module.
property.name	String	Optional	User-specified parameter name. Part of the property element.
property.value	String.	Optional	User-specified parameter value. Part of the property element.
property.description	String	Optional	User-specified description. Part of the property element.

Considerations for Lifecycle Modules

When using keep the following points in mind of lifecycle module:

• The server lifecycle listener classes are called synchronously from the main server thread. Therefore, take extra precautions must be taken to ensure that the listener classes don't block the server.

• The listener classes may create threads if appropriate. The threads must be stopped during the shutdown and termination phases.

• The resources allocated during initialization or startup events should be cleared.

• The listener classes are loaded in the context of server's root class loader, which loads server-wide resources as well. Therefore, all the support classes needed by these server lifecycle event listener must be available at this class loader or its parent, the system class loader. As a consequence, you must ensure that the Java security manager policy files are appropriately set up, Otherwise, a lifecycle listener class trying to perform a System.exec()may get a security access violation.

Sample Lifecycle Configuration

The following example shows a portion of the server.xml that defines a lifecycle listener.

<lifecycle-module>
<class-name>com.sun.ias.server.LifecycleListenerImpl</class-name>
<is-failure-fatal>false</is-failure-fatal>
<description>Sample lifecycle module</description>
<property>
<name>foo</name>
<value>fooval</value>
<property>
</lifecycle-module>

The following example shows a sample LifecycleListener implementation

/** 
*PROPERITARY/CONFIDENTIAL. Use of this product is subject to license terms
*
*Copyright 2006-2007 by SunMicrosystems, Inc.,
*4150 Network Circle, Santa Clara, California, 95054, U.S.A
*All rights reserved.
package com.sun.ias.server;
import java.util.Properties; 
import java.util.logging.Level;  
import com.sun.appserv.server.LifecycleEventContext; 
import com.sun.appserv.server.ServerLifecycleException; 
import com.sun.appserv.server.LifecycleEvent; 
import com.sun.appserv.server.LifecycleListener;
 /**
  * LifecycleListenerImpl is a dummy implementation for the LifecycleListener 
  * interface.
  * This implementation stubs out various lifecycle interface methods.
  */ 
public class LifecycleListenerImpl implements LifecycleListener {
/** receive a server lifecycle event
* @param event associated event
* @throws <code>ServerLifecycleException</code> for exception condition.
* 
* /
public void handleEvent(LifecycleEvent event) throws ServerLifecycleException {
LifecycleEventContex ctx=event.getLifecycleEventContext();

ctx.log(level.INFO, "got event" + event.getEventType() + "event data:" + 
event.getData());

Properties props;

if (Lifecycleevent.INIT_EVENT == event.getEventType()) {
System.out.println("LifecycleListener: INIT_EVENT");

props = (Properties) event.getData();

//handle INIT_EVENT
return;
}

if (LifecycleEvent.STARTUP_EVENT == event.getEventType()) {
System.out.println("LifecycleListener: START_EVENT");
//handle STARTUP_EVENT
return;
}
if (LifecycleEvent.READY_EVENT == event.getEventType()) {
System.out.println("LifecycleListener: READY_EVENT");
//handle READY_EVENT
return;
}

if (LifecycleEvent.SHUTDOWN_EVENT == event.getEventType()) {
System.out.println("LifecycleListener: SHUTDOWN_EVENT");
//handle SHUTDOWN_EVENT
return;
} if (LifecycleEven.TERMINATION_EVENT == event.getEventType()) {
System.out.println("LifecycleListener: TERMINATION_EVENT");
//handle TERMINATION_EVENT
return;
 }
 }
}