THIS IS ARCHIVE DOCUMENTATION FOR TERRACOTTA v. 3.0. For the current release, see the current DSO documentation »

Release: 3.0.1
Publish Date: May, 2009

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 the 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.

One advantage to using Annotations is that the Terracotta definitions for your classes will stay with your code. Encapsulating all information about a class — including its Terracotta nature — in the class file improves the readability of your application. Also, refactoring annotated classes does not require changing the tc-config.xml file.

If you are replacing configuration properties in tc-config.xml with annotations, be sure to remove or comment out the replaced properties.

Installing TIM-Annotations

To use annotations, you will need the annotations TIM. This can installed in two ways:

• Automatically using the tim-get script
• Manually from the Terracotta Forge (tim-annotations)

To install automatically using the tim-get script use the following command:

[PROMPT] tim-get.sh 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] tim-get.sh 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 : http://forge.terracotta.org/releases/projects/tim-annotations/
   Download : http://download.terracotta.org/maven2/org/terracotta/modules/tim-annotations/1.2.0-SNAPSHOT/tim-annotations-1.2.0-SNAPSHOT.jar
   Status   : 
   
   Annotations package for Terracotta projects
   
   Compatible with TC 2.7.0-SNAPSHOT
   
   Dependencies:
   
      + modules-common (2.7.0-SNAPSHOT)
   
   Maven Coordinates:
   
      groupId   : org.terracotta.modules
      artifactId: tim-annotations
      version   : 1.2.0-SNAPSHOT
   
   Configuration:
   
      <modules>
         <module name="tim-annotations" version="1.2.0-SNAPSHOT" />
      </modules>
   
   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.: <dependency> <groupId>org.terracotta.modules</groupId> <artifactId>tim-annotations</artifactId> <version>1.2.0-SNAPSHOT</version> </dependency> and (it wouldn't be Maven if it didn't require tons of XML would it?) you'll have to configure the appropriate repository: <repositories> <repository> <id>terracotta-repository</id> <url>http://www.terracotta.org/download/reflector/maven2</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>true</enabled> </snapshots> </repository> </repositories> 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

InstrumentedClass

Use this annotation to mark a class instrumented.

import org.terracotta.modules.annotations.*;

@InstrumentedClass
public class MyClass {
    ...
}

HonorTransient

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

import org.terracotta.modules.annotations.*;

@InstrumentedClass
@HonorTransient
public class MyClass {
    ...
}

Root

Use this annotation to mark a field as a root.

import org.terracotta.modules.annotations.*;

public class MyClass {
    @Root
    private final Map map = new HashMap();
    
    ...
}

Autolock

Use the AutolockXXX annotations to autolock methods.

import org.terracotta.modules.annotations.*;

@InstrumentedClass
public class MyClass {
    @AutolockRead
    public synchronized void getFoo() { return foo; }

    @AutolockWrite
    public synchronized void setFoo(int foo) { this.foo = foo; }
  
    @AutolockConcurrentWrite
    public synchronized void setFooConcurrent(int foo) { this.foo = foo; }

    @AutolockSynchronousWrite
    public synchronized void setFooSynchronous(int foo) { this.foo = foo; }

    ...
}

If you are replacing autolock properties in tc-config.xml with AutolockXXX annotations, you may find that the lock level has not been specified. The default lock level for autolock properties in tc-config-xml is "write".

DMI

Use the DMI annotation to mark a method for DMI.

import org.terracotta.modules.annotations.*;

@InstrumentedClass
public class MyClass {
    @DMI
    public void notify() { … }
 
    ...
}