Child pages
  • Annotations for DSO

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin
Include Page
documentation-navbar
documentation-navbar
Section
Column
width250px
{div:style=} {include:
Wiki Markup
Div
stylemargin-top:20px
Include Page
documentation-index
documentation-index
} {div}
Column
{div9:id=documentationcolumn} {include:HeaderBasic} h1. Annotations for Terracotta DSO {include:dsoCaveat_include} {toc:minLevel=2|maxLevel=2} h2. Introduction Terracotta Distributed Shared Objects (DSO) configuration can normally be implemented by identifying classes in your application that need to be instrumented and locked using the appropriate XML in the Terracotta configuration file ({{tc-config.xml}} by default). Annotations provide a mechanism for developers to mark class instrumentation, root configuration, transient fields, and locking directly in Java class files. In this case, there is no requirement to configure these in {{tc-config.xml}}. 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. {note} If you are replacing configuration properties in {{tc-config.xml}} with annotations, be sure to remove or comment out the replaced properties. {note} h2. Installing Annotations To use annotations, you must install the Terracotta Toolkit JAR using the tim-get tool: {noformat}
Wiki Markup
Div
iddocumentationcolumn
Include Page
HeaderBasic
HeaderBasic

Annotations for Terracotta DSO

Include Page
dsoCaveat_include
dsoCaveat_include
Table of Contents
minLevel2
maxLevel2

Introduction

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

Annotations provide a mechanism for developers to mark class instrumentation, root configuration, transient fields, and locking directly in Java class files. In this case, there is no requirement to configure these in tc-config.xml.

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.

Note

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

Installing Annotations

To use annotations, you must install the Terracotta Toolkit JAR using the tim-get tool:

No Format

[PROMPT] tim-get.sh install terracotta-toolkit-1.0
{noformat}

You

should

see

output

similar

to

the

following:

{

No Format
}

Terracotta 3.3.0, as of 20100716-150712 (Revision 15922 by cruise@su10mo5 from 3.3)

Installing terracotta-toolkit-1.0 1.0.0 [org.terracotta.toolkit]...
   INSTALLED: terracotta-toolkit-1.0 1.0.0 [org.terracotta.toolkit] - Ok

Done. (Make sure to update your tc-config.xml with the new/updated version if necessary)
{noformat}

This

example

uses

version

the

Terracotta

Toolkit

with

API

version

1.0,

available

with

Terracotta

kit

version

3.3.0.

The

version

you

install

may

differ.

h2.

Configuring

Your

Application

To

Use

Annotations

After

installing

the

Terracotta

Toolkit,

you

must

add

the

JAR

file

to

the

Terracotta

configuration

file

(

{{

tc-config.xml

}}

by

default)

and

to

your

application's

classpath.

You

can

use

tim-get

to

confirm

the

installation

of

the

Terracotta

Toolkit

JAR

file,

locate

its

installation

path,

and

obtain

the

configuration

snippet

that

must

be

added

to

{{

tc-config.xml

}}

:

{

No Format
}


[PROMPT] tim-get.sh info terracotta-toolkit-1.0

Terracotta 3.3.0, as of 20100716-150712 (Revision 15922 by cruise@su10mo5 from 3.3)

(+) terracotta-toolkit-1.0 1.0.0 [org.terracotta.toolkit]
    
   Installed: YES
    
   Author   : Terracotta, Inc.
   Homepage : http://forge.terracotta.org/releases
   Docs     : http://forge.terracotta.org/releases
   Download : http://www.terracotta.org/download/reflector/releases/org/terracotta/toolkit/
terracotta-toolkit-1.0/1.0.0/terracotta-toolkit-1.0-1.0.0.jar
   Status   : Supported
   Internal : false
   Terracotta Toolkit
   Compatible with Terracotta 3.3.0

   Dependencies:
    
      None.

   Maven Coordinates:
    
      groupId   : org.terracotta.toolkit
      artifactId: terracotta-toolkit-1.0
      version   : 1.0.0

   Configuration:
    
   <?xml version="1.0" encoding="UTF-8"?>
   <modules>
   <module group-id="org.terracotta.toolkit" name="terracotta-toolkit-1.0" version="1.0.0"/>
   </modules>
   Note: If you are installing the newest or only version, the version may be omitted.

   Installed at mystuff/terracotta-3.3.0/platform/modules/org/terracotta/toolkit/terracotta-toolkit-1.0/1.0.0
   This is the latest version.
    
   There are no other versions of this TIM that are compatible with the current installation.

