Skip navigation.

Deploying WebLogic Server Applications

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents View as PDF   Get Adobe Reader

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 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 specified by the Staging Directory Name attribute.
  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:


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:

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:
  2. java weblogic.Deployer -adminurl http://admin:7001 -username weblogic
       -name app -undeploy
  3. If the earlier deployment did not have an application.xml file, create one in the application's META-INF subdirectory.
  4. Deploy the application using weblogic.Deployer. Enter a command in the following form:
  5. 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:

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.

Warning: After you have deployed your application, do not change or remove the original source files for the application. The WebLogic Server deployment framework uses the files to manage deployed applications. Changing or removing the original source files may result in unexpected application behavior.

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:

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

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:

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:


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:

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:

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:


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

  3. To redeploy the exploded application, copy the updated files over the existing files in that directory.
  4. 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:

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:

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:

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) {
     ("MyListener(preStart) -- we should always see you..");
   } // preStart
  public void postStart(ApplicationLifecycleEvent evt) {
     ("MyListener(postStart) -- we should always see you..");
   } // postStart
  public void preStop(ApplicationLifecycleEvent evt) {
     ("MyListener(preStop) -- we should always see you..");
   } // preStop
  public void postStop(ApplicationLifecycleEvent evt) {
     ("MyListener(postStop) -- we should always see you..");
   } // postStop
   public static void main(String[] args) {
     ("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) {
     ("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) {
     ("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


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


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


Skip navigation bar  Back to Top Previous Next