Working with Managed Coherence Servers

Managed Coherence Servers provides tight integration between WebLogic Server and Coherence. This integration allows for a simplified and streamlined development and management environments of distributed applications. The functionality allows end users to build a new archive type (Grid Archive orGAR), which can be deployed and managed via standard WebLogic Server best practices. Developers can now streamline their build processes to generate GARs. Operations departments can now standardize deployment of Coherence and Coherence applications in the test and production environments. This feature requires both WLS 12.1.2 and Coherence 12.1.2 (or above)

Traditionally, Coherence has been deployed as a jar incorporated into a java application (e.g., WAR or standalone Java application) along with a tier of standalone cache server JVMs (often using the DefaultCacheServer class). The embedded java usages (such as in a WAR) are referred to as clients and the standalone cache servers are referred to as servers. The lifecycles of the “clients” and cache servers are managed separately, often manually, with the cache servers managed by custom shell scripts. Application development and deployment in this model is a complicated process involving many parts that require custom management processes

A Coherence application is defined by the artifacts required for a Coherence node to serve a particular Coherence cache or invocation request. A GAR contains:

• A deployment descriptor, with required name coherence-application.xml. 
• A collection of Java classes required to serve the request; typically these are implementations of EntryProcessors, Filters, Aggregators, and backing-map business logic. Classes are optional.
• An optional collection of support JARs. Optional unless required by some other class.

The deployment descriptor contains the following:

• A pointer to a cache configuration xml document. This document describes the Coherence services and caches.
• An optional pointer to a POF configuration document. This document describes the types serializable using the Portable Object Format.
• An optional class name of a class implementing the LifeCycleListener interface.
• An optional class name of a class implementing the ConfigurableCacheFactory interface.

<?xml version="1.0" encoding="ISO-8859-1"?>
<coherence-application>
  <cache-configuration-ref>META-INF/cache-config.xml </cache-configuration-ref>  
  <pof-configuration-ref>META-INF/pof-config.xml</pof-configuration-ref>>
  <application-lifecycle-listener>
      <class-name>. . . </class-name>
  </application-lifecycle-listener>
  <configurable-cache-factory-config>
     <class-name>...</class-name>
  <configurable-cache-factory-config>. . . </configurable-cache-factory-config>
</coherence-application>

Example coherenece-application.xml Deployment Descriptor


These artifacts are grouped in a jar called a Coherence Grid Archive (GAR) that defines all the artifacts for a particular Coherence Application. This mirrors to a large degree the structure of other Java EE artifacts such as Web Archives (WAR).

The format of a GAR is typically:

• META-INF
• MANIFEST.MF
• coherence-application.xml – Coherence deployment descriptor
• coherence-cache-config.xml – Coherence cache configuration
• pof-config.xml – Portable Object Format (POF) configuration document. This document describe which objects and how they are serialized using POF.
• [optional class files in appropriate packages]

Coherence Application Development Models

Coherence Applications are typically deployed in tiers. The simplest model is a two-tiered deployment, and includes:

• A data tier, used to host Coherence Server instances responsible for storing the data related to the application.
• An application tier that hosts the application consuming data stored in the data tier.

Each tier is managed using standard WebLogic Server principles combined with the new functionality integrated for the 12.1.2 release. The new Coherence Cluster definition represents the operational (runtime) configuration of a Coherence cluster. Coherence clusters are then associated with a WebLogic Server cluster representing the data tier, and a separate WLS cluster representing the application tier. In the data tier, the grid archive is deployed to each managed server, which is configured as a storage enabled coherence node. The application tier would deploy the identical GAR, packaged in an EAR and the EAR is then deployed to each storage disabled managed server representing the application tier. Note thats it’s considered best practice to have dedicated storage tiers, separate from the application tier to ensure optimum cluster performance.

There are two areas related to configuration with Managed Coherence Servers:

• Standard Cache Configuration
• WLS Domain configuration

Standard Cache configuration is managed by the coherence-cache-config.xml file that resides within the Grid ARchive. These configuration concepts relate to cache configuration and topologies (near caches) which are explained via the standard coherence documentation, found here.

Configuring the WLS domain as described in the preceding sections is new functionality made available in 12.1.2 and above. It is possible to perform this configuration via both WLST and the Administration console. The high-level steps involved would be to:

