| 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 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. |
| |
| |
| [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/toc.html#GSDPG[GlassFish Server Open Source Edition Application Deployment |
| Guide], or see the `asadmin create-lifecycle-module` command in the |
| link:../reference-manual/toc.html#GSRFM[GlassFish Server Open Source Edition 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`. |
| |
| |