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 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 184.108.40.206.1 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)
Or for *NIX / Mac (using bash)
Note: You don’t need to set JAVA_HOME on Mac.
Next run the following to check you have everything setup correctly:
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:
- Basic snapshot operations – shows how to issue Persistence Operations from Java
- Display Persistence notifications – shows how to use JMX Notifications to subscribe and display Persistence operations
- Running Persistence operations in parallel
- 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)
Next, start one or more cache servers using in separate terminals using:
Next, in a separate terminal run the persistence example using:
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]
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
snapshots = 
------BasicSnapshotOperations example completed------
You can inspect the code in src/com/tangosol/examples/persistence directory. The Driver.java 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.