1. Create a domain
2. Create a Coherence Cluster
3. Create a Data tier WLS cluster and associate it with the Coherence Cluster
4. Associate the Data tier WLS cluster with the Coherence Cluster
5. Deploy your GAR to the data tier
6. Create an Application WLS Cluster and associate it with the Coherence Cluster
7. Deploy your EAR to the application tier.

The combined Coherence/WebLogic Server installed will run with Java 1.6, however Managed Coherence Server instances require version 1.7 or later to function property.

1. Determine installed Java version

   Using a command similar to java -version determine the java version on the target machine.
   WebLogic/Coherence 12.1.3 requires Java 1.7 or later. 
   
   

2. Install or upgrade Java

   If the installed version of Java is not 1.7 or later.
   1. Download Java SE Development Kit 7 for your operating system from here and follow the instructions to install.
   2. If the java command is not in the class path note the installation directory which will be referred to this as JAVA_HOME.
   3. Install the JDK per the instructions for your operating system.
   4. Set the value of the JAVA_HOME variable using a command similar to:
      $ set JAVA_HOME=c:\jdk\jdk1.7.0_45 (Windows) or
      $ export JAVA_HOME=/softeware/jdk/jdk1.7.0_45 (Linux/Solaris)

1. Download and save the WebLogic Server/Coherence combined installer which can be found here.  Be sure to select WebLogic Server and Coherence install as shown below:
   
   
   

2. Unzip the downloaded installed using a command similar to:
   

   $ unzip fmw...wls_Disk1_1of1.zip.

   For example:

   

   
   

3. Execute the installer using a command similar to:
   $ java -jar {path to unzipped installer}/fmw_12.1.3.0.0_wls.jar
   For example.

   
   
   If java was not pre-installed or a newer version was used you may need to use a command similar to:
   ${JAVA_HOME}/bin/java -jar fmw_12.1.3.0.0_wls.jar

4. Enter a location for a new or existing Oracle Inventory and click OK.
   

   

5. In the Welcome dialog click Next
   

   

6. In the Installation Location Dialog choose an appropriate location and click Next.
   For this example the location /opt/oracle/middleware.
   

   

7. In the Installation Type dialog ensure that Complete with Examples is selected and click Next.
   

   

8. In the Prerequisite Checks dialog click Next.
   

   

9. In the Security Updates dialog uncheck I wish to receive security updates and click Next.
   

   

10. In the Email Address not specified dialog click Yes.
    

    

11. Examine the installation summary, return to a prior dialog to correct any errors and then click Install.
    

    

12. In the Installation progress dialog click Next.
    

    

13. In the Install Complete dialog, ensure that Automatically launch Quickstart is checked and click Finish.
    

    

14. The quick configuration wizard will start and display its splash screen.
    

    

15. In the Quickstart wizard enter password Welcome1 in both Password and Confirm password and then click Create. 
    Take care when entering these credentials. If alternate credentials are used note them for later use when logging into the WebLogic Server console.
    

    

16. On the Configuration Process step, click Next.

17. On the Configuration Details dialog click Finish.
    Note, ensure that Start Domain is NOT checked.
    
    WebLogic Server 12.1.3 with all samples has now been installed.
    

1. Open a command prompt and change directory to wlserver/common/bin directory under the Middleware home directory.
   
   $ cd ${ORACLE_HOME}/wlserver/common/bin
   for example:

2. Start the configuration wizard with a command similar to:
   $ ./config.sh
   The Configuration Wizard splash screen will display.
   

3. Ensure that the Create a new domain radio button is selected. If needed modify the domain location. Click Next.
   

4. From the Templates dialog select the Coherence Cluster extension and click Next.
   

5. In the Administrator account dialog enter password Welcome1 and click Next.
6. In the Domain Mode and JDK dialog, accept the defaults and click Next.
7. In the Advanced Configuration dialog select Node Manager and Managed Servers, Clusters and Coherence. Then click Next.
   

8. In the Node Manager dialog select Per Domain Default Location and enter credentials weblogic/Welcome1. Then click Next.
   

9. On the Add dialog click add and add four servers with names and ports as shown below.
   
   

   Name	Port
   cache_server1	7003
   cache_server2	7005
   webapp_server1	7007
   webapp_server2	7009

   
   When complete the results should resemble:
   
   
   When complete, click Next.
   
