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/
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)
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