1. The Java File

The first thing we need for Hello Clustered World is a simple program. The following program instantiates a Main class with an int counter. It increments the counter, and prints the value.

public class HelloClusteredWorld
{
    private static int counter;

    public static void main(String[] args) 
    {
        counter++;
        System.out.println("Counter is: " + counter);
    }
}

Unlike a typical Hello World which has no state - we need a program with state. Otherwise, there isn't anything interesting to cluster. The key to clustering is maintaining shared state. So our HelloClusteredWorld uses an int counter for state.

2. Compile

Use javac to compile the program:

%> javac HelloClusteredWorld.java

3. Run Standalone

Before adding Terracotta, get a feel for how the program runs as a standalone Java process:

%> java HelloClusteredWorld
Counter is: 1

If you run the program again, the counter output will remain 1, since each execution of a standalone Java process starts with fresh, reset memory values:

%> java HelloClusteredWorld
Counter is: 1

4. Configure

To cluster a simple application such as HelloClusteredWorld we need only mark the clustered state. Terracotta introduces the notion of a root, which is the "container" of the clustered state. A root can be any member field of any class.

In HelloClusteredWorld, the clustered state is the counter, so we mark the counter field as a root:

<tc:tc-config xmlns:tc="http://www.terracotta.org/config">
  <application>
    <dso>
      <roots>

        <root>
          <field-name>HelloClusteredWorld.counter</field-name>
        </root>
      </roots>
    </dso>

  </application>
</tc:tc-config>

5. Start a Terracotta Server Array

One requirement for all Terracotta applications is that there must be a running Terracotta Server Array. The Terracotta Server Array manages cluster coherence and persistent state.

The Terracotta Server Array itself is clusterable to deliver the scale and availability as your application demands, however, for demonstration purposes, we will start just one server instance. We do this by running the start-tc-server script included in the bin directory of Terracotta:

%> start-tc-server.sh

2008-10-28 22:59:20,355 INFO - Terracotta Enterprise Edition 2.7.0, as of 20080925-140911 (Revision 2417-10251 by cruise@rh4mo0 from 2.7)
2008-10-28 22:59:21,085 INFO - Configuration loaded from the Java resource at '/com/tc/config/schema/setup/default-config.xml', 
                               relative to class com.tc.config.schema.setup.StandardXMLFileConfigurationCreator....
2008-10-28 22:59:26,853 INFO - JMX Server started. Available at URL[service:jmx:jmxmp://0.0.0.0:9520]
2008-10-28 22:59:27,993 INFO - Terracotta Server has started up as ACTIVE node
on 0.0.0.0:9510 successfully, and is now ready for work.

When we see the line "Terracotta Server has started up...", our clustered application is ready to run.

6. Start the HelloClusteredWorld Program as a Terracotta Client JVM

To start a clustered application, start Java with Terracotta wired in. A simple script, dso-java, is included in the Terracotta bin directory.

Dso-java is a plain wrapper for Java that configures your JVM to run with Terracotta. It accepts the same parameters as the java command line:

%> dso-java HelloClusteredWorld
Counter: 1

At first glance, the output of HelloClusteredWorld clustered is no different from the standalone pass. But wait! Terracotta has provided us with a persistent clustered heap. So what happens if we start another clustered instance? Let's find out...

%> dso-java HelloClusteredWorld
Counter: 2

As we can see, on this second run, our state has been preserved! Let's see what happened when Terracotta was added to our HelloClusteredWorld application.

During the first pass, the clustered state was initialized to 0, and stored persistently in the Terracotta Server Array (and to disk). When the state was modified (counter++) the Terracotta Server Array automatically persisted the updated state. Hence, upon exit of the first pass, the Terracotta Server Array held the persistent state—the counter field—with a value of 1.

Then, in the second pass, the persistent state—the counter field—was automatically loaded into the second JVM. The application modified this state (counter++) and the new value—2—was printed to the console