10. In the Clusters dialog click Add and add two WebLogic Server clusters with names CacheServerWebLogicCluster and WebAppServerWebLogicCluster.
    When complete the dialog should resemble:
    
    When complete, click Next.
    
    
11. Using the Assign Server dialog, assign servers by selecting a server and using the arrow keys to assign that server to a cluster. Assign the cache_server instances to the CacheServerWebLogicCluster and the webapp servers instances to the WebAppWebLogicCluster.
    When complete the dialog should resemble:
    
    
    
    When complete, click Next
    
    
12. In the Coherence Clusters dialog change the cluster name to CoherenceCluster and set the port to 9000, then click Next.
    

13. In the Machines dialog use the add button to add a single machine named machine, then click Next.
14. In the Assign Servers to Machines dialog assign all servers to the newly created machine. When complete the results should resemble those below.
    Then click Next.
    

15. The Configuration Summary should resemble that shown below. Click Create to create the domain.
    
    

16. Click Next.
17. On the Configuration Success dialog click Finish.

You have now successfully created a domain.
In the next section we will start the administration server and complete the configuration of the domain.

Carry out the following steps to start an instance of Node Manager and an administration server.
1. In the command window change directory to the location of the new domain home. 
   
   $ cd ${ORACLE_HOME}/user_projects/domains/base_domain/bin
   
   Replace base_domain with the appropriate name if different.
   
2. Using a command similar to that shown below, start an instance of node manager.
   
   $ ./startNodeManager.sh > ~/nodemanager.log 2>&1 &
   Start an instance of tail using a command similar to tail -f ~/nodemanager.log.
   
   When node manager has started listening on its designated port, exit the command and move to the next step.
   
   For example:
   
   Consider adding nohup to startNodeManager.sh if you would like the server to continue running of the command prompt is closed.
   
3. Using a command similar to that shown below, start an instance of the administration server.
   
   $ ./startWebLogic.sh > ~/admin.log 2>&1 &
   Start an instance of tail using a command similar to tail -f ~/admin.log.
   
   The administration server is stared with the log shows a state of RUNNING as shown below.
   

Carry out the following steps to complete the configuration of the Coherence cluster using the console.


1. Using your browser of choice open a connection to http://localhost:7001/console. Log in using the previously entered credentials (weblogic/Welcome1).
   

2. In the Domain Structure pane, expand Environment and choose server.
   
   
   
   The right pane will change to display the previously created servers which will resemble those shown below. Ensure all servers exist and are stopped.
   

3. In the domain structure pane expand Environment > Clusters.
   
   The right pane will change to display all WebLogic Server clusters.
   
   
4. In the right pane, select the WebAppWebLogicCluster.


5. Select the Coherence tab.
   
   Notice that the default for a WebLogic Cluster which is a member of a Coherence domain is storage enabled.
   
6. Uncheck the Local Storage Enabled flag (shown in its original checked state).
   

7. Click Save.
8. In the Domain Structure pane navigate to Environment>Servers.
   
9. In the Servers page select cache_server1.
10. Select the Coherence tab of cache_server1.
11. Make cache_server1 a JMX enabled management node by checking the field is Coherence Management Node.
    Shown below in the default state of disabled.
    

12. Click Save.
13. In the Domain Structures page navigate to Environment > Servers.
14. Select the Control tab.
15. In the Control tab, select the four servers and click Start.
    

16. Depending on machine capacity it can take between 3 and 5 minutes to start all server instances.
    Use the refresh icon() to refresh the display. 
    

The examples come in source form and must be built. WebLogic Server ships with Apache Ant. The Coherence examples include ant based build scripts which can be used to build the provided examples.

To build the Coherence samples perform the following:


1. Open a command prompt.
   
2. Change to the bin directory under the newly created domain directory.
   $ cd ${ORACLE_HOME}/user_projects/domains/base_domain/bin
   
   
3. Prepare the environment by executing the set domain environment script.
   source ./setDomainEnv.sh
   
   
4. Change directory to the samples location
   cd $ {ORACLE_HOME}/user_projects/applications/wl_server/examples/src/examples/coherence/managed-coherence-servers/common/prj
   
   
