Child pages
  • Annotations for DSO
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 9 Next »

About Terracotta Documentation

This documentation is about Terracotta DSO, an advanced distributed-computing technology aimed at meeting special clustering requirements.

Terracotta products without the overhead and complexity of DSO meet the needs of almost all use cases and clustering requirements. To learn how to migrate from Terracotta DSO to standard Terracotta products, see Migrating From Terracotta DSO. To find documentation on non-DSO (standard) Terracotta products, see Terracotta Documentation. Terracotta release information, such as release notes and platform compatibility, is found in Product Information.

Unknown macro: {div9}
Release: 3.6
Publish Date: November, 2011

Documentation Archive »

Using Annotations

Terracotta configuration can normally be implemented by identifying classes in your application that need to be instrumented and locked using the appropriate XML in your tc-config.xml file.

Annotations, however, provide a mechanism for developers to mark class instrumentation, root configuration, transient fields, and locking directly in your Java class files.

The advantages to using Annotations are that the Terracotta definitions for your classes will stay with your code, thus improving the readability of your application (all information about a class, including it's Terracotta nature, is encapsulated in the class file) and the ability to refactor (refactoring classes with Annotations does not require changing the tc-config.xml file accordingly).

Installing TIM-Annotations

To use annotations, you will need the annotations TIM. This can be retrieved from the [Terracotta Forge]:

You can install this TIM into your Terracotta kit using the [TIM Update Center] with a simple command, e.g.:

[PROMPT] install tim-annotations
Installing tim-annotations (1.2.0-SNAPSHOT) and dependencies...
   Skipped: modules-common (2.7.0-SNAPSHOT)
   Installed: tim-annotations (1.2.0-SNAPSHOT)

Of course, your versions may differ, the versions listed above are for a pre-release version of Terracotta 2.7.

Configuring Your Application To Use Annotations

After installing tim-annotations, you must add the TIM to your tc-config.xml file. Again, the TIM Update Center can help us with this task:

[PROMPT] info tim-annotations
Terracotta 2.7.0-stable0, as of 20080728-140730 (Revision 9506 by cruise@rh4mo0 from 2.7)

tim-annotations (1.2.0-SNAPSHOT)

   Installed: YES
   Author   : Terracotta, Inc.
   Copyright: Copyright (c) 2007 Terracotta, Inc.
   Homepage :
   Download :
   Status   : 
   Annotations package for Terracotta projects
   Compatible with TC 2.7.0-SNAPSHOT
      + modules-common (2.7.0-SNAPSHOT)
   Maven Coordinates:
      groupId   : org.terracotta.modules
      artifactId: tim-annotations
      version   : 1.2.0-SNAPSHOT
         <module name="tim-annotations" version="1.2.0-SNAPSHOT" />
   Installed at /Users/tgautier/terracotta-2.7.0-stable0/modules/org/terracotta/modules/tim-annotations/1.2.0-SNAPSHOT
   There are no other versions of this TIM that is compatible with TC 2.7.0-SNAPSHOT

The Configuration section lists the appropriate configuration required to configure Terracotta to use this TIM. Add it to the clients section of your tc-config.xml.

Using Annotations

After you have installed and configured tim-annotations you are ready to use your annotations.

TIM-Annotations defines Java annotations, which means your application must include TIM-Annotations as a normal Java library. If you are using Maven, this is done simply by adding the appropriate maven configuration to your pom.xml file, e.g.:


and (it wouldn't be Maven if it didn't require tons of XML would it?) you'll have to configure the appropriate repository:


If you have Eclipse, or Idea, or just plain old Vi, you will need to configure the dependency like any other Java library.

There are currently 8 total annotations, each corresponds to a configuration element in the tc-config.xml file. They are:

  • InstrumentedClass
  • HonorTransient
  • Root
  • AutolockRead
  • AutolockWrite
  • AutolockConcurrentWrite
  • AutolockSynchronousWrite
  • DMI


Use this annotation to mark a class instrumented.

import org.terracotta.modules.annotations.InstrumentedClass;

public class MyClass {


Use this annotation to honor transient fields in the instrumented class.

import org.terracotta.modules.annotations.InstrumentedClass;

public class MyClass {


Use this annotation to mark a field as a root.

import org.terracotta.modules.annotations.InstrumentedClass;

public class MyClass {
    private final Map map = new HahsMap();


Use the AutolockXXX annotations to autolock methods.

import org.terracotta.modules.annotations.InstrumentedClass;

public class MyClass {

  public synchronized void getFoo() { return foo; }

  public synchronized void setFoo(int foo) { = foo; }
  public synchronized void setFooConcurrent(int foo) { = foo; }

  public synchronized void setFooSynchronous(int foo) { = foo; }


Use the DMI annotation to mark a method for DMI.

import org.terracotta.modules.annotations.InstrumentedClass;

public class MyClass {
    public void notify() { &hellip; }
  • No labels