Application Deployment

WebLogic uses a two-phase deployment strategy. When you initiate a deployment task for an application, it first prepares the application on all target servers and then activates the application in a separate phase. This two-phase approach reduces the likelihood of inconsistent deployment states across a cluster because the application is deployed on target servers only after acknowledging the success of the prepare phase.

During the prepare phase of deployment, copies of the application and its components are distributed to all target servers. In addition, certain validation checks are performed to ensure that the application and its components can be deployed reliably. A deployment enters the activation phase only if the prepare phase completes successfully. The actual deployment occurs during the activation phase that is, when the application and its components are deployed to each target server. The application is available to clients only after the completion of the activation phase.

By adopting this two-phase deployment strategy, WebLogic can perform intermediate checks that ensure subsequent activation will succeed on all of the target servers. This greatly helps to reduce the risk of an inconsistent and potentially unstable deployment across the domain. In a clustered environment, if deployment fails on any of the target servers during either the prepare or activation phases, the deployment task is rolled back as a whole from all targets. For example, if an application targeted to a cluster fails on any of the cluster members during either the prepare or activation phases, the application will not be deployed on any of the servers in the cluster. This helps to ensure the cluster deployment is kept homogenous.

Note that if the prepare phase does succeed on all servers in the cluster, the activation will occur regardless of any subsequent errors that may occur during activation. The prepare phase is designed to minimize the likelihood of activation errors, but if they do occur, the deployment will not be rolled back and you will have a nonhomogenous deployment. In this case, you may have to undeploy the application, fix the error causing the activation problem, and redeploy.

12.3.1 Application Staging

The prepare phase is particularly important in a WebLogic domain composed of multiple managed servers. During the prepare phase, the application that is being deployed has to be distributed somehow to all of the managed servers participating in the deployment. Staging refers to this process of copying application files to locations from where they can be deployed to target servers. Generally, you can make the application files available to the Administration Server, which will organize the distribution of these files. However, if you have a shared directory setup, you may not want this behavior. Alternatively, you may want to take on the responsibility of ensuring that the components are distributed yourself.

WebLogic provides various staging modes that control the way in which an application can be distributed:

stage

Application files are copied automatically to a staging directory on the target server. Once the server boots up, it will run the application from this staging folder.

external_stage

An external user or process (and not WebLogic) ensures that the application is available on the server's staging folder before initiating deployment.

nostage

Application files are not copied to another location during deployment, so all targeted servers deploy from the same file or directory.

The staging mode can be specified for each server in the domain, and later overridden by individual applications on the server. However, once an application is deployed, its staging mode cannot be changed.

12.3.1.1 Staging

When you enable application staging for a managed server, WebLogic is responsible for distributing the components to the targeted servers before the actual deployment is initiated. During the prepare phase, the application files are copied automatically to a staging directory on the targeted server and subsequently activated from there. This is the default deployment behavior for a managed server in the domain. It is perhaps the most robust because each managed server has its own local copy of the application module. In doing so, it can avoid problems caused by network outages during deployment. For example, if the shared directory used in nostage mode becomes unavailable, it can cripple the servers in the domain that rely on the shared directory.

The name of the application's staging directory on a managed server is a combination of the server's name and the name of the application. For instance, if you deploy a web application, MyWebApp, packaged within oo.war to ServerA, the WAR file is copied to ServerAMyWebAppoo.war located on ServerA. The same behavior is observed on each targeted server on which the default staging mode is configured. Staging ensures that each server has its own copy of the application. The naming scheme for the application's staging folder works nicely to avoid any conflicts if you are running multiple servers on a single machine (or a shared filesystem).

The following example shows how to deploy a web application to a WebLogic cluster:

java weblogic.Deployer -targets mycluster -name oo -source oo.war -deploy -stage

Note that the command is run from the machine hosting the Administration Server. The -stage option instructs the Deployer tool to stage the web application, and the -deploy action instructs the members of the cluster to deploy the web application. This will ensure that the WAR is copied to each server in the cluster, and then activated on each cluster member. Once the web application is deployed successfully on all members of the cluster, a request such as http://mycluster:7001/oo/index.jsp then can be directed to any server in the cluster. You subsequently can stop the application on all servers in the cluster by invoking the Deployer tool as follows:

java weblogic.Deployer -name oo -stop

If you want to stop the application on just a subset of the servers, use the -targets option to specify those servers:

java weblogic.Deployer -targets someserver -name oo -stop

The application will no longer be available on any member of the cluster. This means that any HTTP requests for a resource hosted by the web application will return an HTTP 503 error response (Service Unavailable). In general, you should specify the -targets option only if you must stop the application on a subset of the servers to which it is deployed. Unless otherwise specified, the -targets option always defaults to the existing targets that have been configured for the application. Stopping an application doesn't change its staging mode, however a copy of the WAR still is available on each server and can be restarted quickly using the following command:

