Developing Lifecycle Listeners

Lifecycle listener modules provide a means of running short or long duration Java-based tasks within the application server environment, such as instantiation of singletons or RMI servers. These modules are automatically initiated at server startup and are notified at various phases of the server life cycle.

The following sections describe how to create and use a lifecycle module:

• Server Life Cycle Events
• The LifecycleListener Interface
• The LifecycleEvent Class
• The Server Lifecycle Event Context
• Assembling and Deploying a Lifecycle Module
• Considerations for Lifecycle Modules

Server Life Cycle Events

---

A lifecycle module listens for and performs its tasks in response to the following events in the server life cycle:

• During the INIT_EVENT, the server reads the configuration, initializes built-in subsystems (such as security and logging services), and creates the containers.
• During the STARTUP_EVENT, the server loads and initializes deployed applications.
• During the READY_EVENT, the server is ready to service requests.
• During the SHUTDOWN_EVENT, the server destroys loaded applications and stops.
• During the TERMINATION_EVENT, the server closes the containers, the built-in subsystems, and the server runtime environment.

These events are defined in the LifecycleEvent class.

The lifecycle modules that listen for these events implement the LifecycleListener interface and are configured in the server.xml file.

The LifecycleListener Interface

---

To create a lifecycle module is to configure a customized class that implements the com.sun.appserv.server.LifecycleListener interface. You can create and simultaneously execute multiple lifecycle modules.

The LifecycleListener interface defines this method:

• public void handleEvent(com.sun.appserv.server.LifecycleEvent event) throws ServerLifecycleException

This method responds to a lifecycle event and throws a com.sun.appserv.server.ServerLifecycleException if an error occurs.

A sample implementation of the LifecycleListener interface is the LifecycleListenerImpl.java file, which you can use for testing lifecycle events:

package com.sun.appserv.server;

import java.util.Properties;

/**
 * LifecycleListenerImpl is a dummy implementation for the LifecycleListener
 * interface.This implementaion 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 exceptional condition.
    *
    * Configure this module as a lifecycle-module in server.xml:
    *
    * <applications>
    *      <lifecycle-module name="test"
    *               class-name="com.sun.appserv.server.LifecycleListenerImpl"
    *               is-failure-fatal="false">
    *         <property name="foo" value="fooval"/>
    *      </lifecycle-module>
    * </applications>
    *
    * Set<code>is-failure-fatal</code>in server.xml to <code>true</code> for
    * fatal conditions.
    */
   public void handleEvent(LifecycleEvent event) throws ServerLifecycleException
   {
      LifecycleEventContext context = event.getLifecycleEventContext();

      context.log("got event" + event.getEventType() + " event data: "
         + event.getData());

      Properties props;

      if (LifecycleEvent.INIT_EVENT == event.getEventType()) {
         context.log("LifecycleListener: INIT_EVENT");

         props = (Properties) event.getData();

         // handle INIT_EVENT
         return;
      }

      if (LifecycleEvent.STARTUP_EVENT == event.getEventType()) {
         context.log("LifecycleListener: STARTUP_EVENT");

         // handle STARTUP_EVENT
         return;
      }

      if (LifecycleEvent.READY_EVENT == event.getEventType()) {

         context.log("LifecycleListener: READY_EVENT");

         // handle READY_EVENT
         return;
      }

      if (LifecycleEvent.SHUTDOWN_EVENT== event.getEventType()) {
         context.log("LifecycleListener: SHUTDOWN_EVENT");

         // handle SHUTDOWN_EVENT
         return;
      }

      if (LifecycleEvent.TERMINATION_EVENT == event.getEventType()) {
         context.log("LifecycleListener: TERMINATE_EVENT");

         // handle TERMINATION_EVENT
         return;
      }
   }
}

The LifecycleEvent Class

---

The com.sun.appserv.server.LifecycleEvent class defines a server life cycle event. The following methods are associated with the event:

• public java.lang.Object getData()

This method returns the data associated with the event.

• public int getEventType()

