Running the Coherence 12.2.1 Persistence Examples

In this post I’ll show you how to get started with the new Coherence Persistence feature in 12.2.1 by working through the examples that ship with the product.

Firstly a quick overview of what Persistence is about.

Persistence Introduction

Persistence is a set of tools and technologies that manage the persistence and recovery of Coherence distributed caches. Cached data is persisted so that it can be quickly recovered after a catastrophic failure or after a cluster restart due to planned maintenance. Persistence and federated caching can be used together as required.

Persistence can operate in two modes:

  • On-Demand persistence mode – a cache is manually persisted and recovered upon request using the snapshot manager. The snapshot manager is exposed as an MBean interface that provides operations for creating, archiving, and recovering snapshots of a cache.
  • Active persistence mode – In this mode, cache contents are automatically persisted on all mutations and are automatically recovered on cluster/service startup. The snapshot manager can be used in active persistence mode to perform on-demand snapshots of a cache.

See the the Online Documentation or our Persistence YouTube Screencast for more information.


Follow the instructions in my post from last month on how to install Coherence with the examples.  Once you have done this, then continue on to run the Persistence examples.

Setting your Environment 

Now that you have completed the installation above you need to open a command prompt or terminal window and setup your environment with the following environment variables:

  • JAVA_HOME  – points to the directory you install the JDK
  • COHERENCE_HOME – points to the base directory you installed Coherence to

Note: If you are running Coherence or greater, you will not need to set the COHERENCE_HOME variable.

Open a terminal and change to the examples/java directory under your Coherence home.

E.g. for Windows: (assuming you installed into c:\Oracle\Middleware\1221)

SET JAVA_HOME=c:\jdk\jdk1.8.0_65
cd \Oracle\Middleware\1221\coherence\examples\java
set COHERENCE_HOME=%cd%\..\..

Or for *NIX / Mac (using bash)

SET JAVA_HOME=/u01/jdk1.8/
cd /u01/product/coherence1221/coherence/examples/java
export COHERENCE_HOME=`pwd`/../..

Note: You don’t need to set JAVA_HOME on Mac.

Next run the following to check you have everything setup correctly:

bin\build contacts
bin\build persistence

You should see something like the following:

building contacts from com/tangosol/examples/contacts ...
Please refer to readme.txt for instructions on how to run the contacts example

If you don’t, check that you have JAVA_HOME and COHERENCE_HOME set correctly.

Hint for Windows users: Once you have completed the above, just type start in a command window and press enter. This will open another window with the same environment set. Do this a couple of times as we will need a number of command prompts.

Running the Examples

There are a number of different examples you can run to get a feel for how persistence works. Take a look in the readme.txt and search for ‘Persistence example’. The examples you can run are:

  1. Basic snapshot operations – shows how to issue Persistence Operations from Java
  2. Display Persistence notifications – shows how to use JMX Notifications to subscribe and display Persistence operations
  3. Running Persistence operations in parallel
  4. Advanced example – There are also SFTP snapshot archiver advanced example. (Leave that until you understand the concepts)

The readme.txt explains the steps to run each example, but I have included the Basic Snapshot operations example below for convenience.

The basic example shows how to call snapshot operations from Java.
Persistence is configured to store data in the ‘persistence-data’ directory under java examples home. Refer to resource/persistence/tangosol-coherence-override.xml for details of the defined persistence-environment.

First, build the persistence example using the following:
(Only required once, Ignore if you already did this above)

bin\build contacts
bin\build persistence

Next, start one or more cache servers using in separate terminals using:

bin\run-cache-server persistence

Next, in a separate terminal run the persistence example using:

bin\run persistence

The example will run and output similar to the following will be displayed:

------BasicSnapshotOperations example begin------

------Initial data size is 0------

------create new snapshots------
      create new snapshot snapshot-empty
      snapshots = [snapshot-empty]

------Populated data size is 10000------
      create new snapshot snapshot-10000
      snapshots = [snapshot-10000, snapshot-empty]

------recover snapshot------
      cleared cache, size = 0
      Recover snapshot snapshot-10000 containing 10000 entries
      cache size is now 10000
      Recover snapshot snapshot-empty containing 0 entries
      cache size is now 0

------removing snapshots------
      snapshots = []

------BasicSnapshotOperations example completed------

You can inspect the code in src/com/tangosol/examples/persistence directory. The file is the initial class for all persistence examples.

You will also see messages on the run-cache-server terminal indicating that Persistence operations are underway.

Note: Don’t forget to run through the other examples!

Viewing Persistence Using JVisualVM Plugin

Its worth installing the JVisualVM Plugin and take a look at the Persistence tab as well as Caches tab while you are running the examples.  See my post in the new JVisualVM Plugin for 12.2.1 for more information.

This post goes into a bit more depth on the MBeans that are available for working with Persistence through JMX connections.


Persistence is a great new feature and the examples show you how to get started with it and some of the functionality available.

Take a look at the Online Documentation for Persistence and email me let me know if you are interested in a more in-depth guide to Persistence as i have a lab guide that I can share.




This entry was posted in Examples and tagged , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s