java weblogic.Deployer -name oo -start

In this case, no staging needs to occur the web application (WAR) already had been copied to all servers in the cluster. We are merely reactivating the web application using the previously staged copy of the WAR on each cluster member.

Stopping an application simply makes the application unavailable to clients, and avoids the need for any further preparation (and staging) if the application needs to be restarted. If you really need to undeploy the application, use the -undeploy option. This stops the application and removes the staged files. If you want to redeploy the application, you must distribute and prepare the application again. The following command shows how to undeploy a web application from all the servers to which it is deployed:

java weblogic.Deployer -name oo -undeploy

Now any HTTP requests for a resource hosted by the web application will return an HTTP 404 error response (Not found). Be careful when you use the -undeploy option because the Deployer tool physically removes all staged files from all targeted servers.

If you simply want to redeploy an application, perhaps because you have changed the code in some way, run the Deployer tool as follows:

java weblogic.Deployer -name oo -redeploy

Because WebLogic Server adopts a two-phase deployment strategy, you can instruct the Deployer tool to only distribute an application component, and not start it. The following command shows how to distribute a web application module:

java weblogic.Deployer -targets myserver -name myapp -source oo.war -stage -distribute

At this point, the web application will be distributed and is ready to be activated. Once the application module has been distributed, you can activate (or start) the application module in the usual way:

java weblogic.Deployer -name myapp -start

12.3.1.2 External staging

External staging is quite similar to WebLogic's support for staging, except that WebLogic isn't responsible for distributing copies of the application to each targeted server. Instead, the user (or an external process) is in charge of distributing the application files before initiating actual deployment. The application files need to be placed in the same staging directory as WebLogic would use were you using the default staging mode. For instance, if you need to deploy the application MyWebApp located in the file oo.war to a cluster containing the servers, ServerA and ServerB, you must copy oo.war to the ServerAMyWebApp folder located on ServerA, and to the ServerBMyWebApp folder located on ServerB. In addition, the application files being deployed also must be available to the Administration Server. You typically will use this staging mode if you have external tools that can handle the distribution of your application files.

Let's assume that you've copied the web application (oo.war) to staging directories on all managed servers in the cluster mycluster. Then you can activate the web application on mycluster using the Deployer tool on the Administration Server:

java weblogic.Deployer -targets mycluster -name mywebapp -source oo.war -deploy -external_stage

All other deployment operations such as stopping, starting, and unpreparing work exactly as described before. The -undeploy option behaves differently when it operates on an externally staged application. In this case, the Deployer tool undeploys only the application from all servers in the cluster, but doesn't remove the application files from the staging directory.

12.3.1.3 No staging

By disabling application staging, you ensure that WebLogic does not distribute the application files during the prepare phase of deployment. Instead, the staging directory is ignored completely and the applications are deployed to the target server directly from their source directories. This is the default staging mode for the Administration Server.

No staging is ideal for incremental development on a single-server domain. Because the application is deployed from the target files directly, this mode allows the web container to detect changes to servlets and JSPs and reload them as necessary. It also can be used if you have multiple application servers running on the same machine, where the servers share the same disk.

The following command shows how to deploy and activate a web application to a cluster using the no staging mode:

java weblogic.Deployer -targets mycluster -name goo -deploy -nostage goo.war

Just like the external staging mode, the application files being deployed also must be available to the Administration Server.

12.3.2 Configuring the Staging Mode

To set the default staging mode for a server, start up the Administration Console, select the server from the left pane, and navigate to the Configuration/Deployment tab. Here you will find options to modify the server's staging mode and the default staging directory for the server. If your domain consists of servers that use a shared disk, you even can specify a shared staging directory for each server. In the case of the Administration Server, you also can specify the default directory that should be used to store the uploaded files for deployment.

In WebLogic 8.1, you can set the staging mode for an application when you choose between the following two options during deployment: "Copy this application onto every target for me," which enables the staging mode, and "I will make the application accessible from the following location," which disables staging altogether. If you want to deploy an application with external staging, the Administration Console cannot help you. You must use the Deployer tool to deploy an application in the externally staged mode. WebLogic 8.1 also lets you set the staging mode for individual applications, in which case they override the default staging mode for the server. For example, you can set the staging mode for a web application by choosing the application from the left pane of the Administration Console and then navigating to the Configuration/General tab.

12.3.3 Auto-Deployment

WebLogic also supports an auto-deployment feature that typically should be used only during the development stages of a single-server deployment. In the development mode, applications are deployed to the Administration Server automatically as soon as they are copied into the domainapplications folder. By default, WebLogic Server runs in the development mode, which means that the auto-deployment feature is enabled by default. By placing the server in production mode, you can disable this auto-deployment feature. In this situation, you explicitly need to deploy your applications using either the Deployer tool or the Administration Console. Developers on WebLogic 8.1 instead can use the split-directory development methodology, detailed later in this chapter.

