Developing Applications with WebLogic Server

      

Programming Application Life Cycle Events

The following sections describe how to create applications that respond to WebLogic Server application life cycle events:

WARNING: Application-scoped startup and shutdown classes have been deprecated as of release 9.0 of WebLogic Server. The information in this chapter about startup and shutdown classes is provided only for backwards compatibility. Instead, you should use life cycle listener events in your applications.

 

Understanding Application Life Cycle Events

Application life cycle listener events provide handles on which developers can control behavior during deployment, undeployment, and redeployment. This section discusses how you can use the application life cycle listener events.

Four application life cycle events are provided with WebLogic Server, which can be used to extend listener, shutdown, and startup classes. These include:

For Startup and Shutdown classes, you only implement a main{} method. If you implement any of the methods provided for Listeners, they are ignored.

Note: No remove{} method is provided in the ApplicationLifecycleListener, because the events are only fired at startup time during deployment (prestart and poststart) and shutdown during undeployment (prestop and poststop).

 

Registering Events in weblogic-application.xml

In order to use these events, register them in the weblogic-application.xml deployment descriptor. See “Application Deployment Descriptor Elements.” Define the following elements:

 

Programming Basic Life Cycle Listener Functionality

You create a listener by extending the abstract class (provided with WebLogic Server) weblogic.application.ApplicationLifecycleListener. The container then searches for your listener.

You override the following methods provided in the WebLogic Server ApplicationLifecycleListener abstract class to extend your application and add any required functionality:

Listing 10-1 illustrates how you override the ApplicationLifecycleListener. In this example, the public class MyListener extends ApplicationLifecycleListener. Listing 10-1 MyListener 

import weblogic.application.ApplicationLifecycleListener;

import weblogic.application.ApplicationLifecycleEvent;

public class MyListener extends ApplicationLifecycleListener {

  public void preStart(ApplicationLifecycleEvent evt) {

     System.out.println

     ("MyListener(preStart) -- we should always see you..");

   } // preStart

  public void postStart(ApplicationLifecycleEvent evt) {

     System.out.println

     ("MyListener(postStart) -- we should always see you..");

   } // postStart

  public void preStop(ApplicationLifecycleEvent evt) {

     System.out.println

     ("MyListener(preStop) -- we should always see you..");

   } // preStop

  public void postStop(ApplicationLifecycleEvent evt) {

     System.out.println

     ("MyListener(postStop) -- we should always see you..");

   } // postStop

   public static void main(String[] args) {

     System.out.println

     ("MyListener(main): in main .. we should never see you..");

   } // main

}

Listing 10-2 illustrates how you implement the shutdown class. The shutdown class is attachable to preStop and postStop events. In this example, the public class MyShutdown does not extend ApplicationLifecycleListener because a shutdown class declared in the weblogic-application.xml deployment descriptor does not need to depend on any WebLogic Server-specific interfaces. Listing 10-2 MyShutdown 

import weblogic.application.ApplicationLifecycleListener;

import weblogic.application.ApplicationLifecycleEvent;

public class MyShutdown {

   public static void main(String[] args) {

     System.out.println

     ("MyShutdown(main): in main .. should be for post-stop");

   } // main

}

Listing 10-3 illustrates how you implement the startup class. The startup class is attachable to preStart and postStart events. In this example, the public class MyStartup does not extend ApplicationLifecycleListener because a startup class declared in the weblogic-application.xml deployment descriptor does not need to depend on any WebLogic Server-specific interfaces. Listing 10-3 MyStartup 

import weblogic.application.ApplicationLifecycleListener;

import weblogic.application.ApplicationLifecycleEvent;

public class MyStartup {

   public static void main(String[] args) {

     System.out.println

     ("MyStartup(main): in main .. should be for pre-start");

   } // main

}

 

Configuring a Role-Based Application Life Cycle Listener

You can configure an application life cycle event with role-based capability where a user identity can be specified to startup and shutdown events using the run-as-principal-name element. However, if the run-as-principal-name identity defined for the application life cycle listener is an administrator, the application deployer must have administrator privileges; otherwise, deployment will fail.

  1. Follow the basic programming steps outlined in Programming Basic Life Cycle Listener Functionality.

  2. Within the listener element add the run-as-principal-name element to specify the user who has privileges to startup and/or shutdown the event. For example: 
    <listener>

      <listener-class>myApp.MySessionAttributeListenerClass</listener-class>

      <run-as-principal-name>javajoe</run-as-principal-name>

    </listener>

