Skip navigation.
Downloads | Product Documentation | Support

Deploying WebLogic Server Applications

# Advanced Deployment Topics

The following sections describe more advanced deployment topics that might not be used in every WebLogic Server installation:

- Two-Phase Deployment Protocol
- WebLogic Server 6.x Deployment Protocol (Deprecated)
- Enforcing Cluster Constraints with Two-Phase Deployment
- Deployment Staging Modes and Staging Directories
- Deployment Order
- Redeploying Applications and Modules
- Deploying Enterprise Applications With Alternate Deployment Descriptors
- Deployment Topics for Developers

# Two-Phase Deployment Protocol

WebLogic Server uses a two-phase deployment protocol when deploying applications and standalone modules in a domain. The protocol ensures the consistency of deployments to multiple WebLogic Servers in a domain, and also supports advanced deployment features such as application ordering and improved monitoring.

Each deployment in a WebLogic Server domain takes place in two phases: prepare and activate.

### Phase 1: Prepare

The prepare phase ensures that the application and its modules are in a state in which they can be reliably deployed. During the prepare phase, WebLogic Server instances in the domain complete the following tasks:

1. If necessary, the Administration Server copies deployment files to the target servers' staging directories.
2. Each target server validates the deployment files and checks for possible errors to ensure that the files can actually be deployed.

### Phase 2: Activate

In the activate phase, target servers make the application available for clients to use. The activate phase constitutes the actual deployment of the application or module.

The activation phase only takes place after the prepare phase successfully completes.

## Benefits of Two-Phase Deployment

The primary goal of the two-phase deployment model is to ensure that a deployment to multiple targets (for example, deployments to a cluster of WebLogic Server instances) succeeds or fails as a logical unit on the available target servers. In a cluster, you can ensure that a deployment does not activate if even one of the available servers fails to verify the deployment files or detects an error in the deployment files.

Note: The WebLogic Server 6.x deployment protocol, which is deprecated in WebLogic Server 8.1, does not ensure consistent deployment to clusters. See WebLogic Server 6.x Deployment Protocol (Deprecated) for more information.

The two-phase deployment protocol also enables the following new features for deployed applications:

- Consistent deployment states for clusters. If an application targeted to a cluster fails on any of the cluster members in the prepare phase and then in the activate phase, the application is not activated on any of the cluster members. This helps to ensure that the cluster is kept homogeneous. You can also ensure that a deployment fails if any member of the cluster is not available at the time of deployment; see Enforcing Cluster Constraints with Two-Phase Deployment for more information.
- Application ordering. At server startup, you set the order of application activations. See Deployment Order.
- Application-scoped configuration. Certain resources can be configured and scoped for an application. These include connection pools, security realms and XML related resources. See Overview of Application Scoping in Programming WebLogic XML.
- Improved redeployment. You do not need to undeploy before redeploying. See Redeploying or Stopping a Deployment Unit.
- Improved API. A simple API separates configuration from the actual deployment operations. When a deployment is requested, this API creates the necessary configuration (MBeans) for you. Also, the deployment operations are not on the MBeans themselves, so you can change the configuration (such as the target lists) without affecting the deployed application, until a deployment request is initiated. See Deployment Management API, and see also the API documentation for weblogic.management.deploy.
- Deployment status. It is now easier to track the progress of a deployment especially when it has multiple targets. See the WebLogic Administration Console Online Help for Tasks.

# WebLogic Server 6.x Deployment Protocol (Deprecated)

By default, the two-phase deployment protocol is used to deploy new applications by all available deployment tools. The Administration Server also uses the deprecated WebLogic Server 6.x deployment protocol when:

- Pre-configured applications do not specify the two-phase deployment protocol (ApplicationMBean.TwoPhase=true), or
- The application contains multiple modules, but no `application.xml` descriptor.

The 6.x deployment protocol is now deprecated. If you have applications that use the 6.x protocol, follow these instructions to use two-phase deployment:

1. Undeploy the application using weblogic.Deployer. Enter a command in the following form:

>     java weblogic.Deployer -adminurl http://admin:7001 -username weblogic
>        -name app -undeploy

2. If the earlier deployment did not have an `application.xml` file, create one in the application's `META-INF` subdirectory.
3. Deploy the application using weblogic.Deployer. Enter a command in the following form:

