This chapter provides a basic overview, and a description of various features of lifecycle listeners in Web Server. It includes the following sections:
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.
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 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 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()
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.
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. |
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.
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; } } }