The following sections describe how to use WebLogic Server redeployment to update applications and parts of applications in a production environment:
In a production environment, deployed applications frequently require 24x7 availability in order to provide uninterrupted services to customers and internal clients. WebLogic Server provides flexible redeployment strategies to help you update or repair production applications based on their required level of availability.
Production redeployment strategy involves deploying a new version of an updated application alongside an older version of the same application. WebLogic Server automatically manages client connections so that only new client requests are directed to the new version. Clients already connected to the application during the redeployment continue to use the older version of the application until they complete their work, at which point WebLogic Server automatically retires the older application.
Production redeployment enables you to update and redeploy an application in a production environment without stopping the application or otherwise interrupting the application's availability to clients. Production redeployment saves you the trouble of scheduling application downtime, setting up redundant servers to host new application versions, manually managing client access to multiple application versions, and manually retiring older versions of an application (see Redeploying Applications and Modules In-Place for information about these manual steps).
Production redeployment can be used in combination with the -distribute command to prepare a new version of an application for deployment. Then, you can deploy the application in Administration mode, which allows you to perform final sanity testing of a new application version directly in the production environment before making it available to clients. See Distributing a New Version of a Production Application.
Production redeployment is supported only for certain J2EE application types, see Restrictions on Production Redeployment Updates. For production redeployment procedures and related information, see Using Production Redeployment to Update Applications.
In-place redeployment immediately replaces a running application's deployment files with updated deployment files. In contrast to production redeployment, in-place redeployment of an application or stand-alone J2EE module does not guarantee uninterrupted service to the application's clients. This is because WebLogic Server immediately removes the running classloader for the application and replaces it with a new classloader that loads the updated application class files.
Note: | In-place redeployment is the redeployment strategy used in previous versions of WebLogic Server. |
WebLogic Server uses the in-place redeployment strategy for J2EE applications that do not specify a version identifier, and for J2EE applications and stand-alone modules that are not supported in Production Redeployment. You should ensure that in-place redeployment of applications and stand-alone J2EE modules takes place only during scheduled downtime for an application, or when it is not critical to preserve existing client connections to an application. See Using In-Place Redeployment for Applications and Stand-alone Modules for more information.
WebLogic Server uses the in-place redeployment strategy when performing partial redeployment of a deployed application or module. Partial redeployment can replace either static files in an application, or entire J2EE modules within an Enterprise Application deployment, as described in Partial Redeployment of Static Files.
WebLogic Server enables you to redeploy selected files in a running application, rather than the entire application at once. This feature is generally used to update static files in a running Web application, such as graphics, static HTML pages, and JSPs. Partial redeployment is available only for applications that are deployed using an exploded archive directory.
Partial redeployment of static files does not affect existing clients of the application. WebLogic Server simply replaces the static files for the deployed application, and the updated files are served to clients when requested. See Updating Static Files in a Deployed Application.
Partial redeployment also enables you to redeploy a single module or subset of modules in a deployed Enterprise Application. Again, partial deployment is supported only for applications that are deployed using an exploded archive directory.
Note that redeployment for modules in an Enterprise Application uses the in-place redeployment strategy, which does not guarantee uninterrupted client access to the module. For this reason, you should ensure that partial redeployment of J2EE modules in an EAR takes place only during scheduled application downtime, or when it is not critical to preserve client access to the application. See Using Partial Redeployment for J2EE Module Updates.
The following table summarizes each WebLogic Server redeployment strategy and describes the scenarios in which you would use each strategy.
WebLogic Server enables you to redeploy a new, updated version of a production application without affecting existing clients of the application, and without interrupting the availability of the application to new client requests.
WebLogic Server performs production redeployment by deploying a new version of an application alongside an older, running version of the application. While redeployment is taking place, one version of the application "active," while the other version is "retiring." The active application version receives all new client connection requests for the application, while the retiring application version processes only those client connections that existed when redeployment took place. WebLogic Server undeploys the retiring application version after all existing clients of the application have finished their work, or when a configured timeout is reached.
When you redeploy a new version of an application, WebLogic Server treats the newly-deployed application version as the active version, and begins retiring the older version. During the retirement period, WebLogic Server automatically tracks the application's HTTP sessions and in-progress transactions. WebLogic Server tracks each HTTP session until the session completes or has timed out. In-progress transactions are tracked until the transaction completes, rolls-back, or reaches the transaction timeout period.
You can roll back the production redeployment process by making the older application version active. This may be necessary if, for example, you determine that there is a problem with the newer version of the application, and you want WebLogic Server to begin moving clients back to the older version. To make the older application version active, redeploy it.
In a WebLogic Server cluster, each clustered server instance retires its local deployment of the retiring application version when the current workload is completed. This means that an application version may be retired on some clustered server instances before it is retired on other servers in the cluster. Note, however, that in a cluster failover scenario, client failover requests are always handled by the same application version on the secondary server, if the application version is still available. If the same application version is not available on the secondary server, the failover does not succeed.
In order to use the production redeployment feature, an application must meet certain requirements during the development and deployment phases.
The production redeployment strategy is supported for:
Production redeployment is not supported for:
Production redeployment only supports HTTP clients and RMI clients (see Graceful Shut Down of RMI Client Request Processing). Your development and design team must ensure that applications using production redeployment are not accessed by an unsupported client. WebLogic Server does not detect when unsupported clients access the application, and does not preserve unsupported client connections during production redeployment.
During development, applications must be designed to meet specific requirements in order to ensure that multiple versions of the application can safely coexist in a WebLogic Server domain during production redeployment. See Developing Versioned Applications for Production Redeployment in Developing WebLogic Server Applications for information about the programming conventions required for applications to use production redeployment.
If an Enterprise Application includes a JCA resource adapter module, the module:
Before resource adapters in a newer version of the EAR are deployed, resource adapters in the older application version receive a callback. WebLogic Server then deploys the newer application version and retires the entire older version of the EAR.
For a complete list of production redeployment requirements for resource adapters, see Production Redeployment in Programming WebLogic Resource Adapters.
WARNING: | Because the production redeployment strategy requires an application to observe certain programming conventions, use production redeployment only with applications that are approved by your development and design staff. Using production redeployment with an application that does not follow BEA's programming conventions can lead to corruption of global resources or other undesirable application behavior. |
A deployed application must specify a version number before you can perform subsequent production redeployment operations on the application. In other words, you cannot deploy a non-versioned application, and later perform production redeployment with a new version of the application.
WebLogic Server can host a maximum of two different versions of an application at one time.
When you redeploy a new version of an application, you cannot change:
To change any of the above features, you must first undeploy the active version of the application.
WebLogic Server attempts to use the production redeployment strategy when the currently-deployed application and the redeployed application specify different versions.
To assign a version identifier to an application, BEA recommends that you store a unique version string directly in the MANIFEST.MF
file of the EAR or WAR being deployed. Your development process should automatically increment the version identifier with each new application release before packaging the application for deployment.
Maintaining version information in this manner ensures that the production redeployment strategy is used with each redeployment of the application in a production domain. See Developing Versioned Applications for Production Redeployment in Developing WebLogic Server Applications.
If you are testing the production redeployment feature, or you want to use production redeployment with an application that does not include a version string in the manifest file, specify a unique version string by using the -appversion
option when deploying or redeploying an application:
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -deploy -name myTest
Deployment
-source /myDeployments/myApplication/91Beta
-targets myCluster -stage -appversion .91Beta
The version string specified with -appversion
is applied only when the deployment source files do not specify a version string in MANIFEST.MF
. See
Application Version Conventions in Developing WebLogic Server Applications for information about valid characters and character formats for application version strings.
WARNING: | Do not use -appversion to deploy or redeploy in a production environment unless you are certain the application follows BEA's programming conventions for production redeployment. See Requirements and Restrictions for Production Redeployment. Using production redeployment with an application that does not follow the programming conventions can cause corruption of global resources or other undesirable application behavior. |
The WebLogic Server Administration Console displays both version string information and state information for all deployed applications and modules. To view this information, select the Deployments node in the left-hand pane of the Administration Console.
You can also display version information for deployed applications from the command line using the weblogic.Deployer
-listapps command:
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -listapps
To redeploy a new version of an application using the production redeployment strategy:
MANIFEST.MF
file of the new application source you want to deploy:jar xvf myApp.ear MANIFEST.MF
cat MANIFEST.MF
For example, if the currently-deployed application's files are stored in:
/myDeployments/myApplication/91Beta
You would store the updated application files in a new subdirectory, such as:
/myDeployments/myApplication/1.0GA
WARNING: | For nostage or external_stage mode deployments, do not overwrite or delete the deployment files for the older version of the application. The original deployment files are required if you later choose to roll back the retirement process and revert to the original application version. |
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -redeploy -name myTestDeployment
-source /myDeployments/myApplication/1.0GA
If the new deployment files do not contain a version identifier in the manifest, see Assigning a Version Identifier During Deployment and Redeployment.
By default WebLogic Server makes the newly-redeployed version of the application active for processing new client requests. Existing clients continue to use the older application until their work is complete and the older application can be safely undeployed.
If you want to specify a fixed time period after which the older version of the application is retired (regardless of whether clients finish their work), use the -retiretimeout
option with the -redeploy command:
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -redeploy -name myTestDeployment
-source /myDeployments/myApplication/1.0GA
-retiretimeout 300
-retiretimeout
specifies the number of seconds after which the older version of the application is retired. You can also retire the older application immediately by using the -undeploy command and specifying the older application version, as in:
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -undeploy -name myTestDeployment
-appversion .91Beta
If WebLogic Server has not yet retired an application version, you can immediately undeploy the application version without waiting for retirement to complete. This may be necessary if, for example, an application remains in the retiring state with only one or two long-running client sessions that you do not want to preserve. To force the undeployment of a retiring version of an application, use the -undeploy command and specify the application version:
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -undeploy -name myTestDeployment
-appversion .91Beta
Notes: | You cannot specify the -graceful option to the -undeploy command when undeploying an application version that is being retired, or waiting for a retirement timeout to occur. |
Note: | If you do not explicitly specify an application version with the -appversion option, WebLogic Server undeploys the active version and all retired versions of the application. If an older version of the application is not yet retired and you run the -undeploy command without specifying the -appversion option, WebLogic Server logs a warning message in the server log and does not undeploy the unretired version. To later undeploy such versions of the application, you must run the -undeploy command again and specify the application version with the -appversion option. |
Reversing the production redeployment process switches the state of the active and retiring applications and redirects new client connection requests accordingly. Reverting the production redeployment process might be necessary if you detect a problem with a newly-deployed version of an application, and you want to stop clients from accessing it.
To roll back the production redeployment process, issue a second -redeploy command and specify the deployment source files for the older version, as in:
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -redeploy -name myTestDeployment
-source /myDeployments/myApplication/91Beta
-retiretimeout 300
If the deployment files do not contain a version identifier in the manifest, see Assigning a Version Identifier During Deployment and Redeployment.
You can use the -rmigraceperiod
attribute to specify a grace period (in seconds) for processing of RMI client requests when retiring (-retirement
) or gracefully (-graceful
) shutting down an application. The work manager of a server instance accepts and schedules RMI calls until the grace period expires without a receiving new RMI client request. If a new RMI client request occurs within the grace period, the grace period is reset and RMI client processing continues until:
If an RMI client tries to access a retired application or a shutdown application, the client receives NoSuchObjectException
when trying to invoke the object. If a new version of the object is available, an application needs to catch the NoSuchObjectException
exception and look up the new version of the object using the JNDI environment property
weblogic.jndi.WLContext.RELAX_VERSION_LOOKUP
to return bindings from the active version of the application.
For example, the following command places the application in Administration mode after allowing any pending HTTP sessions or in-process work to complete:
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -name mymodule-stop -adminmode -graceful
-rmigraceperiod 30
If graceful retirement is initiated at T0 seconds, and a RMI request (msg1) arrives at T1 seconds where T1 < (T0 + 30), the application waits for T1 + 30 seconds for additional RMI client requests.
When you distribute a new version of an application, WebLogic Server prepares the new application version for deployment. You can then deploy the application in Administration mode, which makes it available only via a configured Administration channel. External clients cannot access an application that has been distributed and deployed in Administration mode.
You can use the -adminmode
option to start the application in administration mode. For information, see Starting a Distributed Application in Administration Mode.
The older version of the application remains active to process both new and existing client requests. WebLogic Server does not automatically retire the older version of the application when you distribute and deploy a newer version in Administration mode.
After you complete testing of the new application via an Administration channel, you either undeploy the new application version or start it. Starting the application causes WebLogic Server to route new client connections to the updated application, and begin retiring the older application version.
The basic steps for distributing a new version of an application in Administration mode are nearly the same as those documented in Redeploying a New Version of an Application. You simply use the weblogic.Deployer
-distribute command, rather than the -redeploy command, as in:
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -distribute -name myTestDeployment
-source /myDeployments/myApplication/1.0GA
-appversion 1.0GA
Once the application is distributed, start it in Administration mode:
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -start -adminmode -name myTestDeployment
-source /myDeployments/myApplication/1.0GA
-appversion 1.0GA
Starting the application in Administration mode makes it available only via a configured Administration channel. See Configuring Network Resources in Designing and Configuring WebLogic Server Environments.
Optionally, specify the retirement policy or timeout period for distributed applications.
After performing final testing using the configured Administration channel, you can open the distributed version of the application that is running in Administration mode to new client connections by using the weblogic.Deployer
-start command without the -adminmode
option:
-appversion
option to weblogic.Deployer
to start the application that was distributed and deployed in Administration mode:java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -start -name myTestDeployment
-appversion .91Beta
By default WebLogic Server routes new client requests to the application version that was previously distributed and running in Administration mode. Existing clients continue using the older application until their work is complete and the older application can be safely undeployed. If you want to specify a fixed time period after which the older version of the application is retired (regardless of whether clients finish their work), use the -retiretimeout
option:
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -start -name myTestDeployment
-appversion .91Beta -retiretimeout 300
-retiretimeout
specifies the number of seconds after which the older version of the application is retired.
When using production redeployment, keep in mind the following best practices:
/stage
subdirectory of the domain directory) and are removed when an the associated application version is undeployed. /myTestDeployment/.91Beta
and /myTestDeployment/1.0GA
in each server's staging directory before deployment and redeployment.
In-place redeployment immediately undeploys and replaces a running application's deployment files with updated deployment files. When used to redeploy entire applications or J2EE modules, in-place redeployment makes the application or module unavailable during the deployment process, and can cause existing clients to lose in-process work. This disruption of client services occurs because application class files and libraries are immediately undeployed from their class loaders and then replaced with updated versions.
Because in-place redeployment of applications and modules adversely affects clients of the application, it should not be used with production applications unless:
WARNING: | WebLogic Server always performs in-place redeployment for applications that do not include a version identifier. |
WebLogic Server also uses in-place redeployment for many partial redeployment operations (redeployment commands that affect only a portion of an application). In some cases, using partial redeployment is acceptable with production applications, because the redeployed files do not adversely affect active client connections. Table 8-2 describes each type of partial deployment and its effect on deployed applications.
Safe for versioned applications that are compatible with production redeployment. See Using Production Redeployment to Update Applications.
|
To redeploy an entire application or stand-alone module using the in-place redeployment strategy:
The exact method for taking an application offline depends on the architecture of your WebLogic Server domain. In most cases, a redundant server or cluster is created to host a separate copy of the application, and load balancing hardware or software manages access to both servers or clusters. To take the application offline, the load balancing policies are changed to roll all client connections from one set of servers or clusters to the redundant set.
For example, if the currently deployed application's files are stored in:
/myDeployments/myApplication/91Beta
You would store the updated application files in a new directory, such as:
/myDeployments/myApplication/1.0GA
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -redeploy -name myApp
If an application was previously deployed to multiple, non-clustered server instances, you can specify a target list to redeploy the application on only a subset of the target servers, as in:
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -redeploy -name myApp
-targets myserver1,myserver2
Note: | For applications deployed to a cluster, redeployment always occurs on all target server instances in the cluster. If the application was previously deployed to all servers in the cluster, you cannot subsequently redeploy the application on a subset of servers in the cluster. |
When using in-place redeployment to redeploy entire applications or stand-alone modules, keep in mind the following:
save-sessions-enabled
to "true" in the container-descriptor
stanza of the weblogic.xml
deployment descriptor file. Note, however, that the application still remains unavailable while in-place redeployment takes place.
The weblogic.Deployer
utility uses a different command form if you want to redeploy individual modules of a deployed Enterprise Application. To redeploy a subset of the modules of an Enterprise Application, specify modulename@servername in the target server list to identify the modules you want to redeploy. For example:
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -redeploy -name myApp
-targets mymodule1@myserver1,mymodule2@myserver2
Note: | The use of -redeploy module-uri is deprecated. Instead, use production redeployment or redeploy the module using the -targets module@target syntax. |
If the application was previously deployed to a cluster, you must redeploy the module to the entire cluster, rather than a subset of servers. If you specify a subset of servers in the cluster, weblogic.Deployer
responds with the error:
An attempt to add server target target_name to module module_name has been rejected . This is because its parent cluster, cluster_name, is aso targeted by the module.
The following restrictions apply to using partial redeployment for modules in an Enterprise Application:
weblogic.Deployer
requires that you explicitly redeploy all of the affected modules. If you attempt to use partial redeployment with only a subset of the affected J2EE modules, weblogic.Deployer
displays the error:Exception:weblogic.management.ApplicationException: [J2EE:160076] You
must include all of [module_list] in your files list to modify [module
]
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
.Keep in mind these best practices when using partial redeployment for Enterprise Application modules:
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
weblogic.xml Schema in Developing Web Applications, Servlets, and JSPs for WebLogic Server for more information.)save-sessions-enabled
to "true" in the container-descriptor
stanza of the weblogic.xml
deployment descriptor file. Note, however, that the application still remains unavailable while in-place redeployment takes place.
In a production environment, you may occasionally need to refresh the static content of a Web application module—HTML files, image files, JSPs, and so forth—without redeploying the entire application. If you deployed a Web application or an Enterprise Application as an exploded archive directory, you can use the weblogic.Deployer
utility to update one or more changed static files in-place. See
Avoiding Unnecessary JSP Compilation on dev2dev.com.
To redeploy a single file associated within a deployment unit, specify the file name at the end of the redeploy command. For example:
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -name myApp -redeploy myApp/copyright.html
Always specify the pathname to updated files relative to the root directory of the exploded archive directory. In the above example, the Web application is deployed as part of an Enterprise Application, so the module directory is specified (myApp/copyright.html
).
If the Web application module had been deployed as a stand-alone module, rather than as part of an Enterprise Application, the file would have been specified alone (copyright.html
).
You can also redeploy an entire directory of files by specifying a directory name instead of a single file. For example:
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -name myApp -redeploy myApp/myjsps
In the above example, all files and subdirectories located in the myjsps
subdirectory of the Enterprise Application are redeployed in-place.
After you have deployed an application or stand-alone module, you can change the WebLogic Server deployment configuration using either the Administration Console or weblogic.Deployer
.
The Administration Console enables you to interactively modify individual deployment configuration properties, while weblogic.Deployer
only allows you to specify an updated deployment plan file to use for reconfiguring the application.
The Administration Console enables you to reconfigure all deployment configuration properties for an application, including properties that were not included in the application's deployment plan. If an application was deployed with a deployment plan, the Console displays any deployment plan configuration properties in the plan in the Deployment Plan tab for the application.
The remaining configuration tabs for an application enable you to change other WebLogic Server configuration properties. The exact properties that are available for configuration depend on the type of application or J2EE module that is deployed. These tabs are available regardless of whether or not the application was deployed with an deployment plan.
Note that certain configuration changes are safe to apply to running production applications, while other changes require you to shut down and restart the application. See Understanding Redeployment Behavior for Deployment Configuration Changes.
When you use the Administration Console to make changes to properties that were defined in a deployment plan, the Console generates a new deployment plan that containing variable definitions for the new properties you modified, as well as any existing variables defined in the plan. You can select where to save the new deployment plan.
The weblogic.Deployer
utility enables you to update an application's deployment configuration by providing a new deployment plan to use with the application.
Note: | The updated deployment plan must be valid for the application's current target servers, or the configuration update will fail. |
To reconfigure an application with a different (and valid) deployment plan, use the -update command and specify the new deployment plan file, as in:
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -update -name myTestDeployment
-plan /myDeployments/myNewPlan.xml
Note: | Certain configuration changes are safe to apply to running production applications, while other changes require you to shut down and restart the application. See Understanding Redeployment Behavior for Deployment Configuration Changes. |
Note: | The redeployment behavior in this section applies both to configuration changes made using the Administration Console and via the weblogic.Deployer -update command. |
When you change the deployment configuration for a deployed application, WebLogic Server applies the changes using a redeployment operation. The type of redeployment strategy used depends on the nature of configuration changes applied. If you modified the value of a resource binding property, the configuration update uses either the production redeployment strategy (if the application supports production redeployment), or the in-place redeployment strategy for the entire application. Performing in-place redeployment for an entire application or module is not recommended for production environments, because the application is first undeployed, causing connected clients to lose in-progress work. See Overview of Redeployment Strategies for more information.