5. Using ant build the samples using a command similar to:
   ant package
   Which will produce output similar to:
   $ ant package
   to override old definition of task jspc
   Trying to override old definition of task rmic
   
   clean:
   
   banner:
   [echo]
   [echo] ******************************************************************************
   [echo] |
   [echo] | Cleaning build environment for project: managed-coherence-servers-examples
   [echo] |
   [echo] ******************************************************************************
   [echo]
   . . .
   [jar] Building jar: /opt/oracle/middleware/user_projects/applications/wl_server/examples/src/examples/coherence/managed-coherence-servers/common/build/gui/classes/ExampleGUI.jar
   BUILD SUCCESSFUL Total time: 6 seconds
   For brevity we will refer to the following directory as EXAMPLES_HOME ${ORACLE_HOME}/user_projects/applications/wl_server/examples/src/examples/coherence/managed-coherence-servers

If the prior step was successful a set of artifacts was build in:
${ORACLE_HOME}/user_projects/applications/wl_server/examples/src/examples/coherence/managed-coherence-servers/common/build.
The ExampleGAR.gar and ExampleEAR.ear will be deployed and tested in the next sections.


1. Using a browser login to the console using URL http://localhost:7001/console and credentials weblogic/Welcome1.
2. In the Domain Structure pane navigate to Environment > Deployments.
3. In the Summary of Installments pane click Install.
4. Navigate to the directory
   EXAMPLES_HOME/s/common/build/.
   

5. There are a number of directories, click open directory next to the the gar directory.
   
   
6. Select ExampleGAR.gar and click Next.
   
7. On the Choose Targetting style step ensure that Install this deployment as an application is checked and click Next.
   
8. In the Select deployment targets step choose CacheServerWebLogicCluster > All Servers in the Cluster.
   

9. In the Optional Settings step click Finish. The Summary of Deployments pane will be displayed and should resemble:
   
   

   If you were successful the GAR will be deployed and in state Active.

Now that the ExampleGAR.gar is deployed we will deploy the associated web application.


10. Click Install.
    
    
11. Navigate to the EXAMPLE_HOME/common/build/ear directory.
    Select the file ExampleEAR.ear. The Install Application Assistant pane should resemble:
    
    Click Next.
    
    
12. On the Choose Targeting style step ensure that Install this deployment as an application is checked and click Next.
13. In the Select Deployment Targets step, ensure that WebAppWebLogicCluster is checked and click Next.
    

14. In the Optional Settings step click Finish.
    When complete the summary of deployments should resemble:
    

15. Expand ExampleEAR by clicking the plus (+) sign. The application will expand and should resemble that shown below.
    

16. Run the application by entering URL http://localhost:port/example-web-app/faces/ContactList.jspwhere port is either 7007 or 7009.
    
    The application should display a page similar to:
    
    
    
    

In this section we will use the WebLogic Server console application to:

1. Create a new WebLogic Cluster for the proxy instances and associate with the Coherence cluster.
2. Create two managed servers, which will be used as proxy servers, and add them to the proxy cluster.
3. Create a cache configuration override using the proxy-cache-config.xml cache configuration file and assign to the new WebLogic Server cluster.
4. Start the new proxy managed servers.
5. Deploy ExampleGAR to the proxy cluster.
6. Override the cache configuration in the ExampleGAR.
7. Test that the cache configuration override was successfully applied.

To add the proxy instances, perform the following steps:

1. Login to the WebLogic Server console at URL http://localhost:7001/console using credentials Weblogic/welcome1.
2. In the Domain Structure expand Environment > Clusters. The Summary of Clusters pane will display.

   

3. Click New > Cluster.
4. Name the cluster ProxyWebLogicCluster, leaving all other fields unchanged, and click OK.
   The newly created cluster will be displayed.
   

   

5. Open the newly created cluster by clicking its name in the Summary of Clusters pane.
6. Select the Coherence tab.
7. From the drop down cluster list select the CoherenceCluster and click Save.
   

   

   Once associated with a Coherence cluster, other Coherence configuration may be modified.
   
8. Uncheck ... and click Save.
   
   
   We are now free to add Managed Coherence Instances to the Proxy WebLogic Cluster.
   
   
9. In the Domain Structure pane expand Environment > Servers.
10. In the Summary of Servers pane click New.
11. Enter Server Name: proxy_server1.
    Enter Server Listen Port: 7011.
    Select Yes, make this server a member of an existing cluster and choose the newly created ProxyWebLogicCluster.
    Click Finish to save the changes.
    

