Terracotta OSS dev starter

The Terracotta Server Array (TSA) provides the platform for Terracotta products and the backbone for Terracotta clusters.
It allows, for instance, to use Ehcache in a clustered mode, and benefit of a distributed in-memory cache.

It is available as open source, and you may want to contribute to it, or even just build it yourself (You can also get binaries on the Terracotta web site).

If you want to contribute to the OSS Terracotta server, here are a few pointers to get you started.

Terracotta server kit

The Terracotta OS server is bundled with Ehcache OS, Quartz OS and Sessions.
This takes form of a tarball that we refer to as a kit.
It requires java 1.6 or higher.
The sourcecode is available as a multi-module Maven project. Modules corresponds to various components that are integrated during the build to create the Terracotta server.

Building a kit is straightforward.

1) Get the sourcecode

svn co https://svn.terracotta.org/svn/tc/dso/trunk/

2) Compile

export MAVEN_OPTS="-Xmx1G -XX:MaxPermSize=512m"
mvn clean install -Pfullmode -Dcheckstyle.skip=true

3) Or Build

mvn clean install -Pfoss-kit -Dcheckstyle.skip=true

The build process will compile the Terracotta server source code, it will also obtain the Ehcache, Quartz and Sessions jars from the maven central repository and will bundle everything as a tarball under the “terracotta-kit/target/” directory.

Running the tests

Please note that the tests are disabled by default. To run tests you will need to do:

mvn -Pcheck-short verify

Start/stop the server

In the final kit, some start/stop scripts are included, but when developing you can start/stop the Terracotta server using Maven or from your IDE

1) Using Maven

cd deploy
mvn exec:exec -P start-server
mvn exec:exec -P stop-server

2) From your IDE
Execute the class


providing the arguments if needed:

-f filename : to specify a custom Terracotta server configuration file (tc-config.xml)
-n servername : to specify a Terraocotta server name
and of course the java options (e.g. -XX:MaxDirectMemorySize for Offheap, and -Xmx for heap)

Server architecture

The Terracotta server follows a SEDA architecture, which decomposes tasks into a set of stages connected by queues, rather than using large concurrent tasks.

The name ‘server’ comes from the fact that the whole Terracotta architecture uses a client-server topology : The two main components are the L1(client) and the L2 (server).

The Toolkit is an abstraction layer providing a public API to the L1 component. The Toolkit is also used by Ehcache and other Terracotta libraries to connect to the Terracotta Server (L2) to become clustered.

It must be noted that server instances also communicate between themselves (e.g Active replicating data to Passive), so there is some L2L2 communication as well.

Transactions on the L1 side, are handled by the transaction manager, to build a message that will be transmitted through the communication layer. Once the transaction is committed the message reaches the remote transaction manager on the L2 side.

Stages are created once the messages reach the L2 and it goes into the Message transactions stage, from there it gets passed to the lookup stage where it looks for the cache to be used. Next it goes to the apply stage, to apply the changes, followed by the broadcast stage, to broadcast information back.

Finally it comes to the L1 and a couple of stages take place, to acknowledge that the transactions have been applied, and apply resulting changes on the L1 side.

Stages can be configured in term of threads number (wider) and batches sizes (longer), in order to maximize the performance.

The classes com.tc.objectserver.impl.DistributedObjectServer and com.tc.object.DistributedObjectClient are the entry points for the L2 and L1.

They wire and start every parts of the components, no logic passes through it. They’re useful if you need to find what classes belong to the component you want to change.

Therefore, when doing changes, you can concentrate on the flow you want to work on, and the appropriates objects.

Project modules organization

When looking at the code obtained from the scm, we see a number of directories.

build-data and build-parent are used to build the kit.

checkstyle and checkstyle-toolkit are used to run a checkstyle verification

common contains classes that are common to the L1 and L2.

deploy has the definition to execute the l2 from maven, when developing (cf point before)

devwork is where you put the source of other projects, such as ehcache

dso* modules contain the code handling the stages

management contain the code for the JMX support that allow to get information about the Terracotta server.

management-agent provides similar information but using a REST agent and is now preferred to JMX
Terracotta* modules defines the assembly of the components of the Terracotta server

toolkit* modules are containing the toolkit code


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s