Platform Concepts
Clients and Servers
Terracotta clusters JVMs together by injecting cluster-aware bytecode into your Java code at runtime as your classes are loaded by each JVM. This is what makes Terracotta transparent to your application. Part of this cluster-aware bytecode causes your JVM to make a TCP connection to server processes we call "Terracotta server instances." In a cluster, Terracotta server instances exist as a cohesive array.
In keeping with the client/server terminology, we call your application JVMs that are clustered together "Terracotta clients" or "Terracotta cluster nodes."
You can think of your clustered JVMs—the Terracotta clients—as being logically one big JVM with a shared heap. All of the threads in all of the JVMs can communicate with each other and share data with each other through this clustered virtual heap just as if they were all in the same big JVM.
A Terracotta server instance acts as a traffic cop to coordinate the threads in different JVMs together and to handle the storage and retrieval of object data in the shared clustered virtual heap. The server instance stores this heap data on disk so you can treat the data in your clustered virtual heap as durable as if it were in a database.
Distributed Shared Objects (DSO)
Just as you address your heap through references to objects in a single JVM, you address the Terracotta clustered virtual heap through references to clustered objects—which we refer to as "distributed shared objects" or "managed objects"—in the Terracotta cluster. To your code, these objects look just like regular objects—and, in fact, they are just regular objects on the heap of your local JVMs, the Terracotta clients. However, behind the scenes, Terracotta knows to treat clustered objects differently than regular objects.
When you make changes to a clustered object in your code, Terracotta keeps track of those changes and sends them to all Terracotta server instances. Server instances, in turn, makes sure those changes are visible to all the other JVMs in the cluster as necessary. This way, clustered objects are always up-to-date whenever your code accesses them, just as they are in a single JVM.
Not every object in your JVM is a clustered object. Only those objects that you want to be clustered turn into clustered objects. The way this works is by declaring one or more fields to be a "root."
Roots
A root—sometimes referred to as a "clustered root"—is a special concept introduced by Terracotta. It is a core concept that enables Terracotta to "identify" which objects should be clustered, and which should not.
You, the application developer, specify a root in the Terracotta configuration file. A root is what forms the top of a clustered object graph. Typical roots are Collections such as a HashMap or an ArrayList but they can be any POJO.
A root is assigned at runtime during execution of your application code. When a Terracotta root field is assigned for the first time by your application, Terracotta walks the object graph of that root object and turns every object that is reachable by reference from the root object into a clustered object. Thereafter, every object that becomes referenceable by any clustered object itself becomes a clustered object. If you don't want an object that is referenceable by a clustered object to become clustered, you can declare it to be transient, just like in Java serialization.
Configuration
Because Terracotta clusters JVMs transparently with no explicit API, control over what gets clustered and which operations in your application are sensitive to clustering is performed through the Terracotta configuration. The configuration can be specified using an XML file or using code annotations, depending on the style of configuration you like best.
The three main sections of the Terracotta configuration you must specify are roots, locks, and classes to instrument. The root specification lets you declare which fields in your application are to be treated as clustered roots. The locks specification lets you declare which methods in your application are sensitive to clustered locking and clustered object changes. Which classes to instrument is declared using an "include" or "exclude" syntax that lets you determine which classes Terracotta should inject cluster behavior into.
Coordination
The way Terracotta adds capacity to your application is by letting you transparently increase the number of CPUs available to your application by adding more JVMs on more computers as necessary. Just like a single JVM, the way those CPUs are utilized is by spawning threads to do work on those CPUs to parallelize workload. Terracotta lets threads in different JVMs interact with each other as if they were on the same JVM, allowing you to write code as if your application ran on a single JVM, but also allowing you to deploy on as many different computers as you need to meet your availability and capacity requirements.
In a JVM, threads communicate with each other by coordinating activities like serializing access to shared object data on the heap through locking and by signalling to each other that certain events have taken place. To do this, Java gives you the concurrency primitives built into the language, "synchronized," "wait," and "notify." As of Java 1.5, you can also use the rich set of higher-order thread coordination and communication tools found in the java.util.concurrent package.
When using Terracotta, the concurrency primitives "synchronized," "wait," and "notify" as well as the classes built in to the java.util.concurrent package operate across threads in different JVMs the same as across threads in a single JVM. This is what allows threads in many JVMs to interact with each other as if they were all in one same big logical JVM.
Hello Clustered World
See a simple "hello, world!" Java application clustered with a few lines of configuration.