9 Managing Deployed Applications

Learn how to perform common maintenance tasks on applications and modules that are currently deployed to a WebLogic Server domain.

This chapter includes the following sections:

• Taking a Production Application Offline

• Undeploying Shared Libraries and Packages

• Adding a New Module to a Deployed Enterprise Application

• Enabling Parallel Deployment for Applications and Modules

• Changing the Order of Deployment at Server Startup

• Changing the Target List for an Existing Deployment

• Removing Files from a Web Application Deployment

• Managing Long-Running Deployment Tasks

• On-demand Deployment of Internal Applications

• Using the ReadyApp Framework

Taking a Production Application Offline

WebLogic Server provides two different ways to take an application offline for testing or maintenance purposes.

• Stopping an Application to Restrict Client Access—Makes an application unavailable for processing client requests, but does not remove the deployment from the WebLogic Server domain. Stopping an application places the deployment in administration mode, which allows you to perform internal testing using a configured administration channel.

• Undeploying an Application or Module—Makes an application unavailable for processing client requests and removes WebLogic Server-generated deployment files from the domain.

Stopping an Application to Restrict Client Access

As described in Distributing Applications to a Production Environment, distributing an application and starting it in administration mode, restricts access to an application to a configured administration channel. You can also stop a running application to client requests and place it in administration mode. In a production environment, you may want to stop an application to confirm a reported problem, or to isolate the application from external client processing in order to perform scheduled maintenance.

Use the -stop command to place a running application into administration mode, as in:

java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
   -password weblogic -name mymodule -stop -adminmode

By default, WebLogic Server immediately stops the application, without regard to pending HTTP sessions or in-process work. If you want to wait for pending HTTP sessions to complete their work before stopping the application to client requests and placing it in administration mode, add the -graceful option:

java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
   -password weblogic -name mymodule -stop -adminmode -graceful

Note:

If you do not explicitly specify an application version with the -appversion option, the -stop command will only stop the active version of the application. If there are other versions of the application that you also want to stop (or that you want to stop instead or the active version), you must specify them with the -appversion option.

To restart an application that was previously stopped, making it available to external clients, use the -start command and specify the deployment name. You do not need to redeploy a stopped application to make it generally available:

java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
   -password weblogic -name mymodule -start

For detailed command information, see Start.

Undeploying an Application or Module

After you deploy a new application or standalone module to servers in a domain, the deployment name remains associated with the deployment files you selected. Even after you stop the deployment on all servers, the files remain available for redeployment using either the WebLogic Server Administration Console or weblogic.Deployer utility.

If you want to remove a deployment name and its associated deployment files from the domain, you must explicitly undeploy the application or standalone module. To undeploy a deployment unit from the domain using weblogic.Deployer, specify the -undeploy command, as in:

java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
   -password weblogic -name mymodule -undeploy

Note:

Using the -undeploy command without the -targets and -submoduletargets flags completely removes the application or standalone module from all WebLogic Server instances and untargets all JMS sub-module resources.

By default, WebLogic Server immediately stops and undeploys the application, interrupting current clients and in-progress work. For a production application, you may want to undeploy "gracefully," allowing current HTTP clients to complete their work before undeploying:

java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
   -password weblogic -name mymodule -undeploy -graceful

Undeploying a deployment unit does not remove the original source files used for deployment. It only removes the deployment's configuration from the domain, as well as any deployment files that WebLogic Server created during deployment (for example, files copied with stage deployment mode and files uploaded to the Administration Server).

If you need to redeploy a deployment unit after undeploying it, you must again identify the deployment files, targets, staging mode, and deployment name using the instructions in Deploying Applications and Modules with weblogic.Deployer.

Undeploying Shared Libraries and Packages

A shared Java EE libraries or optional package cannot be undeployed until all applications that reference the library or package are first undeployed.

If no applications reference an application or package, use the instructions in Undeploying an Application or Module to undeploy it.

Adding a New Module to a Deployed Enterprise Application

WebLogic Server's module-level targeting support enables you to add and deploy a new enterprise application module without having to redeploy other modules that are already deployed.

To deploy a new module in an EAR, you simply use module-level targeting syntax described in Module-Targeting Syntax.

For example, if you were to add a module, newmodule.war, to a deployed enterprise application named myapp.ear (update application.xml file as necessary), you could then deploy newmodule.war using the weblogic.Deployer command:

java weblogic.Deployer -username myname -password password 
   -name myapp.ear -deploy -targets newmodule.war@myserver 
   -source /myapp/myapp.ear

This command deploys the new module without redeploying the other modules in the application. Note that you must specify the correct file extension (.war in the above example) for archived modules in an EAR file.

Enabling Parallel Deployment for Applications and Modules

For use cases involving the deployment of multiple applications or the deployment of a single application with multiple modules, parallel deployment improves startup and post-running deployment time, including server startup.