>     java weblogic.Deployer -adminurl http://admin:7001 -username weblogic
>        -deploy -name ArchivedEarJar -source C:/MyApps/JarEar.ear
>        -target server1,server2

This command redeploys the application with the new protocol.

# Enforcing Cluster Constraints with Two-Phase Deployment

When you deploy to a WebLogic Server cluster, the default two-phase deployment behavior ensures that the deployment succeeds only on clustered server instances that are reachable by the Administration Server. If servers are unreachable at the time of deployment (for example, because of a network failure between the Administration Server and a Managed Server) those servers will not receive the deployment request until the network connection is restored. This can lead to a situation where some servers in the cluster use a new version of a deployment unit, while other, unreachable servers use an older version.

The `ClusterConstraintsEnabled` option enforces a strict two-phase deployment policy for all servers in a domain. `ClusterConstraintsEnabled` ensures that a deployment to a cluster succeeds only if all members of the cluster are reachable and can deploy the specified files.

You can set the `ClusterConstraintsEnabled` for the domain when you start the Administration Server by supplying a startup argument:

- `-DClusterConstraintsEnabled=true` enforces strict cluster deployment for servers in a domain.
- `-DClusterConstraintsEnabled=false` uses the default two-phase deployment behavior for servers in a domain; deployment is ensured only for clustered servers that are reachable by the Administration Server.

You can also set the `ClusterConstraintsEnabled` option using the Administration Console:

1. Log into the Administration Console for the domain.
2. Select the name of your domain at the top of the left pane.
3. Select the Configuration->General tab in the right pane.
4. Use the Enable Cluster Constraints box to enable or disable cluster constraints for the entire domain.
5. Click Apply and reboot the Administration Server to apply the change.

# Deployment Staging Modes and Staging Directories

The deployment staging mode determines whether or not the Administration Server copies deployment files to target servers during the activate phase of a deployment. WebLogic Server provides three different options for staging archive files: stage mode, nostage mode, and external_stage mode, as described in Staging Modes.

A server's staging directory is the directory in which the Administration Server copies deployment files for stage mode deployments. It is also the directory in which deployment files must reside before deploying an application using external_stage mode.

## Stage Mode

In stage mode, the Administration Server copies the deployment files from their original location on the Administration Server machine to the staging directories of each target server. For example, if you deploy a J2EE Application to three servers in a cluster using stage mode, the Administration Server copies the deployment files to directories on each of the three server machines. Each server then deploys the J2EE Application using its local copy of the archive files.

When copying files to the staging directory, the Administration Server creates a subdirectory with the same name as the deployment name. So if you deployed using the command:

>     java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
>        -password weblogic -name mytestear -stage -targets mycluster
>        -deploy c:\bea\weblogic81\samples\server\medrecd\dist\physicianEar

a new directory, `mytestear`, would be created in the staging directory of each server in `mycluster`. If you do not specify a deployment name, a default deployment name (and staging subdirectory) is used:

- For exploded archive deployments, the deployment name and staging subdirectory are the name of the directory you deployed (`physicianEar` in the example above).
- For archived deployments, the default deployment name is the name of the archive file without the extension. For example, if you deploy `physicianEar.ear`, the deployment name and staging subdirectory are `physicianEar`.

The Administration Console uses stage mode as the default mode when deploying to more than one WebLogic Server instance. `weblogic.Deployer` uses the target server's staging mode as the default, and managed servers use stage mode by default.

Stage mode ensures that each server has a local copy of the deployment files on hand, even if a network outage makes the Administration Server unreachable. However, if you are deploying very large applications to multiple servers or to a cluster, the time required to copy files to target servers can be considerable. You may consider nostage mode to avoid the overhead of copying large files to multiple servers.

## Nostage Mode

In nostage mode, the Administration Server does not copy the archive files from their source location. Instead, each target server must access the archive files from a single source directory for deployment. The staging directory of target servers is ignored for nostage deployments.

For example, if you deploy a J2EE Application to three servers in a cluster, each server must be able to access the same application archive files (from a shared or network-mounted directory) to deploy the application.