12. In the Summary of Servers pane, click the new proxy_server1 name. 
13. In the Setting for server pane, choose the Configuration > General tab and then in the Machine drop down choose machine and click Save.  
    

    We must now change the unicast port for the proxy server so we can connect to a specific port from Extend clients.

14. Select the Coherence tab
15. Change Unicast Listen Port to 9020.
    Check Unicast Port Auto Adjust,
    Un-check Local Storage Enabled.
    Click Save.
    

16. Create the second instance by cloning proxy_server1.
    
    1. In the Domain Structure pane select Environment > Servers. 
    2. Check proxy_server1 and click Clone. 
    3. Change the Name to proxy_server2 and server Listen Port to 7013.
    4. Click Ok.
17. In the Domain Structure page select Environment > Coherence Clusters.
18. Click the CoherenceCluster cluster.
19. Click the Cache Configurations tab. 
20. Click New to create a new cache configuration.
21. In the Cache Configuration propertues dialog, set:
    Name:                                           ProxyCacheConfiguration
    JNDI Name:                                   ExamplesGar
    Cache Configuration File:             EXAMPLE_HOME/common/resource/config/proxy-cache-config.xml
    Import Cache Configuration File:  Checked.
    
    Assuming the example install location the fully qualified path to the configuration file is: /opt/oracle/middleware/user_projects/applications/wl_server/examples/src/examples/coherence/managed-coherence-servers/common/resource/config/proxy-cache-config.xml.
    Click Next.
    
    
22. Target the cache configuration to the proxy server cluster by checking ProxyWebLogicCluster. Click Finish.
    

23. In the Domain Structure pane expand Environment > Deployments.
24. Open the ExamineGAR deployment by clicking its name. 
25. Select the Targets tab.
26. Check ProxyWebLogicCluster and then Click Save.
    The Coherence application is now deployed to both the cache server and proxy clusters.
    

27. Start the new proxy servers by:
    
    1. In the Domain Structure pane expand Environment > Servers.
    2. Choose the Control tab.
    3. Check proxy_server1 and 2.
    4. Click Start.
28. Validate that the override configuration has been used by:
    
    1. Open a command prompt
    2. Change directory to the ORACLE_HOME directory, for example:
       $ cd /opt/oracle/middleware
    3. Search the proxy server logs for a log statement showing the loading of the proxy configuration file using a command similar to:
       $ find . -name 'proxy_server*.log' | xargs grep cache-config.xml
    4. If the cache configuration override was successfully loaded, log statements referencing the file should be found. For example:
       

In this section we will build a Coherence*Extend GUI application and run it against the newly added proxy tier.

1. Open a command prompt.
2. Change directory to the base domain bin directory.
   $ cd ${ORACLE_HOME}/user_projects/domains/base_domain/bin
3. Setup the WebLogic Server environment.
   $ source ./setDomainEnv.sh
4. Change directory to the Coherence examples directory.
   $ cd /opt/oracle/middleware/user_projects/applications/wl_server/examples/src/examples/coherence/managed-coherence-servers/common/prj/
5. Compile the examples to a directory of your choice, for this tutorual we will use /home/oracle/gui.
   $ ant -Dinstall_dir=/home/oracle/gui installgui
   You should see output similar to: [mkdir] Created dir: /home/oracle/gui/config
   [mkdir] Created dir: /home/oracle/gui/lib
   [mkdir] Created dir: /home/oracle/gui/bin
   [copy] Copying 1 file to /home/oracle/gui/config
   [copy] Copying 1 file to /home/oracle/gui/config
   [copy] Copying 1 file to /home/oracle/gui/lib
   [copy] Copying 1 file to /home/oracle/gui/lib
   [copy] Copying 1 file to /home/oracle/gui/bin
   [copy] Copying 1 file to /home/oracle/gui/bin
   BUILD SUCCESSFUL
   Total time: 2 seconds
   
6. Change directory to the directory specified by the -D parameter above.
   $ cd /home/oracle/gui
   
7. Inspect the config/extend-cache-config.xml file. This file defines how to connect to the cluster.
   Examine the address-provider element, which removes the need to put any specific IP addresses in the cache-configuration files.
   For example:
   $ less config/extend-cache-config.xml. . .
     <initiator-config>
       <tcp-initiator>
           <name-service-addresses>
              <address-provider>extend-address-provider</address-provider>
           </name-service-addresses>
        </tcp-initiator>
   </initiator-config>
   The address-provider is defined in the tangosol-coherence-override.xml.
   