For multitenant environments, parallel deployment improves the deployment of one or more applications across multiple partitions. See Enabling Parallel Deployment in Mult-Tenant Environments in Using WebLogic Server MT.

When applications and resources are deployed, they are first sorted into sets by overall deployment type. Then, each set begins the deployment process, following the order described in Changing the Order of Deployment at Server Startup.

Within the set of applications, applications with the same deployment order number can deploy in parallel to each other, improving performance.

Note:

By default, parallel deployment for applications is enabled in WebLogic domains that are created with, or upgraded to, WebLogic Server 12.2.1 or later. (Parallel deployment for modules is disabled by default.)

Applications running on WebLogic Server instances prior to version 12.2.1 may have some internal dependencies that must be specified in a deployment order. If that deployment order is not specified, then WebLogic Server cannot detect those dependencies. These dependencies would have been satisfied when using serial deployment on WebLogic Server versions prior to 12.2.1. However, there is some risk of these dependencies being violated when you make the transition from serial deployment to parallel deployment, and this violation would result in a deployment failure. Consequently, in domains that are created with versions of WebLogic Server prior to 12.2.1, parallel deployment is disabled by default. See Parallel Deployment in Upgrading Oracle WebLogic Server.

The following sections describe how to enable parallel deployment for applications and modules within an application archive:

• Enabling Parallel Deployment for Applications

• Enabling Parallel Deployment for Modules

Enabling Parallel Deployment for Applications

To enable parallel deployment for applications, configure the ParallelDeployApplications attribute of the DomainMBean. With this attribute enabled, applications with the same deployment order will deploy in parallel of each other, improving performance. The ParallelDeployApplications attribute is enabled by default.

The overall deployment order of resources and applications remains unchanged, so deployment types that precede applications in the normal deployment order (for example, JDBC system resources and Java EE libraries) are guaranteed to be fully deployed before applications are deployed.

Note:

Only applications with no cross-dependencies should deploy in parallel. If an application depends on other applications, then this application needs to have a higher dependency-order than the applications it depends on. Otherwise, parallel activation may cause dependency failures when the dependent application attempts to deploy prior to the deployment of applications on which it depends.

Enabling Parallel Deployment for Modules

You can configure modules within a single application archive to deploy in parallel to each other. To enable parallel deployment of modules for all applications in the domain, configure the ParallelDeployApplicationModules attribute of the DomainMBean. The ParallelDeployApplicationModules attribute is disabled by default.

To enable parallel deployment of modules on a per-application basis, configure the ParallelDeployModules attribute of the AppDeploymentMBean. Setting this attribute overrides the domain value for an individual application.

Note:

You can only enable parallel deployment of modules for applications that contain modules with no cross-dependencies. If modules are dependent on other modules, parallel deployment may cause dependency failures when the dependent module attempts to deploy prior to the deployment of the modules on which it depends.

Note:

If the Java EE <initialize-in-order> element is specified and set to true for an application, then the modules within the application are deployed according to the order they are defined in application.xml, regardless of whether parallel deployment of modules is enabled or disabled.

Changing the Order of Deployment at Server Startup

By default, WebLogic Server deploys applications and resources in a certain order.

1. Caches

2. Internal applications

3. JDBC system resources

4. Deployment handlers

5. JMS system resources

6. Resource-dependent deployment handlers

7. Startup classes

8. WLDF system resources

9. Java EE libraries and optional packages

10. Applications and standalone modules

11. Coherence cluster system resources

12. Custom system resources (this module type is mapped to the custom-resource deployment descriptor (DD) element)

    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.

Changing the Deployment Order for Applications and Standalone Modules

You can change the deployment order for a deployed application or standalone module by setting the AppDeploymentMBean DeploymentOrder attribute in the WebLogic Server Administration Console (or programmatically using the AppDeploymentMBean). The DeploymentOrder attribute controls the load order of deployments relative to one another—modules with lower DeploymentOrder values deploy before those with higher values. By default, each deployment unit is configured with a Deployment Order value of 100. Deployments with the same Deployment Order value are deployed in alphabetical order using the deployment name. In all cases, applications and standalone modules are deployed after the WebLogic Server instance has initialized dependent subsystems.

Note:

You cannot change the load order of applications and standalone modules using the weblogic.Deployer utility.

To view or change the deployment order of deployments using the WebLogic Server Administration Console, follow the steps in Change the server deployment order in Oracle WebLogic Server Administration Console Online Help.

Changing the Deployment Order for Modules in an Enterprise Application

