Overview
Terracotta Cache provides an implementation of a distributed cache that mimics the JBoss TreeCacheMBean API - so that users can transparently replace the cache provider implementation from JBoss TreeCache to Terracotta. The order of magnitude improvement in throughput and improved visibility into the clustered data are primary motivations for doing so.
Description
Terracotta Cache itself is a plain Java collection (java.util.TreeMap with the keys implementing a comparator) that is distributed/clustered via Terracotta's core DSO technology. It maintains most of TreeCache APIs (cache.put, get, remove etc.) so that migrating from JBoss TreeCache to this more scalable (orders of magnitude) implementation is typically simply changing 1 line of code to instantiate TerracottaCache() instead of TreeCache().
 |
This currently works on JBoss Cache v.1.4. Due to incompatible API changes, it doesn't currently work on JBoss Cache 2.0. |
Configuration Module
The quickest and easiest way to use the Terracotta Cache is to include the Terracotta Cache Configuration Module in your Terracotta XML configuration. Just download the following jar file: terracotta-cache-cluster-config-1.0.0.jar
and add it in your configuration like this:
<clients>
<logs>%(l1.log.directory)/local/tc_runtime/terracottacache/client-logs</logs>
<modules>
<repository>file:modules</repository>
<module name="autolock-synchronizedcollection" version="1.0.0"/>
<module name="autolock-synchronizedset" version="1.0.0"/>
<module name="autolock-synchronizedsortedset" version="1.0.0"/>
<module name="autolock-synchronizedmap" version="1.0.0"/>
<module name="autolock-synchronizedsortedmap" version="1.0.0"/>
<module name="terracotta-cache-cluster-config" version="1.0.0"/>
</modules>
</clients>
As you might have noticed, Terracotta Cache depends on some external configuration modules and they must be included in the same order as mentioned above. These modules will allow you to run Terracotta Cache in a thread-safe mode if you may choose to do so (to enable fine-grained locking and least amount of refactoring required). The above mentioned configuration modules can be downloaded from here: http://www.terracotta.org/confluence/display/integrations/SynchronizedCollection
(look under "External Config Modules" in the left pane).
| Module Location
Make sure that the modules are located in the correct location. The location of the modules is specified in the <repository> element. The easiest way is to copy all the module jars in the TC_INSTALL_DIR/modules directory and you do not need to specify the <repostory> element. If you chose to keep the modules in a custom location, you should specify the correct location in the <repository> element. E.g. The above example assumes the modules to be in the modules sub-directory under the current directory. |
| Module name
Note that there ia a correlation between the module jar file-name and the module element in the configuration. The jar file-name follows the pattern modulename-version. |
Here is further documentation on configuration modules: Configuration Modules
Once you have included the configuration modules in your Terracotta Configuration, you will need to rebuild the boot-jar as mentioned in the following link: How to create boot jar
Code Samples
There is a sample test implementation that is included under the test package as Server.java which can browsed to through the SVN link posted below or can be checked out via SVN.
Public Source Repository
SVN: http://svn.terracotta.org/svn/forge/projects/labs/terracotta-cache
Fisheye: http://svn.terracotta.org/fisheye/browse/TerracottaForgeLabs/terracotta-cache
Private Source Repository (for committers)
SVN: https://svn.terracotta.org/repo/forge/projects/labs/terracotta-cache
Implementation Details
TODO
Javadocs and other Documentation in the works.
