Lifecycle Module

Available:

Confluence 2.3 and later

 Lifecycle plugins allow you to perform tasks on application startup and shutdown

Application Lifecycle

Startup is performed after Confluence has brought up its Spring and Hibernate subsystems. If Confluence is being set up for the first time, the startup sequence is run after the completion of the setup wizard. This means that lifecycle plugins can assume access to a fully populated Spring container context, and a working database connection. (i.e. you don't need to check isContainerSetup() or isSetupComplete())

Shutdown is performed when the application server is shutting down the web application, but before the Spring context is disposed of.

Plugin Activation and Deactivation

Activating or deactivating a lifecycle plugin will not cause any of its lifecycle methods to be run. If you want your plugin to respond to activation and deactivation, you should make sure it implements Making your Plugin Modules State Aware.

Shutdown is not guaranteed

There are many situations in which the shutdown sequence will not be run, as it is dependent on the orderly shutdown of the application server. Plugins should not rely on shutdown being performed reliably, or even ever.

Shutdown lifecycle tasks are most useful for cleaning up resources or services that would otherwise leak in situations where the web application is being restarted, but the JVM is not exiting. (i.e. services that retain classloaders or threads that would otherwise prevent the application from being garbage-collected)

Defining a Lifecycle Plugin

Lifecycle plugin definitions are quite simple. Here's a sample atlassian-plugin.xml fragment:

<lifecycle key="frobozz" name="Frobozz Service" class="com.example.frobozz.Lifecycle" sequence="1200">
    <description>Start and stop the Frobozz service</description>
</lifecycle>
  • The key is the required plugin module key, which must be unique within the plugin.
  • The name is the required display name for the plugin.
  • The class is the required class name for the lifecycle service implementation.
  • The sequence number is required, and determines the order in which lifecycle plugins are run. On startup, they are run from lowest to highest sequence number, then in reverse order on shutdown.

Defining a Lifecycle Service Implementation

If you are implementing a new lifecycle service, you should implement com.atlassian.config.lifecycle.LifecycleItem:

package com.atlassian.config.lifecycle;

public interface LifecycleItem
{
    /**
     * Called on application startup.
     *
     * @param context the application's lifecycle context
     * @throws Exception if something goes wrong during startup. No more startup items will be run, and the
     *         application will post a fatal error, shut down all LifecycleItems that have run previously, and
     *         die horribly.
     */
    void startup(LifecycleContext context) throws Exception;

    /**
     * Called on application shutdown
     *
     * @param context the application's lifecycle context
     * @throws Exception if something goes wrong during the shutdown process. The remaining shutdown items
     *         will still be run, but the lifecycle manager will log the error.
     */
    void shutdown(LifecycleContext context) throws Exception;
}

However, for convenience, and to make it easy to plug in third-party lifecycle events that are implemented as servlet context listeners, lifecycle service classes can instead implement javax.servlet.ServletContextListener – the contextInitialized() method will be called on startup, and contextDestroyed() on shutdown.

Sequences

The sequence numbers of the lifecycle modules determine the order in which they are run. On startup, modules are run from lowest to highest sequence number, then on shutdown that order is reversed (first in, last out). As a general guideline:

Sequence number

Description

0 - 500

Configuration tweaks and application sanity checks.

800

Database and configuration upgrades.

1000

Zen Foundation configuration.

5000

Start/stop the Quartz scheduler

  • If your startup lifecycle item has a sequence less than 800, you can't assume that the configuration or database schema are current
  • If you have a sequence number greater than 5000, you must keep in mind that scheduled jobs (including Job Module) may run before you've started up, or after you've shut down.
Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport