15 Programming Application Life Cycle Events

Learn how to create applications that respond to WebLogic Server application life cycle events.

This chapter includes the following sections:

Understanding Application Life Cycle Events

Application life cycle listener events provide handles on which developers can control behavior during deployment, undeployment, and redeployment. Learn 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:

• Listeners—attachable to any event. Possible methods for Listeners are:

  • public void preStart(ApplicationLifecycleEvent evt) {}

    preStart is invoked during application prepare, before preparation of the application has completed.

  • public void postStart(ApplicationLifecycleEvent evt) {}

    postStart is invoked near the end of application activation, after application initialization.

  • public void preStop(ApplicationLifecycleEvent evt) {}

    preStop is invoked as application deactivation begins.

  • public void postStop(ApplicationLifecycleEvent evt) {}

    postStop is invoked during application unprepare, after the application has been deactivated. It is not a callback for the separate remove phase.

• Shutdown classes only get postStop events.

  Note:

  Application-scoped shutdown classes have been deprecated as of release 9.0 of WebLogic Server. Use life cycle listeners instead.

• Startup classes only get preStart events.

  Note:

  Application-scoped startup classes have been deprecated since WebLogic Server 9.0. Use application life cycle listeners instead.

  For the legacy startup and shutdown elements, provide public static void main(String[] args). WebLogic invokes that method with an empty argument array. A startup class is invoked only at preStart; a shutdown class is invoked only at postStop. Declaring listener-named methods on those classes does not register them as listener callbacks.

  ApplicationLifecycleListener has no remove callback. Use preStop/postStop for application shutdown work; these callbacks follow the application lifecycle transitions described above. Application-version deletion notifications use ApplicationVersionLifecycleListener.postDelete, described later in this chapter.

Registering Events in weblogic-application.xml

You must register the application life cycle listener classes in the weblogic-application.xml deployment descriptor in order to use them.

See Enterprise Application Deployment Descriptor Elements. Define the following elements:

• listener—Used to register user defined application life cycle listeners. These are classes that extend the abstract base class weblogic.application.ApplicationLifecycleListener.

• shutdown—Used to register user-defined shutdown classes.

• startup—Used to register user-defined startup classes.

Programming Basic Life Cycle Listener Functionality

You can 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:

• preStart{}

• postStart{}

• preStop{}

• postStop{}

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

Example 15-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
}

Example 15-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.

Example 15-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
}

Example 15-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.

Example 15-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

For an ApplicationLifecycleListener registered with listener, run-as-principal-name selects the user identity under which its callbacks execute. 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 listener, add run-as-principal-name to select the callback execution identity. This does not grant a user permission to deploy or start/stop the application.

   <listener>
     <listener-class>MyListener</listener-class>
     <run-as-principal-name>javajoe</run-as-principal-name>
   </listener>
   

   javajoe is an illustrative name; use an existing user in the application’s security realm.

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.

This identity setting applies to ApplicationLifecycleListener callbacks; application-version callbacks use the anonymous identity described in Understanding Application Version Life Cycle Event Behavior.

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

You can configure application life cycle events with or without specifying URI elements in the weblogic-application.xml deployment descriptor file.

The optional listener-uri, startup-uri and shutdown-uri elements identify the JAR containing the corresponding class, relative to the EAR root. If a URI element is omitted, that class must already be visible to the application classloader. For the examples here, place compiled classes with their package paths under APP-INF/classes, or package them in a JAR under APP-INF/lib. Classes visible only to a child module classloader, such as WEB-INF/classes in a WAR, are not sufficient. No shell CLASSPATH edit is required for these EAR layouts.

The startup and shutdown portions of these descriptor examples are compatibility examples for deprecated application-scoped classes.

The descriptor elements listener-uri, startup-uri and shutdown-uri each name foo.jar, located at the EAR root (myEar/foo.jar). They are descriptor elements, not command-line parameters.

Example 15-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 specifying URI elements.

Example 15-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>

The following minimal complete descriptor registers MyListener alone. Add its listener child to an existing descriptor while retaining other configuration. For this default-package teaching example, put MyListener.class in APP-INF/classes/MyListener.class. If you use a package, preserve its directory layout and use its fully qualified name in listener-class.

<weblogic-application xmlns="http://xmlns.oracle.com/weblogic/weblogic-application">
  <listener>
    <listener-class>MyListener</listener-class>
  </listener>
</weblogic-application>

Understanding Application Life Cycle Event Behavior During Redeployment

Application life cycle events are only triggered if a full redeployment of the application occurs. During a full redeployment 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.

Application life cycle callbacks run during initial deployment and subsequent whole-application lifecycle transitions, including undeployment and full redeployment. A partial module/resource update does not by itself run this whole-application callback sequence. For a normal successful in-place full redeployment, the old application receives preStop(evt), then postStop(evt); the replacement application is prepared and receives preStart(evt), then postStart(evt) during activation. Initialization of application and listener classes occurs as required during preparation; it is not a separate listener callback. During production redeployment with distinct application versions, the new version can start while the old version is still serving existing work, so do not assume that all old-version stop callbacks precede new-version start callbacks. See Developing Applications for Production Redeployment and Programming Application Version Life Cycle Events.Developing Applications for Production RedeploymentProgramming Application Version Life Cycle Events

Programming Application Version Life Cycle Events

Learn 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 Enterprise Application Deployment Descriptor Elements and Examples of Configuring Life Cycle Events with and without the URI Parameter.

Application version life cycle events are invoked:

• For both static and dynamic deployments.

• ApplicationVersionLifecycleListener callbacks execute as the anonymous identity; run-as-principal-name does not change their callback identity.

• Only if the current application is versioned; otherwise, version life cycle events are ignored.

• A registered version listener can observe events for other versions of the same application and for its own version when it is registered at the time of notification. Newly deployed listeners are registered during prepare, after the initial preDeploy notification. For a normal-mode postDeploy notification, recipients are the newly deployed version and other versions that were active when the notification was dispatched. Retired or unregistered listeners are not guaranteed every later event. Use evt.isOwnVersion() to distinguish an event for the listener’s own version from an event for another version; evt.getApplicationId() identifies the version whose operation caused the event.

Types of Application Version Life Cycle Events

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

• public void preDeploy(ApplicationVersionLifecycleEvent evt)

  • The preDeploy event is invoked when an application version deploy or redeploy operation is initiated.

• public void postDeploy(ApplicationVersionLifecycleEvent evt)

  • The postDeploy event is invoked when an application version is deployed or redeployed successfully.

• public void preUndeploy(ApplicationVersionLifecycleEvent evt)

  • The preUndeploy event is invoked when an application version undeploy operation is initiated.

• public void postDelete(ApplicationVersionLifecycleEvent evt)

  • The postDelete event is invoked when an application version is deleted.

    Note:

    A postDelete event is only fired after the entire application version is completely removed. It does not include a partial undeploy, such as undeploying a module or from a subset of targets.

    Compile the following default-package class to APP-INF/classes/MyVersionListener.class so it is visible to the EAR application loader. For a packaged class, use its fully qualified class name. Put the registration fragment inside META-INF/weblogic-application.xml. The EAR must carry the Chapter 7 application version identifier.

    preDeploy and preUndeploy may veto their operation by throwing ApplicationException. If an operation is vetoed or has already failed, later listeners may not be called. postDeploy and postDelete are notifications, not veto points. This logging example does not veto anything.

    import weblogic.application.ApplicationException;
    import weblogic.application.ApplicationVersionLifecycleEvent;
    import weblogic.application.ApplicationVersionLifecycleListener;
    
    public class MyVersionListener extends ApplicationVersionLifecycleListener {
        @Override
        public void preDeploy(ApplicationVersionLifecycleEvent evt)
                throws ApplicationException {
            report("preDeploy", evt);
        }
    
        @Override
        public void postDeploy(ApplicationVersionLifecycleEvent evt) {
            report("postDeploy", evt);
        }
    
        @Override
        public void preUndeploy(ApplicationVersionLifecycleEvent evt)
                throws ApplicationException {
            report("preUndeploy", evt);
        }
    
        @Override
        public void postDelete(ApplicationVersionLifecycleEvent evt) {
            report("postDelete", evt);
        }
    
        private static void report(String phase, ApplicationVersionLifecycleEvent evt) {
            System.out.println(phase + ": " + evt.getApplicationId()
                    + ", ownVersion=" + evt.isOwnVersion());
        }
    }
    

    <listener>
      <listener-class>MyVersionListener</listener-class>
    </listener>
    

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

This example assumes normal-mode deployment of V1 followed by production deployment of V2, retirement of V1, and undeployment of V2. It distinguishes dispatch of an application-version event from receipt by an already registered ApplicationVersionLifecycleListener. It is a conceptual successful-path sequence, not a global clock across target servers.

Table 15-1 Sequence of Deployment Actions and Application Version Life Cycle Events

Normal successful operation	Event version and notification point	Registered observers
Initial deployment of V1	preDeploy(V1) before V1 is prepared	Existing registered versions of this application, if any; V1 has no listener registered yet
V1 preparation and activation	V1 listeners register during prepare; postDeploy(V1) is dispatched when activation reaches the version-notification flow	V1 receives its own postDeploy event
Production deployment of V2 while V1 is active	preDeploy(V2) before V2 is prepared	V1 receives an event for V2; V2 has no listener registered yet
V2 preparation and activation	V2 listeners register during prepare; normal-mode postDeploy(V2) is dispatched as V2 becomes active and V1 loses active status	Both newly registered V2 and previously active V1 receive an event for V2
Retirement of V1	V1 finishes serving its existing work and its listeners are unregistered during unprepare	Do not represent this as an additional postDeploy callback
Undeployment of V2 begins	preUndeploy(V2) is dispatched at the undeployability check	V2 and any other still-registered versions of the same application can observe the event and veto through preUndeploy
V2 is unprepared and removed	V2 listeners are cleared during unprepare; postDelete(V2) is dispatched at the remove notification point	Only observers still registered at that point can receive it; V2 cannot rely on its already-cleared listener receiving its own postDelete

Post notifications are not unconditional failure/completion callbacks. A failure before the corresponding notification point can prevent delivery; reaching a callback does not certify that every later deployment-management step succeeded. preDeploy/preUndeploy can be vetoed. postDelete describes complete application-version removal, not a partial module or target undeploy. Ordinary ApplicationLifecycleListener callbacks such as postStart are separate from these version callbacks.