Developing Applications with WebLogic Server

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Programming Application Lifecycle Events

The following sections describe how to create applications that respond to WebLogic Server application lifecycle 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 lifecycle listener events in your applications.

 


Understanding Application Lifecycle Events

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

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

Note: 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, you must register them in the weblogic-application.xml deployment descriptor. See “Application Deployment Descriptor Elements.” Define the following elements:

 


Programming Basic Lifecycle 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 Lifecycle Listener

You can configure an application lifecycle 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 lifecycle 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 Lifecycle 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:
  3. <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 lifecycle listener.

 


Examples of Configuring Lifecycle Events with and without the URI Parameter

The following examples illustrate how you configure application lifecycle 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, you must 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 lifecycle 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 Lifecycle 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 lifecycle events without using the URI parameter.

Listing 10-5 Configuring Application Lifecycle 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 Lifecycle Event Behavior During Re-deployment

Application lifecycle events are only triggered if a full re-deployment of the application occurs. During a full re-deployment of the application—provided the application lifecycle events have been registered—the application lifecycle 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 lifecycle 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 Lifecycle Events

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

Understanding Application Version Lifecycle Event Behavior

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

Application version lifecycle events are invoked:

Types of Application Version Lifecycle Events

Four application version lifecycle events are provided with WebLogic Server:

Example of Production Deployment Sequence When Using Application Version Lifecycle 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 Lifecycle Events
Deployment action
Time
Version V1
Version V2
Deployment of Version V1
T0
preDeploy(V1) invoked.
 
T1
Deployment starts.
 
T2
Application lifecycle 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 lifecycle 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.

Note: 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.

Note: This event occurs even if the undeployment fails.


  Back to Top       Previous  Next