Note: The source for the deployment files in nostage mode is the path provided by the user at deployment time (as opposed to stage mode, where the source is the path in each server's staging directory). However, even in nostage mode, WebLogic Server copies out parts of the deployment to temporary directories. This enables users to update entire archived deployments or parts of archived deployments.

In nostage mode, the Web Application container automatically detects changes to JSPs and servlets. Nostage also allows you to later update only parts of an application by updating those parts in one file system location and then redeploying.

The Administration Console uses nostage mode as the default when deploying only to the Administration Server (for example, in a single-server domain). `weblogic.Deployer` uses the target server's staging mode, and Administration Servers use stage mode by default. You can also select nostage mode if you run a cluster of server instances on the same machine, or if you are deploying very large applications to multiple machines that have access to a shared directory. Deploying very large applications in nostage mode saves time during deployment because no files are copied.

## External_stage mode

External_stage mode is similar to stage mode, in that target servers deploy using local copies of the deployment files. However, the Administration Server does not automatically copy the deployment files to targeted servers in external_stage mode; instead, you must copy the files to the staging directory of each target server before deployment. You can perform the copy manually or using automated scripts.

Within each target server's staging directory, deployment files must be stored in a subdirectory that reflects the deployment name. This can either be the name you type in for the deployment, or the default deployment name (the name of the exploded archive directory, or the name of the archive file without its file extension). See Deploying an Enterprise Application Using external_stage Mode for an example.

External_stage mode is the least common deployment staging mode. It is generally used only in environments that are managed by third-party tools that automate the required copying of files. You may also choose to use external_stage mode when you are deploying very large applications to multiple machines and you do not have a shared file system (and cannot use nostage mode). Using external stage in this scenario decreases the deployment time because files are not copied during deployment.

## Server Staging Modes vs. Application Staging Modes

When you deploy an application or standalone module using the Administration Console, the staging mode is set at the application level. The application staging mode always overrides any deployment mode specified for the target server itself.

The server staging mode specifies the default deployment mode for a server if none is specified at deployment time. For example, the server staging mode is used if you deploy using `weblogic.Deployer` and you do not specify a staging mode. The default value for the server staging mode is nostage for the Administration Server and stage mode for Managed Servers.

# Deployment Order

By default, WebLogic Server deploys server-level resources (JDBC followed by JMS) before deploying applications and standalone modules, followed by startup classes. (The order of startup class execution is configurable, as described in Ordering Startup Class Execution and Deployment.)

Note: WebLogic Server security services are always initialized before server resources, applications, and startup classes are deployed. For this reason, you cannot configure custom security providers using startup classes, nor can custom security provider implementations rely on deployed server resources such as JDBC.

The deployment order of deployment units relative to one another is determined by the Load Order attribute. By default, each deployment unit is configured with a Load Order value of 100. Deployments with a lower Load Order value are deployed before those with a higher value during startup. Deployments with the same Load Order value are deployed in alphabetical order using the deployment name. You can change the load order for a deployment unit by setting the Load Order attribute in the Administration Console or programmatically using the ApplicationMBean. See Changing the Order of Deployment for a Deployment Unit for instructions on changing the Load Order using the Administration Console.

## Deployment Order for Modules Within an Enterprise Application

If the application is an EAR, the individual modules are loaded in the order in which they are declared in the application.xml deployment descriptor. See Enterprise Application Deployment Descriptor Elements in Developing WebLogic Server Applications.

## Ordering Startup Class Execution and Deployment

By default WebLogic Server startup classes are run after the server initializes JMS and JDBC services, and after applications and standalone modules have been deployed.

If you want to perform startup tasks after JMS and JDBC services are available, but before applications and modules have been activated, you can select the Run Before Application Deployments option in the Administration Console (or set the `StartupClassMBean`'s `LoadBeforeAppActivation` attribute to "true").

If you want to perform startup tasks before JMS and JDBC services are available, you can select the Run Before Application Activations option in the Administration Console (or set the `StartupClassMBean`'s `LoadBeforeAppDeployments` attribute to "true").

The following figure summarizes the time at which WebLogic Server executes startup classes.

Figure 4-1 Startup Class Execution

BEA provides the `examples.jms.startup` API code example which demonstrates how to establish a JMS message consumer from a WebLogic startup class.See the Administration Console Online Help or the full Javadocs for `StartupClassMBean` for more information.

Note: WebLogic Server 8.1optionally installs API code examples in WL_HOME`\samples\server\examples\src\examples`, where WL_HOME is the top-level directory of your WebLogic Server installation. You can start the examples server, and obtain information about the samples and how to run them.

## Redeploying Applications and Modules

Once you deploy an application, you can redeploy the application itself or selected parts of the application. Redeploying an entire application involves unloading its classes and then deploying the application again with the changed deployment files. (For applications deployed using stage mode, redeployment also involves re-copying deployment files to target servers.)

Note: An application becomes unavailable to clients during redeployment. WebLogic Server doesn't guarantee the operation of the application and deployment task if there is an access from the client at this time. For this reason, redeployment is not recommended for use in a production environment.

Redeploying a part of an application, such as a Web Application or EJB module in an Enterprise Application, involves unloading only the classes in a particular classloader and reloading those classes using the updated class files. See WebLogic Server Application Classloading in Developing WebLogic Server Applications for more information on classloading behavior. Individual files in a Web Application (for instance, a servlet, JSP, or static HTML page) can also be redeployed independently of the rest of the application, without affecting the application classloaders.

See Redeploying or Stopping a Deployment Unit and Redeploying Static Files in a Web Application for example instructions on redeploying applications and modules.

## Limitations of Redeploying Applications and Modules

When redeploying applications and modules, consider the following limitations:

- For an application or module that was originally deployed to a WebLogic Server cluster, subsequent redeployment must occur on all members of the cluster. For example, you cannot deploy an application to a WebLogic Server cluster and later redeploy the application or a part of the application on a subset of servers in the cluster.
- Redeploying entire, staged applications may have performance implications due to increased network traffic when deployment files are copied to the Managed Servers.
- By default, WebLogic Server destroys current user sessions when you redeploy a Web Application. If you want to preserve Web Application user sessions through a redeployment, set `save-sessions-enabled` to "true" in the `container-descriptor` stanza of the `weblogic.xml` deployment descriptor file.
- If you change an application's deployment descriptor files, the container redeploys the entire application.
- To redeploy an Enterprise Application, all of the application's modules must redeploy successfully.
- Removing a module in a redeploy operation is not supported. A redeploy operation updates the applicaiton with new version while using the original deployment framework (MBeans, container, module list). If you need to remove a module, you must undeploy the original application and deploy the new version as a new application.
- When redeploying only one module of an Enterprise Application, if the module affects other classes loaded in the same classloader, the redeployment is rejected with a message saying you must explicitly redeploy all the affected modules. See WebLogic Server Application Classloading in Developing WebLogic Server Applications for more information about application classloading behavior.
- If you redeploy a module of an Enterprise Application that affects other modules (because of classloader dependencies), you must explicitly redeploy the entire application. `weblogic.Deployer` displays the message:

>     Exception:weblogic.management.ApplicationException: [J2EE:160076] You
>     must include all of [module_list] in your files list to modify [module]

- You can not redeploy stale files (files that are older than the currently deployed files based on the timestamp of the compiler). If you need to revert to an older version of your deployment (maintaining the original timestamp), you must undeploy the currently deployed files and then deploy the older version of the files.

## Partial Redeployment for Exploded Web Applications

Partial redeployment refers to changing or adding a part of a deployed Web Application, and using the redeploy action to have the change take place. WebLogic Server supports partial redeployment only for Web Applications that are deployed as exploded WAR files. The following kinds of partial redeployment are supported:

- Static files such as HTML files, graphics files, and JSPs that do not modify the session or update code can be redeployed on-the-fly without interrupting clients of the application.
- Classes in the `WEB-INF/classes` directory can be redeployed independently of the rest of the Web Application. You can also deploy only the updated classes (rather than the entire `WEB-INF/classes` directory) by setting the Reload Period for the Web Application. (See Deploying Web Applications in Developing Web Applications for WebLogic Server for more information about Reload Period.)
- JAR files in `WEB-INF/lib` cannot be redeployed independently of the rest of the Web Application. The container automatically redeploys the entire application, but maintains the state, when redeploying JAR files in `WEB-INF/lib`.

# Deploying Enterprise Applications With Alternate Deployment Descriptors

WebLogic Server enables you to change the run-time deployment configuration of an Enterprise Application without having to modify and repackage the contents of the archive itself. You accomplish this by specifying an alternate deployment descriptor file to use when deploying the Enterprise Application.

An alternate deployment descriptor file can reside anywhere outside a packaged EAR file or exploded EAR directory. (You cannot store alternate Deployment Descriptor files within the archive or directory.) You identify the external EAR descriptor file at deployment time, and WebLogic Server uses the alternate file in place of the deployment's existing (packaged) deployment descriptor. If the files are deployed using stage mode, alternate deployment descriptor files are copied with the deployment files to the top level of the deployment's subdirectory in each target server's staging directory (for example, domain_directory`/`servername`/stage/myapp`). With other staging modes, no copying is performed.

You can specify an alternate deployment descriptor file to use in place of either the standard J2EE deployment descriptor (`application.xml`) or the WebLogic Server deployment descriptor (`weblogic-application.xml`).

## Common Uses for Alternate Deployment Descriptors

Alternate deployment descriptors are generally used with archived Enterprise Applications (EAR files), because they enable you to change deployment parameters without repackaging the application itself. However, you can also specify alternate descriptors to use with exploded EAR directories.

Common uses for alternate deployment descriptors include:

- Changing deployment parameters for an encrypted EAR file that is cumbersome to repackage or explode.
- Changing the subset of modules that you choose to deploy from the EAR. For example, although an EAR may contain multiple, logical applications, you can use an alternate deployment descriptor to deploy only a subset of available applications to a particular WebLogic Server instance.

## Limitations of Alternate Deployment Descriptors

If you deploy an Enterprise Application using an alternate descriptor, you cannot change the alternate descriptor file's location when you redeploy the application. For example, you cannot use the `weblogic.Deployer -redeploy` command and specify a different filename or path to the alternate deployment descriptor file. Note, however, that changes to the original descriptor file are implemented during redeployment.

If you have deployed an application with a standard deployment descriptor, you cannot use an alternate descriptor with the deployed application using the `-redeploy` or `-deploy` commands. Instead, you must first undeploy the application, then deploy it with an alternate descriptor file

## Command-Line Options for Specifying Descriptors

To use an alternate deployment descriptor, you simply use one or both of the following options to `weblogic.Deployer`:

- `-altappdd`—specifies the name of an alternate J2EE deployment descriptor (`application.xml`).
- `-altwlsappdd`—specifies the name of an alternate WebLogic Server deployment descriptor (`weblogic-application.xml`).

See Deploying an Enterprise Application with an Alternate (External) Application Descriptor for an example of using alternate descriptor files.

# Deployment Topics for Developers

This section contains topics for J2EE application developers who are developing and deploying applications to WebLogic Server:

- Auto-Deployment
- Application Lifecycle Events

## Auto-Deployment

Notes: Auto-deployment is a method for quickly deploying an application to a standalone server (Administration Server) for evaluation or testing. It is recommended that this method be used only in a single-server development environment. Use of auto-deployment in a production environment or for deployment on Managed Servers is not recommended.

BEA recommends that you use the WebLogic Server split development directory and `wldeploy` ant task, rather than auto-deployment, when developing an application. See Introducing the Split Development Directory Structure in Developing WebLogic Server Applications.

If auto-deployment is enabled, when an application is copied into the `\applications` directory of the Administration Server, the Administration Server detects the presence of the new application and deploys it automatically (if the Administration Server is running). If WebLogic Server is not running when you copy the application to the `\applications` directory, the application is deployed the next time the WebLogic Server Administration Server is started. Auto-deployment deploys only to the Administration Server.

Notes: Due to the file locking limitations of Windows NT, if an application is exploded, all the modules within the application must also be exploded. In other words, you cannot use auto-deployment with an exploded application or module that contains a JAR file.

Auto-deployment is intended for use with a single server target in a development environment. If you use other tools, such as the Administration Console, to add targets to an auto-deployed, exploded application, redeploying the application does not propagate changes to the new target servers.

### Enabling and Disabling Auto-Deployment

You can run a WebLogic Server domain in two different modes: development and production.

Development mode enables a WebLogic Server instance to automatically deploy and update applications that are in the `domain_name/applications` directory (where `domain_name` is the name of a WebLogic Server domain). In other words, development mode lets you use auto-deploy. Production mode disables the auto-deployment feature.

By default, a WebLogic Server domain runs in development mode. To specify the mode for a domain, see Creating and Configuring Domains Using the Configuration Wizard in Configuring and Managing WebLogic Server.

### Auto-Deploying, Redeploying, and Undeploying Archived Applications

To auto-deploy an archived application, copy its archive file to the `/applications` directory. WebLogic Server automatically sets the application's deployment mode to stage mode.

A deployment unit that was auto-deployed can be dynamically redeployed while the server is running. To dynamically redeploy, copy the new version of the archive file over the existing file in the `/applications` directory.

To undeploy an archived deployment unit that was auto-deployed, delete the application from the `/applications` directory. WebLogic Server stops the application and removes it from the configuration.

### Auto-Deploying, Redeploying, and Undeploying Applications in Exploded Archive Format

To auto-deploy an application in exploded archive format, copy the entire exploded archive directory to the `/applications` directory. WebLogic Server automatically deploys exploded archive applications using the nostage deployment mode. If you deploy an exploded EAR directory that contains archived modules (JAR files), the JAR files are locked during the deployment.

When an application has been auto-deployed in exploded archive format, the Administration Server periodically looks for a file named `REDEPLOY` in the exploded application directory. If the timestamp on this file changes, the Administration Server redeploys the exploded directory.

To redeploy files in an exploded application directory:

1. When you first deploy the exploded application directory, create an empty file named `REDEPLOY`, and place it in the WEB-INF or `META-INF` directory, depending on the application type you are deploying:

An exploded enterprise application has a `META-INF` top-level directory; this contains the application.xml file.

An exploded Web application has a `WEB-INF` top-level directory; this contains the web.xml file.

An exploded EJB application has a `META-INF` top-level directory; this contains the ejb-jar.xml file.

An exploded connector has a `META-INF` top-level directory; this contains the ra.xml file.

Note: The `REDEPLOY` file works only for an entire deployed application or standalone module. If you have deployed an exploded Enterprise Application, the `REDEPLOY` file controls redeployment for the entire application—not for individual modules (for example, a Web Application) within the Enterprise Application. If you deploy a Web Application by itself as an exploded archive directory, the `REDEPLOY` file controls redeployment for the entire Web Application.

2. To redeploy the exploded application, copy the updated files over the existing files in that directory.
3. After copying the new files, modify the `REDEPLOY` file in the exploded directory to alter its timestamp.

When the Administration Server detects the changed timestamp, it redeploys the contents of the exploded directory.

Note: You must touch the `REDEPLOY` file (alter its timestamp) any time you wish to trigger redeployment of an auto-deployed application. Even if you modify an application while a server is shut down, you must touch `REDEPLOY` to ensure that changes are applied when the server next starts up.

To undeploy an application that was auto-deployed in exploded format, use the `weblogic.Deployer` `-undeploy` command, or use the Administration Console to remove the deployment configuration. Then remove the application files from the `/applications` directory.

## 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:

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

>     public void preStart(ApplicationLifecycleEvent evt) {}

- The preStart event is the beginning of the prepare phase, or the start of the application deployment process.)

>     public void postStart(ApplicationLifecycleEvent evt) {}

- The postStart event is the end of the activate phase, or the end of the application deployment process. The application is deployed.

>     public void preStop(ApplicationLifecycleEvent evt) {}

- The preStop event is the beginning of the deactivate phase, or the start of the application removal or undeployment process.

>     public void postStop(ApplicationLifecycleEvent evt) {}

- The postStop event is the end of the remove phase, or the end of the application removal or undeployment process.

- Shutdown classes only get postStop events.
- Startup classes only get preStart events.

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:

- listener—Used to register user defined application lifecycle 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.

### Basic 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:

- preStart{}
- postStart{}
- preStop{}
- postStop{}

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

Listing 4-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 4-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 extends ApplicationLifecycleListener.

Listing 4-2 MyShutdown

>     import weblogic.application.ApplicationLifecycleListener;

>     import weblogic.application.ApplicationLifecycleEvent;

>     public class MyShutdown extends ApplicationLifecycleListener {

>        public static void main(String[] args) {

>          System.out.println

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

>        } // main

>     }

Listing 4-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 extends ApplicationLifecycleListener.

Listing 4-3 MyStartup

>     import weblogic.application.ApplicationLifecycleListener;

>     import weblogic.application.ApplicationLifecycleEvent;

>     public class MyStartup extends ApplicationLifecycleListener {

>        public static void main(String[] args) {

>          System.out.println

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

>        } // main

>     }

### Configuring Lifecycle Events: 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 4-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 4-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>

### 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{}`