In order to enable the auto-deployment feature for a server, you need to ensure that the following command-line option is set when you start up WebLogic Server:

java -Dweblogic.ProductionModeEnabled=false ... weblogic.Server

The startup script startWebLogic uses a shell variable PRODUCTION_MODE for this purpose. When the server runs in development mode, you can deploy any J2EE component automatically by simply placing the JAR (or directory, if the component exists in exploded format) under the applications directory of the domain. This support extends to enterprise applications, web applications, EJB modules, and resource adapters. If the J2EE application is copied to the directory when the server is not running, it is deployed the next time the server starts. Similarly, you can undeploy the application by simply deleting the JAR (or directory, if it exists in exploded format) from the domain's applications directory.

You may notice occasional file-locking errors on Windows platforms when using the auto-deployment feature. These errors occur when WebLogic attempts to read the file (say, a JAR) while you still are copying the file to the applications directory. For instance, when you redeploy an EJB JAR within an exploded EAR, you may find the deployment aborts because of ZIP errors due to file-locking. One way to get around this issue is to avoid JARs in the first place and simply deploy all J2EE modules within the application in exploded format. Alternatively, you can minimize the occurrence of file-locking errors by lengthening the time period that WebLogic uses to poll the filesystem for application changes.

WebLogic also provides a cute mechanism for redeploying applications already deployed on a server running in development mode. Suppose you have deployed an enterprise application in exploded format, and it includes a large number of application files. It would be impractical for WebLogic to poll every application file continuously for any changes. Instead, WebLogic polls a single file REDEPLOY located in the WEB-INF or META-INF directory of your exploded component. For instance, if you have an exploded EAR, you simply need to copy a blank file called REDEPLOY into its META-INF directory. Now if you want to redeploy the application, just "touch" the file to alter its timestamp. WebLogic will detect the modified timestamp and redeploy the application. This redeploy feature works only for applications and components placed directly under the domain's applications folder.

12.3.4 Alternative Descriptors

You also can use the Deployer tool to deploy an enterprise application with an alternative set of deployment descriptors. Instead of the default application.xml and weblogic-application.xml descriptor files, you can instruct the Deployer tool to use an alternative set without actually modifying the packaged EAR that must be deployed. Use the -altappdd option to set an alternative J2EE deployment descriptor (application.xml) for the enterprise application, and use the -altwlsappdd option to set an alternative WebLogic-specific deployment descriptor (weblogic-application.xml). The following example shows how to deploy an EAR file myApp.ear using alternative descriptor files:

java weblogic.Deployer -targets mycluster -name myApp -deploy -nostage -altappdd f:myapp.xml -altwlsappdd f:mywlsapp.xml myApp.ear

If the application is deployed in the staged mode, the alternative descriptor files are copied to the top level of the application's subdirectory under the staging folder of each target server.

This feature is quite handy during development time because it lets you easily experiment with different runtime configurations of your application. For example, you could deploy the EAR with a different set of descriptors in order to experiment with different context properties, or even a different set of EJB and WAR modules. This mechanism works for any enterprise application, regardless of whether it has been packaged in an archived format (EAR) or in exploded directory format.

There are a few caveats when specifying alternative deployment descriptors. If you've already deployed an application with an alternative set of descriptors, you cannot change the location of the descriptor files when you later redeploy the application. Thus, you cannot specify different locations for the alternative descriptors when you subsequently invoke the Deployer tool with the -redeploy option. Likewise, if you've deployed an enterprise application using the default deployment descriptors, then you cannot redeploy the same application with an alternative set. In both cases, you need to first undeploy the enterprise application and then deploy it again with the alternative descriptor files.

12.3.5 Deployment Order

It is important to understand the order in which WebLogic deploys J2EE applications and components. In general, WebLogic first deploys the managed resources such as JDBC connection pools, data sources, JMS connection factories and destinations, and Mail Sessions. After this, WebLogic deploys the application components in the following sequence: J2EE connectors, EJB modules, and finally web applications. For enterprise applications, WebLogic loads the individual components in the order in which they are declared in the application.xml descriptor file. So, for instance, the EJBs packaged within an EAR will be loaded in the order in which they're declared in the application.xml descriptor file.

WebLogic also lets you adjust the order in which separate applications are deployed. For each application, you can specify a numeric value for the Load Order attribute. WebLogic then will deploy applications in increasing order of their Load Order values. By default, all applications deployed to WebLogic are assigned a Load Order of 100. So, in order to change the sequence in which your applications are deployed, you need to change their Load Order attributes. Once the application is deployed, you can use the Administration Console to locate the J2EE component from the left pane and then change its Load Order setting from the right pane. These changes will come into effect the next time the server is started. You even can make this change programmatically by modifying the value of the LoadOrder attribute of an ApplicationMBean instance. Chapter 20 explains how to use WebLogic's MBeans to effect this change.