Files   Prepare   Deploy   Troubleshooting   Related Topics 

About the Example

Managed Coherence Servers provide a tight integration between Weblogic Server and Coherence, allowing for a simplified and streamlined development and management environment for distributed applications. The functionality allows you to build a new archive type, called a Grid Archive (GAR), which can be deployed and managed on WebLogic Server in a manner similar to other Java EE artifacts. Developers can now streamline their build artifacts to generate GARs, and the operations departments can have a standardized way of deploying Coherence in test and production environments.

This example shows how to perform a rolling restart/redeploy of storage-enabled members that are part of Managed Coherence Servers in WebLogic Server. The example uses a WLST script that can be run against a WebLogic cluster that contains storage-enabled Coherence members.

A rolling restart is a common operation carried out against a Coherence cluster where new or updated classes need to be deployed to members without shutting down the entire cluster. When updating classes on the storage-enabled members, it is important to ensure that you do not lose data while carrying out this operation. This is usually achieved by checking the statusHA value of the services within the cluster and ensuring that they are always machine-safe or node-safe after each redeploy operation.

Consider that you have a storage-enabled WebLogic cluster with three Managed Servers: ms1,ms2 and ms3. The typical steps to perform a rolling restart are to:

1. Ensure the cluster services are machine-safe.
2. Deploy the new application to ms1.
3. Wait until the cluster services are machine-safe.
4. Deploy the new application to ms2.
5. Wait until the cluster services are machine-safe.
6. Deploy the new application to ms3.

The types of changes or updates that can be performed with rolling restart include:

• Adding new EntryProcessors or other classes.
• Adding other POJOs.
• Making changes to existing POJOs, such as additional member fields. (Note: To make changes to POJOs that are stored within a Coherence cache, you must implement the Evolvable interface or the EvolvablePortableObject interface.)
• Making configuration changes. (Note: Some configuration options require a full cluster restart.)

For more information about rolling restart, see the Oracle Coherence documentation.

Rolling upgrade using Weblogic Zero Downtime Patching

Files Used in the Example

Directory Location: D:\Oracle\Middleware\Oracle_Home\wlserver/samples/server/examples/src/examples/coherence/managed-coherence-servers/common/resource/wlst directory.

Prepare the Example

Prerequisites

Before working with this example, install Oracle WebLogic Server, including the examples, if you have not already done so.

Configure Oracle WebLogic Server

Build the Example

To run this example, you must have an existing WebLogic Server environment configured with Coherence. Your environment must have the following:

• A storage-enabled WebLogic Server cluster that has an associated Coherence cluster.
• Three or more Managed Servers as part of that cluster.
• A GAR deployed to the cluster.

Once you have a suitable environment for running the example, complete the steps in Deploy the example. If you do not have an environment available, you can use the environment that is created by building and running the multi server Coherence example described in Managed Coherence Servers - Multi Server. See Prepare the Example for information about how to build and run the multi server example. After the multi server example is running, complete the following steps to create a new Managed Server on the StorageTier cluster:

1. After the multi server example is deployed, launch the WebLogic Server Administration Console using the URL displayed in the command shell from which you deployed the example.
2. Log in as user weblogic and enter the password you specified while deploying the example.
3. In the Domain Structure pane on the left, expand Environment, and select Servers.
4. Select the check box next to storage2 and click Clone.
5. In Server Name, enter the name storage3, and specify a listen port that is not currently used, such as 7033.
6. Click OK to save your changes.
7. In the Summary of Servers page, select the Control tab, select the check box next to the the newly created cache server, and click Start.

After the newly created storage3 is started, Deploy the Example.

Deploy the Example

When the gar_common.py script is copied into the ORACLE_HOME/wlserver/common/wlst directory, the following WLST function is available for use:

     garRedeploy(appName, appFile, clusterName, safetyMode, timeout, shutdownRestart, upload)

The first three arguments are mandatory and the others have defaults. They arguments are described below:

• appName - The name that will be given to the GAR. It must be the same name as the already deployed GAR.
• appFile - The full path name to the GAR to be deployed. This full path must be the same as the already deployed GAR otherwise you will get multiple applications with -1,-2, appended. If you originally deployed the GAR with upload=true, you must set the upload argument above and set this value to true.
• clusterName - The name of the WebLogic cluster on which you wish to run the rolling restart/redeploy.
• safetyMode - The statusHA value to check between redeploys of the application. Must be either SITE-SAFE, RACK-SAFE, MACHINE-SAFE or NODE-SAFE. Default is NODE-SAFE.
• timeout - The time to wait between redeploys for the above safetyMode to be reached. Default is 60 seconds.
• shutdownRestart - Indicates if the Managed Server should be shutdown before deploy and then restarted. Node Manager must be configured to use this. Default is false.
• upload - Indicates the value to send to the deploy command argument upload. As mentioned above, this value must be true if the original GAR was deployed using upload='true'. Default is 'false'.

To deploy the example, complete the following steps:

1. Make sure you have completed the steps described in Prepare the Example.
2. Open a command shell and navigate to the ORACLE_HOME/wlserver/server/bin directory, where ORACLE_HOME represents the central support directory for all WebLogic products installed on your machine. For example, C:\Oracle\Middleware\Oracle_Home.
3. Set your WebLogic Server environment by entering the following command:
   • UNIX or Linux: . ./setWLSEnv.sh or
   • Windows: setWLSEnv.cmd or
4. To test the gar_common.py script, you must populate the caches you are using. If you deployed and ran the Managed Coherence Servers - Multi Server example, use your browser to navigate to the URL for that application, and insert 20 contacts.
5. Using a text editor of your choice, create a new WLST script named test_redeploy.py. (Make sure that this script is saved outside the ORACLE_HOME/wlserver/server/common/wlst directory.)

   In this script, specify the following arguments based upon the Multi Server example:

   • ExampleGAR
   • The full path to the ExampleGAR deployment. (You can obtain the path by clicking on the deployment in the WebLogic Server Administration Console.)
   • StorageTier
   • NODE-SAFE

   Enter the following text in the test_redeploy.py file:
   
   connect()
garRedeploy('ExampleGAR','path-to-ExampleGAR','StorageTier')
   
   

   In the preceding command, path-to-ExampleGAR represents the fully-qualified path to the ExampleGAR deployment. For example:
   
   C:/Oracle/user_projects/applications/wl_server/examples/src/examples/coherence/managed-coherence-servers/common/build/gar/ExampleGAR.gar

6. Run the script using the following command and enter the connection details as requested:
   
   java weblogic.WLST test_redeploy.py
   
