How It's Implemented

The Clustered Ehcache module provides a fragment of Terracotta configuration to instrument certain classes under the net.sf.ehcache package. Additionally, relevant Ehcache internals have been re-implemented to benefit from Terracotta-specific features and optimizations such as:

• fine-grained read and write locks
• an optimized eviction policy
• increased scalability, and
• cluster-wide cache coherency

For these to be activated, you don't have to do anything. They are automatically plugged in and effortlessly replace the original code when the Clustered Ehcache module is activated.

Differences with Ehcache Clustering

Due to some overlap between the features of Ehcache and Terracotta, a number of standard Ehcache behaviors are not directly supported.

These are:

TIM Update Center

Most TIMs can be installed through the TIM Update Center, which provides the simplest way to work with TIMs. The TIM Update Center validates TIM versions to ensure that the correct one is available for your installation. It also provides guidance on configuring Terracotta to use the TIM. See the TIM Update Center documentation for more information on the tim-get tool, which is used to access the TIM Update Center.

Note: You must have Terracotta installed to use tim-get.

The tim-ehcache project contains the following TIMs.

• tim-ehcache-1.3
• tim-ehcache-1.4.1

The instructions below show how to install and use tim-ehcache-1.3. To install and use one of the other TIMs included in this project, simply substitute the name of the TIM you would like to use.

   $ $TERRACOTTA_HOME/bin/tim-get.sh install tim-ehcache-1.3

   > %TERRRACOTTA_HOME%\bin\tim-get.bat install tim-ehcache-1.3

Terracotta Configuration

To use tim-ehcache you must add a module declaration to the Terracotta configuration file, tc-config.xml. You can simply copy and paste one of the following module declarations into your tc-config.xml file. (Note that you should include only one of the ehcache modules, and that it is not necessary to include tim-ehcache-commons.)

<clients>
  <modules>
      <module name="tim-ehcache-1.3" version="1.3.2"/>
      <module name="tim-ehcache-1.4.1" version="1.3.2"/>
    </modules>
</clients>

Using tim-ehcache with a Terracotta Client Application

Client apps will need to declare a CacheManager field, and mark it as root So in your code, if you have the following field declared:

package foo.bar.baz;
import net.sf.ehcache.CacheManager;

public class FooBar {
   protected CacheManager manager = new CacheManager();
}

You will also need to have the following entry in your configuration file:

<roots>
   <root>
      <field-name>foo.bar.baz.FooBar.manager</field-name>
   </root>
</roots>

If the client app uses the singleton methods CacheManager.getInstance() or CacheManager.create() to instantiate a CacheManager then there is no need to declare the field foo.bar.baz.FooBar.manager a root, the integration module already does that for you.

You will also need to download jsr107cache-1.0.jar and add it to your classpath before running your client application. You can obtain this jar either from the project download area or by including it in your Maven pom.xml dependencies as follows:

<dependencies>
   <dependency>
      <artifactId>jsr107cache</artifactId>
      <version>1.0</version>
      <scope>runtime</scope>
      <groupId>net.sf.jsr107cache</groupId>
   </dependency>
</dependencies>

Maven

To use tim-ehcache in a Maven project, you can copy and paste the following dependency information into your project's POM.

<dependency>
  <groupId>org.terracotta.modules</groupId>
  <artifactId>tim-ehcache-1.3</artifactId>
  <version>1.3.2</version>
</dependency>
<dependency>
  <groupId>org.terracotta.modules</groupId>
  <artifactId>tim-ehcache-1.4.1</artifactId>
  <version>1.3.2</version>
</dependency>

At the time of this writing, the Terracotta Forge artifacts are not yet available from Maven's central repository. You must configure your project to use the Terracotta Maven repository:

http://www.terracotta.org/download/reflector/maven2

To tell Maven about this location, set the remoteRepositories property by including the following in the command line when invoking Maven:

   -DremoteRepositories=http://www.terracotta.org/download/reflector/maven2

If your project has other Terracotta Artifacts as dependencies, add the following sections to your project's POM:

<repositories>
  <repository>
    <id>terracotta-repository</id>
    <url>http://www.terracotta.org/download/reflector/maven2</url>
  </repository>
</repositories>
<pluginRepositories>
  <pluginRepository>
    <id>terracotta-repository</id>
    <url>http://www.terracotta.org/download/reflector/maven2</url>
  </pluginRepository>
</pluginRepositories>