8. Using gedit or your favorite editor, open config/tangosol-coherence-override.xml.
   $ gedit config/tangosol-coherence-override.xml
9. The extend-address-provider is defined by a section of xml starting with address-provider.
   
   
   1. Find the <address> element.
   2. Replace the embedded 192.xxx IP address with localhost or the IP address of the machine hosting the proxy servers. 
   3. Save the changes and exit the editor.
   
   For example:
   

10. Start the Coherence*Extend GUI client:
    The client is a simple Java Swing client that listens for events on the contact cache via a MapListener.
    
    1. change to the bin directory
       cd bin
    2. Make the shell scripts executable
       chmod +x *.sh
    3. Run the client
       source start_gui_client.sh
       The Managed Coherence Servers Extend Example will then start.
       
    4. In a browser open the Contact List application at URL
       http://localhost:[7007|7009]/example-web-app/faces/ContastList.jsp.
    5. Select a row and click update.
       

    6. Make a change to any data element other then name, which is used as a key, and click Save. 
    7. Examine the Coherence*Extend application which reflects the change.
       

    8. Exit the GUI client.

When running Coherence outside of WebLogic Server, individual instances can set -Dtangosol.coherence.management=all which allows you to connect to any DefaultCacheServer node and see Coherence MBeans from all servers. Within WebLogic Server, the administration server does this roll-up of the data and which can be inspected by connecting to the the domain runtime MBean server.   In this section we connect to and examine the running state of Coherence using JVisualVM


Readers interested in comprehensive coverage of JVisualVM and the Coherence plug-in are directed to the Oracle Learning Library (OLL). A search of JVisualVM will return a self study and associated OBE.  However the following steps show the basics of using JVisualVM to examine Coherence MBeans running within WebLogic Server.

To use JVisualVM to monitor and manage the Coherence environment.

1. Open a command prompt and change directory to the base_domain bin directory.
   $ cd /opt/oracle/middleware/user_projects/domains/base_domain/bin
   
2. Execute the set domain environment script
   $ source setDomainEnv.sh
3. Change directory to EXAMPLES_HOME/common/resource/bin
   cd /opt/oracle/middleware/user_projects/applications/wl_server/examples/src/examples/coherence/managed-coherence-servers/common/resource/bin
4. Examine the jvisualvm script, which contains several settings for connecting to the administration WebLogic Server MBean server.
   $ cat jvisualvm.sh
   #!/bin/bash
   #
   # Copyright (c) 2013,2014, Oracle and/or its affiliates. All rights reserved.
   #
   # This script will connect to the domainRuntime() mbeans on the admin server and
   # allow you to view the coherence MBeans for the entire coherence cluster.
   #
   
   if [ -z "$WL_HOME" ] ; then
   echo "You must run setDomainEnv.sh"
   exit 1
   fi
   
   export WLS_CP=$WL_HOME/server/lib/wljmxclient.jar:$WL_HOME/server/lib/weblogic.jar
   
   $JAVA_HOME/bin/jvisualvm --cp:a $WLS_CP \
   -J-Djmx.remote.protocol.provider.pkgs=weblogic.management.remote \
   -J-Dcom.oracle.coherence.jvisualvm.refreshtime=10 -J-Xmx1g -J-Xms1g \
   -J-Dcom.oracle.coherence.jvisualvm.disable.mbean.check=true
   #
   # Add a JMX connection in JVIsualVM using the following service url and enter user/ password for the connection
   #
   # service:jmx:iiop://localhost:7001/jndi/weblogic.management.mbeanservers.domainruntime
   
   Consider using copy/paste to save the service description above and past it into JVisualVM.
5. Execute the script
   $ source jvisualvm.sh
   If an error dialog is presented, click Disable Modules and Continue to continue.
   

6. Open a connection to the Administration Servers MBean server by choosing:
   
   1. File > Add JMX Connection.
      

   2. In the Add JMX Connection dialog enter connection details and click OK.
      Connection: service:jmx:iiop://localhost:7001/jndi/weblogic.management.mbeanservers.domainruntime
      Credentials: weblogic/Welcome1.
      If JVisualVM is connecting from a different host or using a different port, adjust the connection details accordingly
      

   3. In the application pane select the new connection.
      

