Chapter 7 Developing Lifecycle Listeners

This chapter provides a basic overview, and a description of various features of lifecycle listeners in Web Server. 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

Web Server 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

Web Server 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 Web Server 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. Web Server will not support dynamic deployment of startup and shutdown classes. Any changes to these classes or their configuration requires server restart.

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;
 }
 }
}