Distributed Cache Tutorial

Download and Install the Terracotta Enterprise Suite

Use the links below to download the Terracotta Enterprise Suite and a 30-day trial license. Run the installer and tell it where to unpack the distribution. We'll refer to this location as ``. In the following instructions, where forward slashes ("/") are given in directory paths, substitute back slashes ("\") for Microsoft Windows installations.

Download

Enterprise Ehcache (including BigMemory, Ehcache Search and the Hibernate distributed cache plugin), Web Sessions, Quartz Scheduler and the Terracotta Server Array all come bundled with the Terracotta Enterprise Suite.

Important: Make sure to download the trial license key in addition to the software bundle.

Download the Terracotta Enterprise Suite ›

Install

Run the installer (your installer version may vary):

%> java -jar terracotta-ee-3.5.2-installer.jar

Copy the license key to the terracotta distribution directory:

%> cp terracotta-license.key /

Start the Distributed Cache Sample

We'll use the "colorcache" sample in the ehcache samples directory of the Terracotta distribution to demo the distributed cache.

Start the Terracotta Server

%> cd <terracotta>/ehcache/samples/colorcache
%> bin/start-sample-server.sh

Start the Sample

%> bin/start-sample.sh

View the Sample

The distributed cache sample starts up two instances of Jetty, each connected to the Terracotta server for access to the distributed cache.

The sample application uses Ehcache to cache color data that it retrieves from a (simulated) database call. It uses the Terracotta distributed Ehcache plugin to make the cache distributed so the cached data is shared across all instances of the application:

Once the Jetty instances have started, you can view the sample application by visiting the following links:

http://localhost:9081/colorcache ›
http://localhost:9082/colorcache ›

Note: these links will not work unless you have the sample running.

After Jetty loads the sample application, it should look something like this in your browser:

Load a Color

Now, load a color by entering a color name into the text field. Start by entering "red." The application with then load the color data for "red" (255, 0, 0).

When a color is first loaded, the application simulates the execution of a slow operation such as loading data from a database or executing a computationally intensive operation. It will then place the color object into Ehcache. Subsequent calls to load that color will be read from the cache, thereby executing much more quickly.

Try clicking the "Retrieve Color" button again to see the application load from cache.

View the Distributed Cached Data in Other JVMs

To see the distributed cache work in the other application server, click on the link in the hint box.

When the page on the other application server loads, the color data for "red" loads from cache, even though the cache was loaded on the first application server:

Try loading a few more colors into the cache. You can see the cached colors in the box on the right. Clicking on a color swatch in that box will load the color data from the cache into the main display.

You'll see those colors loaded quickly as they are loaded from the cache:

Click on the link in the hint box to switch back and forth between the two application servers:

You'll notice that the state of the cache is always in sync in both application servers, no matter which one loads the cache.

Also, notice that, if you don't load a cached color within 120 seconds of placing it in the cache, it will expire from the cache.

The cache eviction policy is configurable on a per-cache basis and evicted elements are automatically evicted across the entire cluster coherently so you will never get cache drift.

View Runtime Cache Statistics and Manage Configuration

Terracotta comes with a console that lets you inspect and dynamically change the runtime contents, statistics, and configuration of the distributed cache. To see it in action, start the console:

%> <terracotta>/bin/dev-console.sh

When the console starts, you will see a splash screen prompting you to connect to the Terracotta server. The Terracotta server coordinates all of the statistics gathering and configuration management of the cache cluster.

Click the "Connect..." button to connect the console to the cluster.

Once connected, open the Ehcache statistics and configuration panel by clicking on Ehcache in the tree-control menu:

Click reload on your browser a few times and you will see the meter in the console register a green bar indicating cache hits. The red bar indicates cache misses and the blue bar indicates cache puts:

Click on the "Statistics" tab in the console to see the runtime statistics graphs:

Click on the "Configuration" tab in the console to view and manage the cache configuration:

Try changing the "time to idle" parameter on the cache to 10 seconds to see the configuration change in real time:

You can see the effect of the configuration change by loading colors into the cache. If you view them again before the new 10 second idle threshold, they will be loaded from cache. After 10 seconds of idleness, they will be evicted from the cache. If you view the other application server, you'll see the cache entries have been evicted uniformly from all instances of the cache.