7. In the right pane one or more panes are displayed. Typically including the MBeans pane.
   If the MBeans pane is not displayed, then its likely the MBeans plugin is not installed.  Please see the JVisualVM plugins page, available here, for information on downloading and installing plugins including the MBeans plug in. 
8. Click Coherence to expand the Coherence MBeans. 
   The set of available Coherence data should resemble:
   

9. Expand any MBean to see its values and operations. Expanding Cache, ultimately results in:
   

Beginning with Coherence 12.1.3, the JVisualVM Coherence plugin is included with the WebLogic Server install when Coherence is also installed. WebLogic Server with Coherence 12.1.2 can use the JVisualVM Coherence plugin, however users will need to download the plug in.

To install the Coherence plugin for JVisualVM

1. At the command line, start JVisualVM.  You needn't connect to any JVM instance at this time.
   Choose Tools > Plugins.
   

2. Choose the Downloaded tab and select Add Plugins.
3. Navigate to the location of the Coherence JVisualVM plugin which should be
   ${ORACLE_HOME}/coherence/plugins/jvisualvm/coherence-jvisualvm.nbm.
   

4. Click Install.
5. In the install plugin wizard click Next.
6. Accept the terms of the license agreement and click Install. 
7. In the validation warning dialog click Continue. 
8. Then the plugin installation completes click Finish
9. Click Close. 
10. Open a new connection using a process similar to that used in the prior section. 
11. In the right pane a new Oracle Coherence tab now exists. Select the Oracle Coherence tab.
    

12. Explore the different sub-tabs representing different areas of Coherence functionality.

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 don't lose data while carrying out this operation. Maintaining data is usually achieved by checking the statusHA value of the services within the cluster and ensuring that they are always in state MACHINE-SAFE or NODE-SAFE after each deploy operation.

In a typical WebLogic Server cluster, when an application is redeployed, it is redeployed on all cluster members at the same time. Re-deployment to all cluster members is problematic for GAR application as it would mean loss of all data in the Coherence caches managed by that GAR.

In WebLogic Server 12.1.2, a new deployment feature was added to allow selective deployment of a GAR to individual managed servers of a WebLogic cluster, even if the GAR was originally deployed to the WebLogic cluster. This is enabled by using the specifiedtargetsonly option. It can be used in the following ways:

This is enabled by using the specifiedtargetsonly option. Rolling restart can be used in the following ways:

• WLST:  Use the WLST deploy function to selectively re-deploy an updated application.
  deploy(appName, appFile, currentServerName, specifiedTargetsOnly='true') 
• wldeploy ant task: Use the wldeploy ant task to perform the redeploy.
  <wldeploy user="${admin.username}" password="${admin.password}"
            adminurl="t3://${admin.host}:${admin.port}" debug="false"
            action="deploy" name="Managed Coherence Servers GAR Test"
            source="${gar.filename}" targets="ms3" specifiedtargetsonly="true"
            failonerror="true">
  </wldeploy>
• Using weblogic.deployer: specifying option -specifiedtargetsonly

A sample WLST script to carry out a rolling redeployment is included with WebLogic Server. To run this carry out the following

1. Login to the WebLogic Server console at URL http://localhost:7001/console using credentials Weblogic/welcome1.
2. In the Domain Structure pane expand Environment, choose Servers.
3. Select cache_server2 and click Clone.
   

4. Change the name to cache_server3 and the listen port to 7030 and click Ok.
   

5. Select the Control tab, select the newly added server, and click Start.
6. Open a command prompt.
7. Change directory to /opt/oracle/middleware/user_projects/domains/base_domain/bin.
8. In the command prompt set the WebLogic environment using a command similar to:
     source ./setDomainEnv.sh
   
9. Change directory to EXAMPLES_HOME /common/resource/wlst and copy the file gar_common.py to the ${WL_HOME}/common/wlst directory.
   This file contains the garRedeploy function.
   
   
   
10. Change directory to a convinient location, in this OBE /home/oracle was used, and create a script called test_redeploy.py and add the following contents. Replace the second argument with the full path of the deployed GAR. This can be found by selecting the deployment from the Deployments option and noting the Source Path. The garRedeploy command and all its arguments should be on a single line and resemble:
    
    connect()
    garRedeploy('ExampleGAR',
    '/opt/oracle/middleware/user_projects/applications/wl_server/examples/src/examples/coherence/managed-coherence-servers/common/build/gar/ExampleGAR.gar',
    'CacheServerWebLogicCluster','NODE-SAFE')
    
