Lets start with some general information about Toolkit. Refer Toolkit javadoc for more details here

Pre-requisite

You can spend some time reading the following posts on Toolkit, although they can be read in any order

• Getting Started with Terracotta Toolkit – Part 1
• Getting Started with Terracotta Toolkit – Part 2 (Cluster Events)

Lets explore a bit what do we achieve when we say Clustered Map

Unclustered Map

As you can see in the figure above, we have different JVM's, each having a Map instance used by Application. Now if we were to share the same instance across app's running in different nodes, we would have to write a lot of infrastructure code to replicate data, keep data coherent etc.

Clustered Map

The figure above depicts a Clustered Map. The Map instance is visible to App's across JVM's as if they are accessing a local instance. You can achieve this in a few lines, without worrying about the infrastructure code. Lets see how we can achieve this in few simple steps.

Steps to creare Clustered Map

Initializing the Toolkit

Before any operations can be performed using Toolkit, it needs to be initialized first. The initialization code is very simple, just single line

ClusteringToolkit clustering = new TerracottaClient("localhost:9510").getToolkit();

This line initializes the Terracotta Client and gets an instance of Toolkit to work with. The argument passed to the TerracottaClient is the IP Address and Port of the Terracotta Server.

Have created a simple function for initialization of the Toolkit.

ClusteringToolkit clusterToolkit = null;

public void initializeToolKit(String serverAdd) {
clusterToolkit = new TerracottaClient(serverAdd).getToolkit();
}

Get/Create the Map

public void initializeMap() {
    clusteredMap = clusterToolkit.getMap(MAP_NAME);
}

The code above creates a Clustered Map. There is no more infrastructure code that you have to write. This gives us a Clustered Map reference. The best part is, there are no new API's to be learned, we continue to use the same old Map API's.

Let's see the data class that we would share across the Map.

public class SharedData implements Serializable {

    private String data;

    public SharedData(String data) {
        this.data = data;
    }

    public String getData() {
        return data;
    }

    public void setData(String data) {
        this.data = data;
    }
}

Its a no-brainer class. Just a simple class for demonstration purpose.

Just to keep life simple, we are going to create a function which populates the Map, and the Nodes can then consume the populated data. Consume here would mean just call a get() and print. In real life scenario, you can mutate the data, and the updated data shall be visible across the cluster.

Lets see the populate function

protected void populateMap(int objectCount) {
        for(int i = 0; i < objectCount; i++) {
            SharedData data = new SharedData(""+i);
            clusteredMap.put(i, data);
        }
    }

Its a simple function which just puts the data in the Map.