(+) Installed  (-) Not installed  (!) Installed but newer version exists

{noformat} {tip:title=Module Versions Are Optional} Since the
Tip
titleModule Versions Are Optional

Since the tim-get

script

finds

the

optimal

version

for

the

current

installation

of

the

Terracotta

kit,

module

versions

are

optional.

{tip} The {{Configuration}} section gives the appropriate configuration required to add to the {{clients}} section of {{

The Configuration section gives the appropriate configuration required to add to the clients section of tc-config.xml

}}

.

It

also

shows

the

JAR

file's

installation

path.

h2.

Using

Maven

or

an

IDE

Terracotta

Annotations

define

Java

annotations,

which

means

your

application

must

include

the

Terracotta

Toolkit

as

a

normal

Java

library.

If

you

are

using

Maven,

this

is

done

by

adding

the

appropriate

maven

configuration

to

your

{{

pom.xml

}}

file.

For

example:

{code:xml}

Code Block
xml
xml

    <dependency>
      <groupId>org.terracotta.toolkit</groupId>
      <artifactId>terracotta-toolkit-1.0</artifactId>
      <version>1.0.0</version>
    </dependency>
{code}

You'll

also

have

to

configure

the

appropriate

repository:

{code:xml}

Code Block
xml
xml

  <repositories>
    <repository>
      <id>terracotta-snapshots</id>
      <url>http://www.terracotta.org/download/reflector/snapshots</url>
      <releases><enabled>false</enabled></releases>
      <snapshots><enabled>true</enabled></snapshots>
    </repository>
    <repository>
      <id>terracotta-releases</id>
      <url>http://www.terracotta.org/download/reflector/releases</url>
      <releases><enabled>true</enabled></releases>
      <snapshots><enabled>false</enabled></snapshots>
    </repository>
  </repositories>
{code}

If

you

are

using

a

snapshot

version,

the

snapshop

repository

must

be

included.

In

an

IDE

such

as

Eclipse,

configure

the

dependency

as

you

do

for

any

other

Java

library.

h2. Using Terracotta Annotations After the Terracotta Toolkit is installed and configured, annotations can be used. There are currently 8 total annotations, each corresponds to a configuration element in the {{

Using Terracotta Annotations

After the Terracotta Toolkit is installed and configured, annotations can be used.

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 h3. InstrumentedClass Use this annotation to mark a class instrumented. {code}

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

InstrumentedClass

Use this annotation to mark a class instrumented.

Code Block

import org.terracotta.modules.annotations.*;

@InstrumentedClass
public class MyClass {
    ...
}
{code} h3. HonorTransient Use this annotation to honor transient fields in the instrumented class. {code}

HonorTransient

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

Code Block

import org.terracotta.modules.annotations.*;

@InstrumentedClass
@HonorTransient
public class MyClass {
    ...
}
{code} h3. Root Use this annotation to mark a field as a root. {code}

Root

Use this annotation to mark a field as a root.

Code Block

import org.terracotta.modules.annotations.*;

public class MyClass {
    @Root
    private final Map map = new HashMap();
    
    ...
}
{code} h3. Autolock Use the AutolockXXX annotations to autolock methods. {code}

Autolock

Use the AutolockXXX annotations to autolock methods.

Code Block

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; }

    ...
}
{code}

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

h3. DMI Use the DMI annotation to mark a method for DMI. {code}

DMI

Use the DMI annotation to mark a method for DMI.

Code Block

import org.terracotta.modules.annotations.*;

@InstrumentedClass
public class MyClass {
    @DMI
    public void notify() { &hellip; }
 
    ...
}
{code} {div9}