7. Note that output similar to the following is displayed:
   

   Initializing WebLogic Scripting Tool (WLST) ...
   
   Welcome to WebLogic Server Administration Scripting Shell
   
   Please enter your username :weblogic
   Please enter your password :
   Please enter your server URL [t3://localhost:7001] :
   Connecting to t3://localhost:7001 with userid weblogic ...
   Successfully connected to Admin Server "AdminServer" that belongs to domain "base_domain".
   
   Checking for cluster StorageTier
   Location changed to domainRuntime tree. This is a read-only tree with DomainMBean as the root. 
   For more help, use help(domainRuntime)
   
   Current status HA of NODE-SAFE is OK
   
   Total number of servers in cluster StorageTier is 3
   Checking cluster statusHA. Timeout is 60 seconds
   
   Cluster service is NODE-SAFE which matches required value. 
    
   Deploying ExampleGAR using /home/oracle/examples/managed-coherence-servers/build/gar/ExampleGAR.gar to server storage1 with option specifiedTargetsOnly=true
   Deploying application from /home/oracle/examples/managed-coherence-servers/build/gar/ExampleGAR.gar to targets storage1 (upload=false) ...
   ......Completed the deployment of Application with status completed
   Current Status of your Deployment:
   Deployment command type: deploy
   Deployment State : completed
   Deployment Message : no message
   Deployment finished. Sleeping 5.
   Checking cluster statusHA. Timeout is 60 seconds
   Already in Domain Runtime Tree
   
   Cluster service is NODE-SAFE which matches required value. 
    
   Checking cluster statusHA. Timeout is 60 seconds
   Already in Domain Runtime Tree
   
   Cluster service is NODE-SAFE which matches required value. 
    
   Deploying ExampleGAR using /home/oracle/examples/managed-coherence-servers/build/gar/ExampleGAR.gar to server storage3 with option specifiedTargetsOnly=true
   Deploying application from /home/oracle/examples/managed-coherence-servers/build/gar/ExampleGAR.gar to targets storage3 (upload=false) ...
   ....Completed the deployment of Application with status completed
   Current Status of your Deployment:
   Deployment command type: deploy
   Deployment State : completed
   Deployment Message : no message
   Deployment finished. Sleeping 5.
   Checking cluster statusHA. Timeout is 60 seconds
   Already in Domain Runtime Tree
   
   Cluster service is NODE-SAFE which matches required value. 
    
   Checking cluster statusHA. Timeout is 60 seconds
   Already in Domain Runtime Tree
   
   Cluster service is NODE-SAFE which matches required value. 
    
   Deploying ExampleGAR using /home/oracle/examples/managed-coherence-servers/build/gar/ExampleGAR.gar to server storage2 with option specifiedTargetsOnly=true
   Deploying application from /home/oracle/examples/managed-coherence-servers/build/gar/ExampleGAR.gar to targets storage2 (upload=false) ...
   .......Completed the deployment of Application with status completed
   Current Status of your Deployment:
   Deployment command type: deploy
   Deployment State : completed
   Deployment Message : no message
   Deployment finished. Sleeping 5.
   Checking cluster statusHA. Timeout is 60 seconds
   Already in Domain Runtime Tree
   
   Cluster service is NODE-SAFE which matches required value. 
    
   Application deployed over all 3 servers
   Exiting
     

8. Run the sample application again to confirm that no data was lost during redeployment.

Applying WebLogic/Coherence Patches in a Rolling Fashion

• Machine1
• Machine2
• Machine3

connect('weblogic','welcome1','t3://localhost:7001')
ensureStatusHA('ExampleGAR','MACHINE-SAFE',120)
print 'StatusHA is MACHINE-SAFE. OK to continue'

Note: This method can only be used for minor patches that are certified to be able to be deployed in this rolling manner.

Troubleshooting

If you end up with multiple GAR applications deployed with -1,-2,-3 appended, ensure that you specified the exact name and full path of the existing deployed GAR file.

Weblogic Zero Downtime Patching

Restrictions of Weblogic Zero Downtime Patching

• Zero Downtime Patching requires atleast 2 machines to be present in a single Weblogic Cluster in order to be eligible for rolling upgrades
• All the managed servers belonging to a machine are shutdown in order to patch Weblogic or upgrade an application. The managed servers in a Coherence cluster must provide enough capacity to handle the shutdown of all the managed server in a single machine

Using Weblogic Zero Downtime Patching

connect('weblogic','welcome1','t3://localhost:7001')
clusters='StorageTier,ClientTier'
# The following command will update Applications(including Coherence GAR applications) specified in the JSON file
rolloutApplications(clusters, '/u01/scratch/app_update.json', options='coherenceServiceHATarget=machine-safe, coherenceServiceHAWaitTimeout=120')
# The following command will patch Weblogic/Coherence, but making sure that there is no data loss
rolloutUpdate(clusters, '/net/wls/wls_patched.jar', '/u01/Oracle_Home_backup', '/u01/jdk1.8.0_50',options='coherenceServiceHATarget=machine-safe, coherenceServiceHAWaitTimeout=120')

Related Topics

(Internet connection required.)

• Oracle WebLogic Server Documentation
• Oracle Coherence Documentation

Copyright © 2012, 2020, Oracle and/or its affiliates. All rights reserved.