Lets look at the consume function

 protected void consumeMapData(int maxObjectId) {
        Range range = new Range(1, maxObjectId);
        while(true) {
            long key = range.getRandomKey();
            byte[] dataBytes = clusteredMap.get((int)key);
            System.out.println("Key = "+key);
            if(dataBytes == null) {
                System.out.println("OOPS!.. somethings wrong dude...");
                return;
            }
            SharedData data = (SharedData)deserializeObject(dataBytes);
            if(data != null) {
                System.out.println("Data = "+data.getData());
            }
            try {
                // Sleep for 5 secs
                Thread.sleep(5000);
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
        }
    }

The function just takes a random key and call a get on the map.

To run this implementation, we would have 3 Nodes running, 1 producer and 2 consumer. The picture below gives an idea of the topology.

Runtime Topology

To run the implementation

You can get the complete source of the sample here

Cluster Events

As of 3.3.0, following are the four Events that are available

• Node Joined
• Node Left
• Operations Enabled
• Operations Disabled

So what do we need to do, in order to receive these events? Just two simple steps

• Implement ClusterListener
• Register the Listener with toolkit

Pre-requisite

Implementing ClusterListener

Here is the code

class MyClusterListener implements ClusterListener {

        public void nodeJoined(ClusterEvent clusterEvent) {
            try {
                System.out.println("Event Type = "+clusterEvent.getType());
                System.out.println("Node Joined "+clusterEvent.getNode().getId()
                        + ", IP="+clusterEvent.getNode().getAddress());
            } catch (UnknownHostException e) {
                e.printStackTrace();
            }
        }

        public void nodeLeft(ClusterEvent clusterEvent) {
            try {
                System.out.println("Node Left "+clusterEvent.getNode().getId()
                        + ", IP="+clusterEvent.getNode().getAddress());
            } catch (UnknownHostException e) {
                e.printStackTrace();
            }
        }

        public void operationsEnabled(ClusterEvent clusterEvent) {
            System.out.println("Operations Enabled");
        }

        public void operationsDisabled(ClusterEvent clusterEvent) {
            System.out.println("Operations Disabled");
        }
    }

As you can see, the implementation is pretty simple. Now its time to register the listener

ClusterInfo clusterInfo = clusterToolkit.getClusterInfo();
clusterInfo.addClusterListener(new MyClusterListener());

Get the complete code here

Time to see the implementation in Action

• Start Terracotta Server
• Start the Listener
• Start/Stop Terracotta Clients and see the events being received

There can be some innovative things that can be done inside the ClusterListener. For ex, you can send SNMP Traps to your management system for nodeJoined or nodeLeft events.

Stay tuned for more on Terracotta Toolkit...

Looking for more details, you find them here

So you want Distributed, Scalable and Highly Available Cache? If yes, then this is the right place for you. The Terracotta Ehcache release has these features inbuilt. The Express Installation mode has simplified Terracotta integration in your application.

How this post is organized
First we shall start with simple standalone cache and then see how Terracotta can easily help us create a Distributed, Scalable and Highly Available cache, with a few minor configurations

What all do you need run the example?

• Terracotta 3.2.0 - Download it from here

Sample Application
Lets design a sample application (a real simple one), which we shall use to demonstrate the features. Device Monitoring is a common requirement in OSS System, and caching the Device information reduces the Database hits. The essential components of our application are
- DevideInfo - A POJO that stores device information
- CacheHandler - Class that handles cache initialization and other ops

Lets see the CacheHandler class, which is the heart of our implementation

public class DeviceInfo  implements Serializable {

    String deviceId;

    String name;

    // .... other device information

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getDeviceId() {
        return deviceId;
    }

    public void setDeviceId(String deviceId) {
        this.deviceId = deviceId;
    }
}

The class is simple and contains information related to the device.

Let see our CacheHandler class

public class CacheHandler {

    public Cache deviceCache;

    public void initCache() {
        // Initialize the CacheManager
        CacheManager cacheManager = CacheManager.create();
        // Get the Cache to store device information
        deviceCache = cacheManager.getCache("deviceCache");
    }

    public void addToCache(DeviceInfo device) {
        Element el = new Element(device.getDeviceId(), device);
        deviceCache.put(el);
    }

    protected int getDeviceCacheSize() {
        return deviceCache.getSize();
    }

    public static void main(String[] args) {
        CacheHandler handler = new CacheHandler();
        handler.initCache();

        // Lets add 10 devices
        // just to keep life simple
        for(int i = 0; i < 10; i++) {
            DeviceInfo device = new DeviceInfo();
            device.setDeviceId("Device-"+i);
            handler.addToCache(device);
        }

        // Not recommended in production
        System.out.println("Cache Size = "+handler.getDeviceCacheSize());

    }
}

The class has two main functions
- initCache - The API initializes the cache
- addToCache - The API adds the device information to the device cache

Lets see our ehcache.xml

<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="ehcache.xsd"
             updateCheck="true" monitoring="autodetect">

   <defaultCache
            maxElementsInMemory="10000"
            eternal="false"
            timeToIdleSeconds="120"
            timeToLiveSeconds="120"
            overflowToDisk="true"
            diskSpoolBufferSizeMB="30"
            maxElementsOnDisk="10000000"
            diskPersistent="false"
            diskExpiryThreadIntervalSeconds="120"
            memoryStoreEvictionPolicy="LRU"
            />

    <cache name="deviceCache"
           maxElementsInMemory="1000000"
           maxElementsOnDisk="1000"
           eternal="false"
           overflowToDisk="false"
           diskSpoolBufferSizeMB="20"
           timeToIdleSeconds="100"
           timeToLiveSeconds="100"
           memoryStoreEvictionPolicy="LFU">
     </cache>

</ehcache>

In the configuration we have defined a deviceCache, that we shall use to store device information.

Following is the list of jars you would need to run this app

• ehcache-core-1.7.2.jar
• slf4j-api-1.5.8.jar
• slf4j-jdk14-1.5.8.jar

All these jars are available as part of Terracotta installation under /distributed-cache directory

You can run this example and see the same in action.

Making it Distributed....

Now lets assume that we want to make the Cache fault tolerant, survive JVM crashes, as well as have it available on different JVM's. It should be able to Scale as we add more JVM's to it and other stuff. With Terracotta, we can just do it in a few steps without changing the code. the magic lies with Express Installation mode, introduced in Terracotta version 3.2.0 and above

Lets see the 3 steps that we need to perform

1. Updates to the ehcache.xml
Add following element to ehcache.xml

<terracottaConfig url="localhost:9510" />

and for the deviceCache, we add <terracotta /> element

here is the updated ehcache.xml

<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="ehcache.xsd"
             updateCheck="true" monitoring="autodetect">

   <terracottaConfig url="localhost:9510" /> 

   <defaultCache
            maxElementsInMemory="10000"
            eternal="false"
            timeToIdleSeconds="120"
            timeToLiveSeconds="120"
            overflowToDisk="true"
            diskSpoolBufferSizeMB="30"
            maxElementsOnDisk="10000000"
            diskPersistent="false"
            diskExpiryThreadIntervalSeconds="120"
            memoryStoreEvictionPolicy="LRU"
            />

    <cache name="deviceCache"
           maxElementsInMemory="1000000"
           maxElementsOnDisk="1000"
           eternal="false"
           timeToIdleSeconds="100"
           timeToLiveSeconds="100"
           memoryStoreEvictionPolicy="LFU">

        <terracotta />
     </cache>

</ehcache>

There is no need to change the code

2. Add ehcache-terracotta-1.8.0.jar to the classpath

Lets start the Terracotta Server

3. Goto Terracotta_Install_dir/bin and execute

$ ./start-tc-server.sh

This shall start the Terracotta server

Now run the application on multiple JVM's. The device information is available on all client JVM's

To monitor Cache, you can use Terracotta Dev Console

If you have further question/queries, please visit Terracotta Forums.

What's coming up Next?
The next post shall touch on write-behind feature in the latest Terracotta Darwin release. Its essentially to get best of both worlds - Caching and Database Offloading Stay tuned..

In this small post we shall explore Terracotta, a leading pure Java Scalability platform. The discussion is based on the AtomicInteger example from Terracotta site, which shows how to implement a Cluster wide id generator (Actually it’s the Sequencer example, but to keep my steps simple had used AtomicInteger). The reason why I choose this example was coz of a very similar requirement that I had to implement in Clustered J2EE application.
Terracotta is well known and needs no introduction

About problem Statement

Well, I needed a simple solution to have
• Cluster wide unique id’s
• Less frequent access to these id’s
• Optional Persistence

NOTE: Please note that the current example is slightly modified version of example from terracotta.org.

Pre-requisite

To run this example, you need to have following installed
• Terracotta
• And JDK offcourse
Let’s take a look at the sample code first

import java.util.concurrent.atomic.*;

public class IdGenerator
{

private AtomicInteger masterCounter = new AtomicInteger(0);

private AtomicInteger slaveCounter = new AtomicInteger(1024);

public int getNewMasterId()
{
int newId = masterCounter.getAndIncrement();
System.out.println("Master Id is: " + newId);
return newId;
}

public int getNewSlaveId()
{
int slaveId = slaveCounter.getAndIncrement();
System.out.println("Slave Id is: " + slaveId);
return slaveId;
}

public static void main(String[] args)
{
new IdGenerator().getNewMasterId();
}
}

The code has two fields ids master and slave, of which master id need to be unique cluster wide. The code is pretty straight forward, and there is nothing to explain. The id’s are generated by simple getAndIncrement() API.

Lets see the tc-config.xml

<tc:tc-config xmlns:tc="http://www.terracotta.org/config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.terracotta.org/schema/terracotta-4.xsd">

<application>
<dso>
<roots>
<root>
<field-name>IdGenerator.masterCounter</field-name>
</root>
</roots>
</dso>
</application>
</tc:tc-config>

Since only master Id needed to be unique in this case, hence the configuration

Let’s look at the deployment architecture

Deployment Architecture

The application was to run on 3 nodes (3 JVM’s on same machine) and one Terracotta server running.
Before we get into running this application, lets take a look at some useful scripts provided by Terracotta
• dso-java (bat|sh) – startup script that bootstraps Terracotta libraries to your application
• start-tc-server (bat|sh) – Script to start Terracotta Server. It is mandatory to start Terracotta Server before running Clients

Let’s run the application
1. Compile the application. There is no dependency on TC libraries.
2. First Start the terracotta Server using script start-tc-server
3. Run 3 separate JVM with command “dso-java IdGenerator”
That’s it. Our first application is running. If we observe the console output, you can see that we have unique id’s for each invocation.

References:

Source code for Terracotta examples - http://svn.terracotta.org/svn/forge/cookbook