The identity specified here should be a valid user name in the system. If run-as-principal-name is not specified, the deployment initiator user identity will be used as the run-as identity for the execution of the application life cycle listener.

 

Examples of Configuring Life Cycle Events with and without the URI Parameter

The following examples illustrate how you configure application life cycle events in the weblogic-application.xml deployment descriptor file. The URI parameter is not required. You can place classes anywhere in the application $CLASSPATH. However, ensure that the class locations are defined in the $CLASSPATH. You can place listeners in APP-INF/classes or APP-INF/lib, if these directories are present in the EAR. In this case, they are automatically included in the $CLASSPATH.

The following example illustrates how you configure application life cycle events using the URI parameter. In this case, the archive foo.jar contains the classes and exists at the top level of the EAR file. For example: myEar/foo.jar Listing 10-4 Configuring Application Life Cycle Events Using the URI Parameter 

  <listener>

       <listener-class>MyListener</listener-class>

       <listener-uri>foo.jar</listener-uri>

  </listener>

  <startup>

       <startup-class>MyStartup</startup-class>

       <startup-uri>foo.jar</startup-uri>

  </startup>

  <shutdown>

       <shutdown-class>MyShutdown</shutdown-class>

       <shutdown-uri>foo.jar</shutdown-uri>

  </shutdown>

The following example illustrates how you configure application life cycle events without using the URI parameter. Listing 10-5 Configuring Application Life Cycle Events without Using the URI Parameter 

 <listener>

       <listener-class>MyListener</listener-class>

  </listener>

  <startup>

       <startup-class>MyStartup</startup-class>

  </startup>

  <shutdown>

       <shutdown-class>MyShutdown</shutdown-class>

  </shutdown>

 

Understanding Application Life Cycle Event Behavior During Re-deployment

Application life cycle events are only triggered if a full re-deployment of the application occurs. During a full re-deployment of the application—provided the application life cycle events have been registered—the application life cycle first commences the shutdown sequence, next re-initializes its classes, and then performs the startup sequence.

For example, if your listener is registered for the full application life cycle set of events (preStart, postStart, preStop, postStop), during a full re-deployment, you see the following sequence of events:

  1. preStop{}

  2. postStop{}

  3. Initialization takes place. (Unless you have set debug flags, you do not see the initialization.)

  4. preStart{}

  5. postStart{}

 

Programming Application Version Life Cycle Events

The following sections describe how to create applications that respond to WebLogic Server application version life cycle events:

 

Understanding Application Version Life Cycle Event Behavior

WebLogic Server provides application version life cycle event notifications by allowing you to extend the ApplicationVersionLifecycleListener class and specify a life cycle listener in weblogic-application.xml. See Application Deployment Descriptor Elements and Examples of Configuring Life Cycle Events with and without the URI Parameter.

Application version life cycle events are invoked:

 

Types of Application Version Life Cycle Events

Four application version life cycle events are provided with WebLogic Server:

 

Example of Production Deployment Sequence When Using Application Version Life Cycle Events

The following table provides an example of a deployment (V1), production redeployment (V2), and an undeploy (V2).

Table 10-1 Sequence of Deployment Actions and Application Version Life Cycle Events
Deployment action Time Version V1 Version V2
Deployment of Version V1 T0 preDeploy(V1) invoked.
T1 Deployment starts.
T2 Application life cycle listeners for V1 are registered.
T3 V1 is active version, Deployment is complete.
T4 postDeploy(V1) invoked.
T5 Application Listeners gets postDeploy(V1).
Production Redeployment of Version V2 T6 preDeploy(V2) invoked.
T7 Application version listener receives preDeploy(V1).
T8 Deployment starts.
T9 Application life cycle listeners for V2 are registered.
T10 If deploy(V2) succeeds, V1 ceases to be active version. If deploy(V2) succeeds, V2 replaces V1 as active version. Deployment is complete.
T11 postDeploy(V2) invoked.

This event occurs even if the deployment fails.

T12 Application version listener gets postDeploy(V2). If deploy(V2) fails, V1 remains active. T13 Application listeners gets postDeploy(V2). T14 If deploy(V2) succeeds, V1 begins retirement. T15 Application listeners for V1 are unregistered. T16 V1 is retired. Undeployment of V2 T17 preUndeploy(v2) invoked. T18 Application listeners gets preUndeploy(v2) invoked. T19 Undeployment begins. T20 V2 is no longer active version. T21 Application version listeners for V2 are unregistered. T22 Undeployment is complete. T23 If the entire application is undeployed, postDelete(V2) is invoked.

This event occurs even if the undeployment fails.