Managed Coherence Servers

Files Prepare Deploy Troubleshooting Related Topics

About the Example

Coherence Persistence feature stores cache data onto disk so the data can be recovered quickly after a catastrophic failure or a cluster restart due to planned maintenance. Coherence Persistence includes the following capabilities:

Declarative Configuration - Persistence is configured using Coherence configuration files and requires no changes to application code. An operational override file is used to configure a persistence environment. Coherence provides two default environments, default-active and default-on-demand, which can be used directly without any modifications. The cache configuration file is used to set persistence properties on a distributed cache.
Shared-Disk or Local-Disk Storage Option - Persistence provides the options of persisting data partitions to a shared disk or persisting data partitions for each cache server on the computer’s local disk. For the default-active and default-on-demand persistence modes, the default directory is named 'coherence' under @DOMAIN_HOME.
Active or On-Demand Persistence Modes - Persistence supports both active persistence and on-demand persistence. In active persistence mode, any mutations to cached data is automatically persisted to disk. In on-demand mode, active persistence is disabled and cached data is only backed up or recovered upon request.
Persistence snapshots - Persistence allows a cache to be backed up at any point in time. Snapshot persistence is supported for both active and on-demand persistence mode.
Persistence Quorum policies - Persistence can be configured to use quorum policies that control how many cluster members must be present before the cluster allows active persistence operations or recovery to commence. Quorum policies allow time for a cluster to start before data recovery begins.
JMX-Based Management and Operations - Persistence can be managed using MBean attributes and operations. The attributes and operations make it easy to perform persistence operations and monitor persistence health and configuration. There are predefined WLST functions provided to easily perform persistence Operations, and this will hep administrators to automate the recovery operations.

From 12.2.1 release of Coherence, On-Demand persistence is switched on by default for all the distributed caches. This example will go through basic configurations for On-Demand and Active persistence scenarios.

Files Used in the Example

Directory Location: D:\Oracle\Middleware\Oracle_Home\wlserver/samples/server/examples/src/examples/coherence/managed-coherence-servers/persistence

example-cache-config-persistence.xml

Oracle Coherence cache configuration file used in this example.

Prepare the Example

Prerequisites

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

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.
Two 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 and Run 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.

Deploy and Run the Example

On-Demand Persistence

By default On-Demand Persistence is turned on in 12.2.1 release of Coherence. In this example, the predefined WLST functions will be used to persist cache-data onto filesystem and then recover the data from the filesystem. We are assuming that the multi-server example has been used to create the Weblogic Domain, even though the following steps are valid for other setups.

Deploy and run the Multi Server example. Navigate to the URL mentioned in the example to see the cache contents. Use the action buttons in the page to modify the cache like adding, deleting or editing the contacts cache.
In this step, a snapshot of the current contents in the cache will be created using WLST command.Connect to Weblogic Domain MBean server using WLST as shown by the following commands. Please replace the password, hostname and port with the values provided while setting up Multi Server example. The port here is the Admin Server port and is typically 7001. The persistence related WLST commands can only be used if the location is changed to domain runtime as shown below
```
      java weblogic.WLST
      connect('weblogic','password','t3://hostname:port')
      domainRuntime()
```
Execute the following command to create a snapshot of the ExampleGAR:PartitionedPofCache service, which includes 'contacts' cache.
```
coh_createSnapshot('ContactsSnapshot', '"ExampleGAR:PartitionedPofCache"')
```
Here 'ContactsSnapShot' is the name of the snapshot, and can be changed to any suitable name. The second parameter is the service name of the 'contacts' cache. The service name for a cache will be defined in the Cache Configuration XML. In this example, the Cache Configuration XML used is located at D:\Oracle\Middleware\Oracle_Home\wlserver/samples/server/examples/src/examples/coherence/managed-coherence-servers/common/resource/config/example-cache-config.xml. Please read the coherence documentation to understand more about Cache Configurations and Service Names.
Once the snapshot is created, navigate to the URL mentioned in the first step and click on the "Clear Cache" button. This will clear the 'contacts' cache.
In the WLST console opened in Step 2 above, execute the following WLST command.
```
coh_recoverSnapshot('ContactsSnapshot', '"ExampleGAR:PartitionedPofCache"')
```
Now navigate to the URL mentioned in Step 1, and the cache will be populated again, and the contents will be same as when you created the snapshot.

