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.
- How DSO Clustering Works
- Platform Concepts
- Hello Clustered World
- Setup and Configuration
- Planning for a Clustered App
- Configuring Terracotta DSO
- Configuration Reference
- Using Annotations
- Cluster Events
- Data Locality Methods
- Distributed Cache
- Clustered Async Data Processing
- Tool Guides
- Developer Console
- Operations Center
- tim-get (TIM Management Tool)
- Platform Statistics Recorder
- Eclipse Plugin
- Sessions Configurator
- Clustering Spring Webapp with Sessions Configurator
- Testing, Tuning, and Deployment
- Top 5 Tuning Tips
- Testing a Clustered App
- Tuning a Clustered App
- Deployment Guide
- Operations Guide
- FAQs and Troubleshooting
- General FAQ
- DSO Technical FAQ
- Troubleshooting Guide
- Non-portable Classes
- Migrating From DSO
- Concept and Architecture Guide
- Examinator Reference Application
- Clustered Data Structures Guide
- Integrating Terracotta DSO
- Clustering Spring Framework
- Integration Modules Manual
- AspectWerkz Pattern Language
Publish Date: November, 2011
Annotations for Terracotta DSO
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
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
If you are replacing configuration properties in
tc-config.xml with annotations, be sure to remove or comment out the replaced properties.
To use annotations, you must install the Terracotta Toolkit JAR using the tim-get tool:
You should see output similar to the following:
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.
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
Module Versions Are Optional
Since the tim-get script finds the optimal version for the current installation of the Terracotta kit, module versions are optional.
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.
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:
You'll also have to configure the appropriate repository:
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.
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:
Use this annotation to mark a class instrumented.
Use this annotation to honor transient fields in the instrumented class.
Use this annotation to mark a field as a root.
Use the AutolockXXX annotations to autolock methods.
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".
Use the DMI annotation to mark a method for DMI.