11. Run the script with the following command.
    java weblogic.WLST test_redeploy.py
    
12. When prompted enter the credentials.  The script should produce results similar to:
    
    

13. Once the script has finished running, check the application to ensure that all the data is present meaning that the rolling restart/redeploy was successful.

1. Login to the WebLogic Console at http://localhost:7001/console.
2. In the Domain Structure pane expand Environment and select Coherence Clusters.
3. Click cluster name Coherence Cluster.
4. Select the Security tab, then the Cache sub tab.
5. Click New to add a new cache configured for security.
6. Enter contacts as the name of the cache and click Finish.
   

7. In the Coherence Caches list click the newly added cache name contacts.
   Roles and policies associated with the cache are displayed.
   

8. Select the policies tab.
9. In the Settings for Contacts pane click Add Conditions.
   

10. On the Predicates step, in the Predicate List drop down choose User and click Next.
    

11. On the Edit Arguments step, add user weblogic, click Add.  When the user has been added click Finish.
    

12. Click Save. 
13. Restart all server instances by:
    
    1. Expanding Environments in the Domain Structure pane.
    2. Selecting Servers.
    3. Choose the Control tab. 
    4. Select all servers, except the AdminServer.
    5. Choose Shutdown > Force Shutdown Now. 
    6. Pause as the servers shut down, this could take 1-3 minutes or more depending on computer performance.
    7. Select all servers, except the Admin Server.
    8. Click Start.
    9. Pause 1-3 minutes or more depending on computer performance.

    Consider using the refresh button to track server start up.

1. Access the application using URL http://localhost:700[7|9]/example-web-app/faces/ContactList.jsp.
   
   An insufficient rights error will be displayed due to the newly added security requirement.
   

1. Open a command prompt.
2. Change directory to ${ORACLE_HOME}/user_projects/domains/base_domain/bin.
3. Configure the environment using a command similar to:
   $ source setDomainEnv.sh
   
4. Change directory to EXAMPLES_HOME/common/resource/config/
   $ cd /opt/oracle/middleware/user_projects/applications/wl_server/examples/src/examples/coherence/managed-coherence-servers/common/resource/config
   
5. Copy the required files to enabled basic authentication using a command similar to:
   $ cp –f web*.xml ../../war/WebContent/WEB-INF
   
   Examination of the web.xml shows the addition of a login-config element defining BASIC security.
   Examination of the weblogic.xml shows an authorized  principal (weblogic).
   
   Confirm that both files were copied before continuing.
   
   
6. Change directory to EXAMPLES_HOME/common/prj
   
   
7. rebuild the examples using an ant command similar to:
   $ ant package
   
   Ant should produce output similar to:
   
   . . .
   [echo]
   [echo] ******************************************************************************
   [echo] |
   [echo] | Packaging files for project: managed-coherence-servers-examples
   [echo] |
   [echo] ******************************************************************************
   [echo]
   [jar] Building jar: /home/oracle/examples/managed-coherence-servers/common/build/gar/ExampleGAR.gar
   [war] Building war: /home/oracle/examples/managed-coherence-servers/common/build/war/ExampleWebApp.war
   [ear] Building ear: /home/oracle/examples/managed-coherence-servers/common/build/ear/ExampleEAR.ear
   [jar] Building jar: /home/oracle/examples/managed-coherence-servers/common/build/gar/ExampleListener.jar
   [ear] Building ear: /home/oracle/examples/managed-coherence-servers/common/build/ear/ExampleListenerEAR.ear
   jar] Building jar: /home/oracle/examples/managed-coherence-servers/common/build/gui/classes/ExampleGUI.jar
   
8. Return to the WebLogic Server Console.
9. In the Domain Structure Pane choose Deployments. 
10. Select the ExampleEAR deployment and click Update.
11. On the Local new deployments file step, click Finish.
12. Access the updated application using URL Access the application using URL http://localhost:700[7|9]/example-web-app/faces/ContactList.jsp. 
13. When prompted enter the weblogic users credentials and click OK.
    

14. Assuming correctly entered credentials the application will then display.
    
    

Congradulations, you have successfully completed the Managed Coherence Server OBE Tutorial.