Sun Java System Application Server Enterprise Edition 8.1 2005Q1 Developer's Guide |
Chapter 10
Developing Lifecycle ListenersLifecycle 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 EventsA 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 InterfaceTo 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:
A sample implementation of the LifecycleListener interface is the LifecycleListenerImpl.java file, which you can use for testing lifecycle events.
The LifecycleEvent ClassThe com.sun.appserv.server.LifecycleEvent class defines a server life cycle event. The following methods are associated with the event:
A LifecycleEvent instance is passed to the LifecycleListener.handleEvent method.
The Server Lifecycle Event ContextThe 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:
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 ModuleYou 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 Administration Guide.
- Use the asadmin create-lifecycle-module command. For details, see the Sun Java System Application Server 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 ModulesThe 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 classloader for lifecycle modules. Each lifecycle module’s classpath in domain.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 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” on page 45.
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.