Advanced Deployment Topics

This chapter describes more advanced deployment topics that might not be used in every WebLogic Server installation. It includes the following sections:

The deployment staging mode determines how a module's archive files are made available to target servers that must deploy the module. WebLogic Server provides three different options for staging archive files: stage mode, nostage mode, and external_stage mode. You can set the staging mode either at the WebLogic Server level or at the application level, which overrides the server setting.

Stage mode indicates that the Administration Server copies the deployment files from their original location to the staging directories of each targeted server. For example, if you deploy a J2EE Application to three servers in a cluster, 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.

Stage mode is the default (and preferred) mode when deploying to more than one WebLogic Server instance.

Nostage mode indicates that the Administration Server does not copy the archive files from their source location. Instead, each targeted server must access the archive files from a single source directory for deployment. 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.

In nostage mode, the web application container automatically detects changes to JSPs and servlets.

Nostage mode is the default mode when deploying only to the Administration Server (for example, in a single-server domain). You can also select nostage mode if you run a cluster of server instances on the same machine.

External_stage mode is similar to stage mode, in that the deployment files must reside locally to each targeted server. However, the Administration Server does not automatically copy the deployment files to targeted servers in external_stage mode; instead, you must ensure that the files are copied to the staging directory of each targeted server.

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.

The following table describes how staging attribute and path settings affect an application's deployment:

Table 3-1 Application Deployment

Staging Mode	Path	Admin Server	Managed Server
stage	Relative	Application files are copied to a directory named after the application in the staging directory, and activated from there (e.g., server/stage/myapp/app.ear).	Files are distributed to the managed server staging area and distributed from there.
nostage	Relative	Path is relative to the staging directory. That is, if the staging directory is /stage, and the relative path is xdir/myapp, then files are assumed to reside at /stage/xdir/myapp. No files are copied.	Same as for Admin Server.
external_stage	Absolute, Relative	Files are assumed to reside in the server's staging area and are loaded from there. No files are copied. The deployment should be copied in a directory with the same name as the application name under each target server's staging directory (e.g., /server/stage/myapp/web.war)	Same as for Admin Server.
stage	Absolute	Same as if path were relative. Application files are copied to a directory named after the application in the staging directory, and activated from there (e.g., server/stage/myapp/app.ear).	Same as if the path were relative. Application files are distributed to the staging directory and activated from there.
nostage	Absolute	Files are not copied and are activated from the absolute path.	Same as for Admin Server.

Note: The Administration Console automatically recommends the optimal staging mode based on your target server selections. In most cases, you should accept the default staging mode that the Administration Console provides.

If you are deploying to a standalone server (Administration Server), or if all target servers reside on the same machine, select nostage mode. In either case, all of the target servers can access the same set of files for deployment.

If you are deploying to multiple, remote servers in a production environment, use stage mode. 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. If you do not want the Administration Server to copy the files for you, use external_stage mode instead and ensure that the files are copied before deployment.

When you deploy an application or 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 an application or module using weblogic.Deployer and you do not specify a staging mode.

By default, WebLogic Server deploys server-level resources (first JDBC and then JMS) before deploying application modules. Modules are then deployed in order starting with connector modules, followed by EJB modules, and finally Web Applications.

The actual deployment order of modules is determined by their Load Order attribute. By default, new applications and modules are configured with a Load Order value of 100. Modules with a lower Load Order value are deployed before those with a higher value during startup. Modules with the same Load Order value are deployed in alphabetical order using the deployment name.

You can change the deployment order for modules by setting ApplicationMBean LoadOrder attribute in the Administration Console.

If the application is an EAR, the individual components are loaded in the order in which they are declared in the application.xml deployment descriptor. See Editing Enterprise Application Deployment Descriptors. As with other modules, you can specify the load order of modules within an EAR by changing the LoadOrder attribute.

When you modify a component (for instance, a servlet, JSP, or HTML page) of a Web Application on the Administration Server, you must take additional steps to refresh the modified component so that it is also deployed on any targeted Managed Servers. One way to refresh a component is to redeploy the entire Web Application. Redeploying the Web Application means that the entire Web Application (not just the modified component) is re-sent over the network to all of the Managed Servers targeted by that Web Application.

WebLogic Server enables you to change the run-time deployment configuration of an 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 a module.

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

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

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

If you deploy an Enterprise Application using an alternate descriptor, you cannot change the alternate descriptor file when you redeploy the application. For example, you cannot use the weblogic.Deployer -redeploy and specify a different filename for the alternate deployment descriptor. WebLogic Server always uses the same alternate descriptor file during a redeployment.

In addition, you cannot specify an alternate deployment descriptor for either the weblogic.xml or weblogic-ejb-jar.xml files in this release.

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

The new two-phase deployment protocol helps to maintain domain consistency. In previous versions of WebLogic Server, when you deployed an application, the administration server sent a copy of the application file(s) to all the targeted servers, which then loaded the application. If deployment to any of those servers failed or partially failed, the entire deployment's state across its target servers became inconsistent.

In the current release of WebLogic Server, deployment first prepares the application across all target servers and then activates the application in a separate phase. If a deployment of an application fails in either the preparation or activation phase, then the cluster deployment is failed.

The new deployment protocol supports the following new features for deployed applications:

The two-phase model makes inconsistent deployment states in clusters less likely by confirming the success of the prepare phase before deploying the application on any targeted servers. A deployment that fails during the prepare phase will not enter the activation phase.

The prepare phase of deployment, the first phase, distributes or copies files and prepares the application and its components for activation, validating them and performing error checks on them. The purpose of the prepare phase is to ensure that the application and its components are in a state in which they can be reliably deployed.

The second phase, the activate phase, is the actual deployment, or activation, of the application and its component with the relevant server subsystem. After the activate phase, the application is made available to clients.

When you deploy a module 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. Servers that are unreachable (for example, due to a network failure between the Administration Server and a Managed Server), receive the deployment only after the Administration Server can reach the server. This can potentially lead to a situation where some servers in the cluster use a new version of a deployed module, while other, unreachable servers use an older version of the module.

The ClusterConstraintsEnabled option enforces a strict two-phase deployment policy for all members of the cluster. ClusterConstraintsEnabled ensures that a deployment to a cluster succeeds only if all members of the cluster are reachable and can deploy the specified module. You set the ClusterConstraintsEnabled option at the domain level by supplying the startup argument to the domain's Administration Server:

By default, the two-phase deployment protocol is used for deploying new applications by all available deployment tools. The current administration server still supports the WebLogic Server 6.x deployment protocol, and this protocol is used when:

To configure an application that uses 6.x protocol to start using the two-phase protocol, remove the application from the domain—removing its configuration—and then re-activate the application, as follows:

The following topics apply only to deploying applications to development servers. See the associated links for more information.

Auto-deployment is a method for quickly deploying an application on the administration server. It is recommended that this method be used only in a single-server development environment for testing an application. Use of auto-deployment in a production environment or for deployment of components on managed servers is not recommended.

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 is started. Auto-deployment deploys only to the administration server.

WebLogic Server provides a special deployment mode to help you quickly update and redeploy application modules during the development phase. This deployment mode allows you to deploy a module directly from a development directory structure, without having to package the module using either the jar utility or by creating an exploded application directory. See Programming WebLogic Server Applications for more information on this deployment mode.