Terracotta support

The retepMicroKernel provides native support for clustering using Terracotta.

Setting up Terracotta

For a microkernel application to use terracotta you must have Terracotta installed on your local machine.

Unlike normal terracotta applications which use the dso-java wrapper, the microkernel handles the configuration of the jvm internally. The only thing it does not do (currently) is to create the bootloader, so you must do the following at least once (and whenever you update terracotta):

 $ cd terrocottaInstallDir
 $ ./bin/make-boot-jar.sh

Running a clustered application

Configuration

With terracotta you provide a tc-config.xml file defining the parameters of what objects are to be instrumented, clustered roots etc. If the TC_CONFIG_PATH environment variable is not set, the kernel will look under the etc directory for a file called appName.tc-config.xml and if that is not found it will look for tc-config.xml

Executing the application

For the kernel to detect the presence of Terracotta, you must ensure that the TC_INSTALL_DIR environment variable is defined with the local installation directory of Terracorra prior to running the application.

This can be done in one of four ways:

1. export TC_INSTALL_DIR=terracotta/home/directory
2. TC_INSTALL_DIR=terracotta/home/directory path/myapp
3. provide the -XKtc:installDir command line argument, eg myapp -XKtc:installDir=/usr/local/terracotta-3.1.0/
4. provide the -XKtc:installDir argument in the applications myapp.config file

The first method would mean that every kernel application run within that shell session would be clustered. The second method works with bash and means that only that invocation of the application would be clustered. The third method works for that one instance. The fourth method works for any invocation of the command.

In either case the application will then look for the tc-config.xml file within the application's etc directory and if that file exists it will run the dso-env.sh script within the Terracotta installation prior to launching the kernel binary. From that moment the application is running within the Terracotta clustered environment.

Common problems

If the kernel fails with something like:

 Error occurred during initialization of VM
 java.lang.NoClassDefFoundError: java/lang/ClassLoader$5

at java.lang.ClassLoader.loadLibrary0(ClassLoader.java:1816) at java.lang.ClassLoader.loadLibrary(ClassLoader.java:1782) at java.lang.Runtime.loadLibrary0(Runtime.java:823) at java.lang.System.loadLibrary(System.java:1028) at java.lang.System.initializeSystemClass(System.java:1086) remove all jars in your Terracotta lib/dso-boot directory and run the make-boot-jar tool to recreate it.

I usually see this if I've copied terracotta over from one platform (say OSX) to another (Linux).