docs/application-development-guide/src/main/asciidoc/lifecycle-listeners.adoc

type=page
status=published
title=Developing Lifecycle Listeners
next=osgi.html
prev=connectors.html
~~~~~~

= Developing Lifecycle Listeners

[[GSDVG00014]][[beamc]]


[[developing-lifecycle-listeners]]
== 12 Developing Lifecycle Listeners

Lifecycle listener modules provide a means of running short or long
duration Java-based tasks within the {productName}
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.


[NOTE]
====
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``/modules/``glassfish-api.jar`` file.

For Javadoc tool pages relevant to lifecycle modules, see the
`com.sun.appserv.server` package.

The following topics are addressed here:

* link:#beamd[Server Life Cycle Events]
* link:#beame[The LifecycleListener Interface]
* link:#beamf[The `LifecycleEvent` Class]
* link:#beamg[The Server Lifecycle Event Context]
* link:#beamh[Deploying a Lifecycle Module]
* link:#beami[Considerations for Lifecycle Modules]

[[beamd]][[GSDVG00167]][[server-life-cycle-events]]

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

[[beame]][[GSDVG00168]][[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:

[source,java]
----
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.

[[beamf]][[GSDVG00169]][[the-lifecycleevent-class]]

=== 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 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 `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.

[[beamg]][[GSDVG00170]][[the-server-lifecycle-event-context]]

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

[[beamh]][[GSDVG00171]][[deploying-a-lifecycle-module]]

=== Deploying a Lifecycle Module

For instructions on how to deploy a lifecycle module, see the
link:application-deployment-guide.html#GSDPG[{productName} Application Deployment
Guide], or see the `asadmin create-lifecycle-module` command in the
link:reference-manual.html#GSRFM[{productName} 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.

[[beami]][[GSDVG00172]][[considerations-for-lifecycle-modules]]

=== 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 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
link:securing-apps.html#beabx[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`.