Lifecycle Plugins

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

• For more information about plugins in general, read Confluence Plugin Guide.
• To learn how to install and configure plugins (including macros), read Installing and Configuring Plugins manually.
• For an introduction to writing your own plugins, read Writing Confluence Plugins

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.

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:

• 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 Plugins) may run before you've started up, or after you've shut down.