|Oracle GlassFish Server Application Development Guide
Part Number E24930-01
Lifecycle listener modules provide a means of running short or long duration Java-based tasks within the Oracle GlassFish 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.
Lifecycle listener modules are deprecated. Support for them is included for backward compatibility. Implementing the org.glassfish.api.Startup interface instead is recommended.
All lifecycle module classes and interfaces are in the as-install
For Javadoc tool pages relevant to lifecycle modules, go to
http://glassfish.java.net/nonav/docs/v3/api/ and click on the
The following topics are addressed here:
A lifecycle module listens for and performs its tasks in response to the following events in the server life cycle:
INIT_EVENT, the server reads the configuration, initializes built-in subsystems (such as security and logging services), and creates the containers.
STARTUP_EVENT, the server loads and initializes deployed applications.
READY_EVENT, the server is ready to service requests.
SHUTDOWN_EVENT, the server destroys loaded applications and stops.
TERMINATION_EVENT, the server closes the containers, the built-in subsystems, and the server runtime environment.
These events are defined in the
The lifecycle modules that listen for these events implement 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.
com.sun.appserv.server.LifecycleEvent class defines a server life cycle event. The following methods are associated with the event:
This method returns an instance of
java.util.Properties that contains the properties defined for the lifecycle module.
public int getEventType()
This method returns the type of the last event, which is
This method returns the lifecycle event context, described next.
LifecycleEvent instance is passed to the
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:
This method returns the server startup command-line arguments.
This method returns the server installation root directory.
This method returns the server instance name.
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
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.
For instructions on how to deploy a lifecycle module, see the Oracle GlassFish Server Application Deployment Guide, or see the
asadmin create-lifecycle-module command in the Oracle GlassFish Server Reference Manual.
You do not need to specify a classpath for the lifecycle module if you place it in the domain-dir
/lib or domain-dir
/lib/classes directory for the Domain Administration Server. Do not place it in the lib directory for a particular instance, or it will be deleted when that instance synchronizes with the Domain Administration Server.
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 class loader is the parent class loader for lifecycle modules. Each lifecycle module's classpath is used to construct its class loader. All the support classes needed by a lifecycle module must be available to the LifeCycleModule class loader or its parent, the Connector class loader.
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
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