This method returns the event type, which is INIT_EVENT, STARTUP_EVENT, READY_EVENT, SHUTDOWN_EVENT, or TERMINATION_EVENT.

• public com.sun.appserv.server.LifecycleEventContext getLifecycleEventContext()

This method returns the lifecycle event context, described next.

A LifecycleEvent instance is passed to the LifecycleListener.handleEvent method.

The Server Lifecycle Event Context

---

The com.sun.appserv.server.LifecycleEventContext interface exposes runtime information about the server. The lifecycle event context is created when the LifecycleEvent class is instantiated at server initialization. The LifecycleEventContext interface defines these methods:

• public java.lang.String[] getCmdLineArgs()

This method returns the server startup command-line arguments.

• public java.lang.String getInstallRoot()

This method returns the server installation root directory.

• public java.lang.String getInstanceName()

This method returns the server instance name.

• public javax.naming.InitialContext getInitialContext()

This method returns the initial JNDI naming context. The naming environment for lifecycle modules is installed during the STARTUP_EVENT. A lifecycle module can look up any resource defined in the server.xml file by its jndi-name attribute after the STARTUP_EVENT is complete.




---

Note	To avoid collisions with names of other enterprise resources in JNDI, and to avoid portability problems, all names in a Sun ONE Application Server lifecycle module should begin with the string java:comp/env.

---




If a lifecycle module needs to look up resources, it can do so in the READY_EVENT. It can use the getInitialContext() method to get the initial context to which all the resources are bound.

• public void log(java.lang.String message)

This method writes the specified message to the server log file. The message parameter is a String specifying the text to be written to the log file.

• public void log(java.lang.String message, java.lang.Throwable throwable)

This method writes an explanatory message and a stack trace for a given Throwable exception to the server log file. The message parameter is a String that describes the error or exception. The throwable parameter is the Throwable error or exception.

Assembling and Deploying a Lifecycle Module

---

You assemble a lifecycle module as described in "Assembling a Lifecycle Module". You deploy a lifecycle module as described in "Deploying a Lifecycle Module".

During lifecycle module deployment, a lifecycle-module element is created in the server.xml file. You can edit this file to change its configuration. The property subelement allows you to specify input parameters. For example:

<lifecycle-module                   name="customStartup"
                  enabled="true"
                  class-name="com.acme.CustomStartup"
                  classpath="/apps/customStartup"
                  load-order="200"
                  is-failure-fatal="true">
   <description>custom startup module to do my tasks</description>
   <property name="rmiServer" value="acme1:7070" />
   <property name="timeout" value="30" />
</lifecycle-module>

Note that if is-failure-fatal is set to true (the default is false), lifecycle module failure prevents server initialization or startup, but not shutdown or termination.

For more information about the server.xml file, see the Sun ONE Application Server Administrator's Configuration File Reference.

After you deploy a lifecycle module, you must restart the server to activate it. The server instantiates it and registers it as a lifecycle event listener at server initialization.

Considerations for Lifecycle Modules

---

The resources allocated during initialization or startup should be freed during shutdown or termination. The lifecycle module classes are called synchronously from the main server thread, therefore it is important to ensure that these classes don't block the server. Lifecycle modules may create threads if appropriate, but these threads must be stopped in the shutdown and termination phases.

The LifeCycleModule Classloader is the parent classloader for lifecycle modules. Each lifecycle module's classpath in server.xml is used to construct its classloader. All the support classes needed by a lifecycle module must be available to the LifeCycleModule Classloader or its parent, the Shared Classloader. (The Shared Classloader loads server-wide resources.)

You must ensure that the server.policy file is appropriately set up, or a lifecycle module trying to perform a System.exec() may cause a security access violation. For details, see "The server.policy File".

The configured properties for a lifecycle module are passed as properties in the INIT_EVENT. The JNDI naming context is not available in the INIT_EVENT. If a lifecycle module requires the naming context, it can get this in the STARTUP_EVENT, READY_EVENT, or SHUTDOWN_EVENT.