Terracotta is a transparent clustering service that allows multiple Java processes on different JVMs to work together using pure objects and threading logic. Here’s how you can use it with Equinox.
Prerequisites: An installation of Java 1.6.0u20 or later (Java SE Downloads) and Terracotta (Open Source Option) Terracotta Download..
Install the downloaded Terracotta:
> tar xvfz terracotta-3.3.0.tar.gz
> export TC_HOME=/opt/tools/terracotta-3.3.0
We wan’t Terracotta to integrate with Equinox. This is where Terracotta Integration Modules come into play:
Terracotta Integration Modules (TIMs) are sets of configuration elements and supporting Java classes packaged together as a single, includable module within the Terracotta configuration. A TIM allows you to integrate Terracotta DSO with the framework or platform that your application is based on.[1]
Let’s look how to include the TIM for Equinox 3.5.1 in the Terracotta configuration file $TC_CONFIG_HOME/tc-config.xml:
We create our own tc-config.xml in $TC_CONFIG_HOME based on a Terracotta sample configuration $TC_HOME/platform/samples/tc-config.xml. Add this snippet to the basic sample config:
Use the Terracotta helper tim-get.sh to install the TIM locally…
> $TC_HOME/bin/tim-get.sh install tim-equinox-3.5.1 1.2.0
Terracotta 3.3.0, as of 20100716-150712 (Revision 15922 by cruise@su10mo5 from 3.3)
Installing tim-equinox-3.5.1 1.2.0...
INSTALLED: tim-equinox-3.5.1 1.2.0 - Ok
Done. (Make sure to update your tc-config.xml with the new/updated version if necessary)
Now that we’ve configured the Equinox integration it’s time to tell Terracotta about our counter, a POJO:
public class Counter {
private AtomicInteger counter;
public int inc() {
return counter.incrementAndGet();
}
public int getCurrentCounter() {
return counter.intValue();
}
}Our Terracotta ‘application’ configuration holds the simple root object (graph) : A “root” is the top of a clustered object graph as declared in the Terracotta configuration.[2]
com.eclipsesource.sovereign.terracotta.counter..*
com.eclipsesource.sovereign.terracotta.counter.Counter.counterLast we need a so called Terracotta “boot JAR”:
Some classes, however, are loaded too early in the lifecycle of the JVM for Terracotta to hook into their loading process. These are classes that are loaded by the boot classloader. Such classes cannot be instrumented at classload time, but must be pre-instrumented and placed in a special JAR file that is then prepended to the boot classpath.[2]
This is done with a Non-Standard Option of the JVM [3]
-Xbootclasspath/p:${TC_CONFIG_HOME}/boot JAR.jar> $TC_HOME/platform/bin/make-boot-jar.sh -f $TC_CONFIG_HOME/tc-config.xml
2010-09-09 15:11:15,446 INFO - Terracotta 3.3.0, as ...
...
2010-09-09 15:11:27,456 INFO - Successfully created boot JAR file at ...
> cp $TC_HOME/lib/dso-boot/dso-boot*jar $TC_CONFIG_HOME
Enough installation and configuration. Engage! We need a running Terracotta server instance.
Terracotta server instances together form a Terracotta server array, which is the heart of a Terracotta cluster. Each Terracotta server instance performs two basic functions:[2]
- Cluster-wide thread coordination and lock management
- Clustered object data management and storage
> $TC_HOME/bin/start-tc-server.sh -f $TC_CONFIG_HOME/tc-config.xml
2010-09-09 15:34:42,370 INFO - Terracotta 3.3.0, as of ...
2010-09-09 15:34:55,915 INFO - Terracotta Server instance has started up... successfully, and is now ready for work.
What’s a server without a client? We fire up the Equinox client with Pax Runner with some additional JAVA_OPTS:
> export JAVA_OPTS=-Dtc.install-root=${TC_HOME} -Dtc.config=${TC_CONFIG_HOME}/tc-config.xml -Xbootclasspath/p:${TC_CONFIG_HOME}/dso-boot-hotspot_linux_160_21.jarOne configuration file contains our counter OSGi bundle etc/counter-demo.pax:
mvn:com.eclipsesource.sovereign/terracotta.counter/0.1.0-SNAPSHOT
The second specifies platform, version, inProcess executor, bootDelegation, …
--platform=equinox
--version=3.5.1
--executor=inProcess
--bootDelegation=sun.*,com.sun.*,javax.xml.*,javax.xml.transform.*,...
--systemPackages=javax.naming, javax.naming.directory, javax.naming.spi, ...
>$PAX_RUNNER_HOME/bin/pax-run.sh etc/counter-demo.pax --args=file:etc/runner.args
2010-09-09 17:14:23,435 INFO - Terracotta 3.3.0, as of 20100716-150712 (Revision 15922 by cruise@su10mo5 from 3.3)
2010-09-09 17:14:24,794 INFO - Successfully loaded base configuration from file at...
2010-09-09 17:14:30,101 INFO - Connection successfully established to server at ...
__________ __________
\______ \_____ ___ ___ \______ \__ __ ____ ____ ___________
| ___/\__ \ \ \/ / | _/ | \/ \ / \_/ __ \_ __ \
| | / __ \_> < | | \ | / | \ | \ ___/| | \/
|____| (____ /__/\_ \ |____|_ /____/|___| /___| /\___ >__|
\/ \/ \/ \/ \/ \/
Pax Runner (1.4.0) from OPS4J - http://www.ops4j.org
----------------------------------------------------
...Review the first lines showing that the Terracotta client successfully estalished it’s connection to the server. If those lines are missing please double check the path to your “boot JAR”.
We added some OSGi commands to interact with our clustered POJO counter:
osgi> help
...
---Sovereign counter commands---
inc - increment the global counter
currentValue - show current counter value
osgi> inc
4
osgi> currentValue
4
Start another application and have fun with the clustered counter….
Sources:
[1] Terracotta Integration Modules Manual
[2] Concept and Architecture Guide
[3] Java SE Documentation – Java – the Java application launcher
Tags: equinox, terracotta
). Luckily we live in a modular world in Eclipse. As a result, I was able to develop a separate bundle called the “OSGi Eliminator” (what a descriptive name 
). The bundle contributes the functionality to automatically terminate a running OSGi Instance when you try to launch the same instance a second time. This functionality already existed in the RAP launcher created by Rüdiger Hermann. All I did was to refactor the functionality out to make it run in a separate bundle and contribute to the OSGi Launcher instead of the RAP Launcher. This solves an annoying problem for me – maybe for you as well?