The steps above can be modified such that the even if storage enabled managed servers are restarted after Step 3, and the cache contents can still be recovered using the coh_recoverSnapshot WLST operation. Please note that on restart, the cache will be populated with 20 entries. This is because in the LifecycleListener postStart() method, 20 entries are added if the cache is empty. Please go through the file LifecycleReactor.java, mentioned in the Files section of Multi Server example

By default, the snapshots are created in @DOMAIN_HOME/coherence directory. The locations and other configurations can be overridden using a Coherence Operational Override file. Please read the Coherence Documentation to understand more about Coherence operational override file and the Persistence related settings.

Active Persistence

In the On-Demand example above, the cache contents are persisted when a snapshot is created and snapshots are created as and when required using WLST commands. Hence the name On-Demand. The other persistence mode is 'Active' mode. In active persistence mode, any mutations to cached data is automatically persisted to disk. In the eventuality that the cache servers go down at any instant, the data which was persisted in the file system will be recovered during the restart of the cache servers.

In order to use Active Persistence, the cache configuration file needs few modifications. The cache configuration for Active persistence mode used in this example is located at D:\Oracle\Middleware\Oracle_Home\wlserver/samples/server/examples/src/examples/coherence/managed-coherence-servers/common/resource/config/example-cache-config-persistence.xml Please note the new XML elements that have been introduced in the cache configuration file some of which are

persistence element - The persistence environment is set inside this element. There can be different persistence environment is a single Coherence Cluster and the different environments can be used by different caching services. Each environment can have different settings such as the filesystem path to persist the cache data etc.
partitioned-quorum-policy-scheme element - The partitioned-quorum-policy-scheme elements is used to set the Quorum policies which in the example is set such that at least 2 storage enabled members must be present in order to use the persistence operations. Please note that the cache cannot be used unless the Quorum policies are met.

Please read the Coherence Documentation to understand more about the various cache configuration elements related to persistence.

Deploy and run the Multi Server example. Navigate to the URL mentioned in the example to see the cache contents.
Navigate to the D:\Oracle\Middleware\Oracle_Home\wlserver/samples/server/examples/src/examples/coherence/managed-coherence-servers/persistence and execute the following commands.

ant all
ant redeployMultiServer

While executing the 'ant all' command above, the cache configuration that is packaged inside the GAR file will be the D:\Oracle\Middleware\Oracle_Home\wlserver/samples/server/examples/src/examples/coherence/managed-coherence-servers/common/resource/config/example-cache-config-persistence.xml mentioned above.
Since the GAR and EAR files are changed, these applications needs to be redeployed. The 'ant redeployMultiServer' undeploys the existing applications installed by the Multi Server example and deploys the new applications which has been built using the 'ant all' command.
Now navigate to the URL mentioned in Step 1, and the modify the context of the cache by doing operations such as add contacts, edit contacts etc.
Restart all the managed server using the WLS administration console.
Navigate to the URL mentioned in Step 1 and verify that all the cache context look the same as before the restart and all of the changes done in Step 3 has been preserved.

In active mode also, snapshots can be created and recovered, as explained in the On-Demand scenario

Even though the above steps makes use of the Multi Server example, the same steps can be applicable for all Coherence Applications which uses Active persistence mode. For any Coherence application, in order to use Active persistence mode, the broad steps needed are as follows

Set the persistence environment to be used in the Coherence Operational Override file. The typical settings of a persistence environment are the persistence mode to be used and the filesystem path in which the cache contents needs to be stored. By default coherence provides two persistence environments, default-active and default-on-demand.
Change your cache configuration to set the persistence environment and quorum policies.

Other WLST commands

Some of the other WLST command which have been introduced for persistence operations are

coh_listSnapshots(serviceName) - List all the snapshots that have been created for the Coherence Service with the specified name
coh_removeSnapshot(snapshotName,serviceName) - Remove the snapshot with the specified name that had been created for the Coherence Service
coh_archiveSnapshot(snapshotName,serviceName) - Archive the snapshot with the specified name that had been created for the Coherence Service
coh_retrieveArchivedSnapshot(snapshotName,serviceName) - Retrieve the archived snapshot with the specified name that had been created for the Coherence Service

Please read the the Oracle Weblogic Documentation related to Coherence to understand more about the various WLST methods and its usage.

Troubleshooting

If ant command cannot be found, ensure you have run . ./setWLSEnv.sh (UNIX/Linix) or setWLSEnv.cmd (Windows).
General Troubleshooting Tips for Examples

document.write(document.title);