The modules contained in an enterprise application are deployed in the order in which they are declared in the application.xml deployment descriptor. See Enterprise Application Deployment Descriptor Elements in Developing Applications for Oracle WebLogic Server.

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 WebLogic Server 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 WebLogic Server Administration Console (or set the StartupClassMBean's LoadBeforeAppDeployments attribute to "true").

To select Run Before Application Deployments or Run Before Application Activations in the WebLogic Server Administration Console, see Configure startup classes in Oracle WebLogic Server Administration Console Online Help.

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

Figure 9-1 Startup Class Execution

Description of "Figure 9-1 Startup Class Execution"

See the description of the Javadocs for StartupClassMBean for more information.

Changing the Target List for an Existing Deployment

After you deploy an application or standalone module in a WebLogic Server domain, you can change the target server list to add new WebLogic Server instances or to remove existing server instances.

If you remove a target server, only the target list itself is updated—the deployment unit remains deployed to the removed server until you explicitly undeploy it. Similarly, if you add a new target server, you must explicitly deploy the deployment unit on the new server before it is active on that server.

To add a new server to the target list using weblogic.Deployer, simply specify the new list of target servers with the -deploy command. For example:

java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
   -password weblogic -name mydeploymentname -deploy 
   -targets server1, newserver

Removing Files from a Web Application Deployment

If you deploy a Web application using an exploded archive directory, you can update the static contents of the Web application in one of two ways.

You can refresh the files (see Updating Static Files in a Deployed Application), or delete the files from the deployment. To delete files, you must use the weblogic.Deployer utility with the delete_files option. For example:

java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
   -password weblogic -name mywebapp -delete_files mywebapp/copyright.html

Always specify the pathname to updated files starting with the top level of the exploded archive directory. In the above example, the Web application resides in an exploded archive directory named mywebapp.

Note:

Because the -delete_files option deletes all specified files or, if you specify a directory but do not specify files within the directory, all files in the specified directory, Oracle recommends that you use caution when using the delete_files option and that you do not use the delete_files option in production environments.

Managing Long-Running Deployment Tasks

The WebLogic Server deployment system automatically assigns a unique ID to deployment tasks so that you can track and manage their progress.

weblogic.Deployer enables you to assign your own task identification numbers for use with deployment commands, as well as monitor and cancel long-running deployment tasks.

For example, the following command assigns a task ID of redeployPatch2 to a new deployment operation:

java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
   -password weblogic -name mymodule -targets myserver -id redeployPatch2
   -nowait -deploy c:\localfiles\myapp.ear

You can later check the status of the task:

java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
   -password weblogic -id redeployPatch2 -list

You can check the status of all running tasks:

java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
   -password weblogic -listtask

If a task takes too long to complete you can cancel it:

java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
   -password weblogic -id redeployPatch2 -cancel

On-Demand Deployment of Internal Applications

There are many internal applications that are deployed during startup. These internal applications consume memory and require CPU time during deployment. This contributes to the WebLogic Server startup time and base memory footprint. Because many of these internal applications are not needed by every user, WebLogic Server has been modified to wait and deploy these applications on the first access (on-demand) instead of always deploying them during server startup. This reduces startup time and memory footprint.

The following sections describe on-demand deployment in detail.

Internal Application Types

There are two different types of internal applications. The first type displays a user interface, and includes the WebLogic Server Administration Console, UDDI explorer, and WebLogic Server test client. The second type does not display a user interface, and includes UDDI and internal servlets for deployment and management file distribution.

For applications with a user interface, WebLogic Server displays a status page indicating that on-demand deployment is in progress. This page refreshes every two seconds. When the internal application completes deployment, you are redirected to the internal application. This status page is displayed on the first access of each application. Subsequent invocations do not deploy the application and go directly to the user interface for the internal application.

Configuring On-Demand Deployment

For a development domain, the default is for WebLogic Server to deploy internal applications on demand. For a production-mode domain, the default is for WebLogic Server to deploy internal applications as part of server startup. You can control the default behavior by configuring the InternalAppsDeployOnDemandEnabled attribute in the Domain MBean. You can change the configuration setting using the WebLogic Server Administration Console or by using the WebLogic Scripting Tool (WLST).

Configuring On-Demand Deployment Using the Administration Console

To change the InternalAppsDeployOnDemandEnabled attribute using the WebLogic Server Administration Console, perform the following steps:

1. Start an edit session with the Lock and Edit button.
2. Select the domain to bring up the Configuration > General page.
3. Change the setting of the Enable on-demand deployment of internal applications check box.
4. Click Save and then click Activate Changes to activate the changes that will take effect at the next restart of WebLogic Server.

Configuring On-Demand Deployment Using WLST

To change the InternalAppsDeployOnDemandEnabled attribute using the WLST, perform the following steps:

connect()
edit()
startEdit()
cmo.setInternalAppsDeployOnDemandEnabled(false)
activate()

Using the ReadyApp Framework

The ReadyApp framework helps to advertise the READY or the NOT READY state of an application that is registered with the framework. This framework prevents traffic from being routed to a WebLogic Server instance that is not fully functional.

When applications that are deployed to WebLogic Server experience asynchronous behavior during initialization, WebLogic Server may enter the RUNNING state before the applications finish initializing. In this situation, the load balancer or other instances of WebLogic Server may prematurely route traffic to a server that is not fully functional. If you rely on the server to determine whether applications are ready to service requests, errors may result.

The ReadyApp framework introduces the READY and NOT READY states, which allow internal and external applications to influence the state of the server and the partitions in which the application runs.

For example, if an application that is registered with the ReadyApp framework is not ready to service requests from an instance of WebLogic Server in the RUNNING state, the server state is set to NOT READY until the application calls the ready() method.

Configuring the ReadyApp Framework with EAR-based or WAR-based Applications

To use the ReadyApp framework, register the EAR-based or WAR-based application with the framework by adding the following code to the application's WebLogic deployment descriptor (META-INF\weblogic-application.xml):

<wls:ready-registration>true</wls:ready-registration>

When the application starts, the state is set to NOT READY. Any application that is registered with the ReadyApp framework is automatically unregistered when the application is undeployed from WebLogic Server.

Note:

The prefix wls: may not be required, depending on the contents of the weblogic-application.xml file. If the rest of the tags do not have the prefix, you can ignore the prefix.

When the application has finished initializing and is ready to service requests, set the application to the READY state by adding the following line to the code where the initialization completes:

weblogic.application.ready.ReadyLifecycleManager.getInstance().ready();

A call to the ready() method indicates to the ReadyApp framework that the application is ready to process requests. However, the application READY state does not mean that the server or partition is ready. All other registered applications must signal that they are ready before the server or partition is ready.

If the application has to stop processing requests, (for example, if the application needs to be reinitialized), use the following method to indicate that the application is not ready:

weblogic.application.ready.ReadyLifecycleManager.getInstance().notReady();

Note:

After an application calls the notReady() method, the server or partition where the application is deployed remains in the NOT READY state until the application calls the ready() method again.

The ready() and notReady() methods can cause the following runtime exceptions:

• IllegalArgumentException: This exception occurs when the applicationId reported by the Component Invocation Context is null.

• IllegalStateException: This exception occurs when the application has not been properly registered. Check the deployment descriptor for proper setup.

Monitoring the ReadyApp Framework

To check the running status of the ReadyApp framework, use one of the following methods:

• Visit the ReadyApp Servlet URL.

• Enable the DebugReadyApp attribute in the WebLogic Server Administration Console.

Monitoring the ReadyApp Framework Using the ReadyApp Servlet URL

Point your browser to http://{host:port}/weblogic/ready. The browser returns a page with either a status 200 (READY) or 503 (NOT READY). Be sure to replace host and port with the host name and port number of the desired server. When WebLogic Server is not running, an Error 404 page appears.

The http://{host:port}/weblogic/ready URL opens a blank page with only the HTTP status set. Use a browser tool to see the actual status. For example, the Google Chrome browser has a Developer Tools setting to show the status of the page and the latency.

Monitoring the ReadyApp Framework by Enabling DebugReadyApp Attribute in the WebLogic Server Administration Console

You can also monitor the ReadyApp framework by enabling the DebugReadyApp attribute in the WebLogic Server Administration Console. If STDOUT logging is enabled, this method of monitoring writes information to the log file or the Console.

To monitor the ReadyApp framework using WebLogic Server Administration Console:

1. Log in to the WebLogic Server Administration Console (http://{host:port}/console/).
2. Select Environment > Servers > MyServer > Debug.
3. In the Debug settings for this server, expand weblogic > application, select the DebugReadyApp check box, and then click Enable.
   This change does not require WebLogic Server to restart. For more information on enabling the debug attributes, see Servers: Debug.
4. Set the severity levels for the log to debug:
   1. Select Environment > Servers > MyServer > Logging > Advanced.
   2. Set the severity level of Minimum severity to log to Debug.
   3. Under Log file, set Severity Level to Debug.
   4. Click Save.
      For more information on logging, see Servers: Logging: General.
5. Visit http://{host:port}/weblogic/ready. Output similar to Example 9-1 appears:

Example 9-1 The ReadyApp Framework Status

**********************
Ready App Map - Operation: Get Ready Status
Partition Id GLOBAL
Item 0 key: TestEar value: 1
Partition Id ratestp2
Item 0 key: ReadyApp2Test$ratestp2 value: 1
Partition Id ratestp1
Item 0 key: ReadyApp2Test$ratestp1 value: 1
**********************

In Example 9-1, three applications are deployed to the server instance: one in the GLOBAL partition and two in the ratest partitions. A value of 1 indicates that these three applications are not ready. If the ready() method is called on these applications, the value is set to 0, which indicates the READY state.