docs/administration-guide/src/main/asciidoc/lifecycle-modules.adoc

type=page
status=published
title=Administering Life Cycle Modules
next=batch.html
prev=monitoring.html
~~~~~~

= Administering Life Cycle Modules

[[GSADG00013]][[giury]]


[[administering-life-cycle-modules]]
== 9 Administering Life Cycle Modules

This chapter provides procedures for administering life cycle modules in
the {productName} 7 environment.

The following topics are addressed here:

* link:#giuxo[About Life Cycle Modules]
* link:#giuue[Configuring Life Cycle Modules]

Instructions for accomplishing the tasks in this chapter by using the
Administration Console are contained in the Administration Console
online help.

[[giuxo]][[GSADG00566]][[about-life-cycle-modules]]

=== About Life Cycle Modules

Life cycle modules, also known as initialization services, provide a
means of running short or long duration Java-based tasks within the
{productName} environment. These modules are automatically initiated
at server startup and are notified at various phases of the server life
cycle. Configured properties for a life cycle module are passed as
properties during server initialization.

All life cycle module classes and interfaces are in the
as-install``/modules/glassfish-api.jar`` file.

A life cycle module listens for and performs its tasks in response to
the following {productName} sequence of events:

1. Initialization. The server reads the configuration, initializes
built-in subsystems (such as security and logging services), and creates
the containers.
2. Startup. The server loads and initializes deployed applications.
3. Ready. The server begins servicing requests.
4. Shutdown. The server shuts down the applications and stops.
5. Termination. The server closes the containers, the built-in
subsystems, and the server runtime environment.

These events are defined in the `LifecycleEvent` class. For information
on creating life cycle modules, see "link:application-development-guide/lifecycle-listeners.html#GSDVG00014[Developing
Lifecycle Listeners]" in {productName}
Application Development Guide.


[NOTE]
====
If the `is-failure-fatal` setting is set to true (the default is false),
life cycle module failure prevents server initialization or startup, but
not shutdown or termination.
====


[[giuue]][[GSADG00567]][[configuring-life-cycle-modules]]

=== Configuring Life Cycle Modules

The following topics are addressed here:

* link:#giuus[To Create a Life Cycle Module]
* link:#giuvh[To List Life Cycle Modules]
* link:#giuyh[To Update a Life Cycle Module]
* link:#giuux[To Delete a Life Cycle Module]

[[giuus]][[GSADG00399]][[to-create-a-life-cycle-module]]

==== To Create a Life Cycle Module

Use the `create-lifecycle-module` subcommand in remote mode to create a
life cycle module.

1. Ensure that the server is running. Remote subcommands require a running server.
2. Create a new life cycle modules by using the
link:reference-manual/create-lifecycle-module.html#GSRFM00043[`create-lifecycle-module`] subcommand.
+
Information about options and properties for the subcommand are included
in this help page.
3. Restart the server for your changes to take effect.
+
See link:domains.html#ginqj[To Restart a Domain].

[[GSADG00206]][[giuyo]]
Example 9-1 Creating a Life Cycle Module

This example creates the `customSetup` life cycle module :

[source]
----
asadmin> create-lifecycle-module --classname "com.acme.CustomSetup"
--classpath "/export/customSetup" --loadorder 1 --failurefatal=true
--description "this is a sample customSetup"
--property rmi="Server\=acme1\:7070":timeout=30 customSetup
Command create-lifecycle-module executed successfully
----

[[GSADG927]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help create-lifecycle-module` at the command line.

[[giuvh]][[GSADG00400]][[to-list-life-cycle-modules]]

==== To List Life Cycle Modules

Use the `list-lifecycle-modules` subcommand in remote mode to list the
existing life cycle modules.

1. Ensure that the server is running. Remote subcommands require a running server.
2. List life cycle modules by using the
link:reference-manual/list-lifecycle-modules.html#GSRFM00181[`list-lifecycle-modules`] subcommand.

[[GSADG00207]][[giuyr]]
Example 9-2 Listing Life Cycle Modules

This example lists the existing life cycle modules.

[source]
----
asadmin> list-lifecycle-modules
WSTCPConnectorLCModule
Command list-lifecycle-modules executed successfully
----

[[GSADG928]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help list-lifecycle-modules` at the command line.

[[giuyh]][[GSADG00401]][[to-update-a-life-cycle-module]]

==== To Update a Life Cycle Module

Use the `set` subcommand to update an existing life cycle module.

1. List the properties that can be updated for a life cycle module by
using the link:reference-manual/get.html#GSRFM00139[`get`] subcommand.
+
For example (single mode):
+
[source]
----
asadmin get "*" | grep sampleLCM
applications.application.sampleLCMmodule.availability-enabled=false
applications.application.sampleLCMmodule.directory-deployed=false
applications.application.sampleLCMmodule.enabled=true
applications.application.sampleLCMmodule.name=sampleLCMmodule
applications.application.sampleLCMmodule.object-type=user
applications.application.sampleLCMmodule.property.class-name=example.lc.SampleModule
applications.application.sampleLCMmodule.property.classpath=/build/lcm.jar
applications.application.sampleLCMmodule.property.is-failure-fatal=false
applications.application.sampleLCMmodule.property.isLifecycle=true
----
2. Update a life cycle module by using the olink:GSRFM00226[`set`]
subcommand.
3. Restart the server for your changes to take effect.
+
See link:domains.html#ginqj[To Restart a Domain].

[[GSADG00208]][[giuyq]]
Example 9-3 Updating a Life Cycle Module

This example updates the `classpath` property.

[source]
----
sadmin> set applications.application.sampleLCMmodule.
property.classpath=/build/lcm_new.jarapplications.application.
sampleLCMmodule.property.classpath=/build/lcm_new.jar
Command set executed successfully.
----

[[GSADG929]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help set` at the command line.

[[giuux]][[GSADG00402]][[to-delete-a-life-cycle-module]]

==== To Delete a Life Cycle Module

Use the `delete-lifecycle-module` subcommand in remote mode to delete a
life cycle module.

1. Ensure that the server is running. Remote subcommands require a running server.
2. List the current life cycle modules by using the
link:reference-manual/list-lifecycle-modules.html#GSRFM00181[`list-lifecycle-modules`] subcommand.
3. Delete a life cycle module by using the
link:reference-manual/delete-lifecycle-module.html#GSRFM00095[`delete-lifecycle-module`] subcommand.

[[GSADG00209]][[giuyi]]
Example 9-4 Deleting a Life Cycle Module

This example deletes the `customSetup` life cycle module.

[source]
----
asadmin> delete-lifecycle-module customSetup
Command delete-lifecycle-module executed successfully
----

[[GSADG930]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help delete-lifecycle-module` at the command line.