Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Developer's Guide

- Previous: Chapter 9 Developing Connectors
- Next: Part III Using Services and APIs

# Chapter 10 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.

All lifecycle module classes and interfaces are in the install-dir`/lib/``appserv-rt.jar` file.

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

- Server Life Cycle Events

- The LifecycleListener Interface

- The LifecycleEvent Class

- The Server Lifecycle Event Context

- 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:

- After the `INIT_EVENT`, the server reads the configuration, initializes built-in subsystems (such as security and logging services), and creates the containers.

- After the `STARTUP_EVENT`, the server loads and initializes deployed applications.

- After the `READY_EVENT`, the server is ready to service requests.

- After the `SHUTDOWN_EVENT`, the server destroys loaded applications and stops.

- After 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.

# 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.

# 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 type of the last event, 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 after the `STARTUP_EVENT`. A lifecycle module can look up any resource by its `jndi-name` attribute after the `READY_EVENT`.

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

# Deploying a Lifecycle Module

You can deploy a lifecycle module using the following tools:

- In the Administration Console, open the Applications component and go to the Lifecycle Modules page. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

- Use the ```asadmin create-lifecycle-module` command. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Reference Manual.

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.

Note –

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

# Considerations for Lifecycle Modules

The resources allocated at initialization or startup should be freed at 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 can create threads if appropriate, but these threads must be stopped in the shutdown and termination phases.

The LifeCycleModule Classloader is the parent class loader for lifecycle modules. Each lifecycle module’s `classpath` in `domain.xml` is used to construct its class loader. All the support classes needed by a lifecycle module must be available to the LifeCycleModule Classloader or its parent, the Connector Classloader.

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

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

- Previous: Chapter 9 Developing Connectors
- Next: Part III Using Services and APIs

- © 2010, Oracle Corporation and/or its affiliates