Terracotta DSO Eclipse Plugin Guide
The Terracotta Distributed Shared Objects (DSO) Eclipse Plug-in provides a self-contained environment for developing DSO applications within the Eclipse IDE. You can install and manage the DSO plugin from within your Eclipse IDE.
To view a webcast on using the Terracotta Eclipse plugin, see Eclipse Plugin Training.
For best results, use Eclipse 3.3 or later. If you are using Eclipse 3.2, be sure to install the Eclipse Plug-in Development Environment (PDE) to allow the Terracotta Eclipse plugin to function correctly.
- Invoke the Help → Software Updates → Find and Install... menu:
- In the Feature Updates dialog, select Search for new features to install and click the Next button:
- In the Update sites to visit dialog, click the New Remote Site... button:
- In the New Update Site dialog:
Terracotta in the Name: field.
- Enter the appropriate URL in the URL: field:
Your new update site will appear in the Update sites to visit dialog. Click Finish to move on to the Search Results dialog.
- In the Search Results dialog, select the Terracotta feature and click the Next button:
- In the Feature License dialog, read the license and, if you agree to its terms, select the I accept the terms of the license agreement:
- In the Installation dialog, click the Finish button:
- In the Feature Verifcation dialog, click the Install All button:
- Terracotta DSO Eclipse Plug-in will be installed followed by a prompt to restart Eclipse, to which you should agree:
- After Eclipse has restarted, invoke the Help → Help Contents menu and view the DSO Tutorial:
M2 Eclipse Plugin
You can use Maven from within Eclipse by installing the M2 Maven Plugin, available from Codehaus. To update Eclipse with the M2 plugin, use http://m2eclipse.sonatype.org/update/.
While attempting to complete the installation of the Maven plugin in Eclipse, you may encounter an error. Follow these steps to solve the error:
- Click OK to dismiss the original error dialog.
A second dialog with the message "Cannot complete the request" appears.
- In the second dialog, uncheck the following download options:
- Maven Integration for AJDT
- Maven SCM handler for Subeclipse
- Maven SCM handler for Team/CVS
- Maven SCM handler for Integration
- Maven: The Definitive Guide book
- Click Next and follow the instructions to complete the Eclipse Maven plugin installation.
Once it is added to Eclipse, configure the M2 Eclipse plugin to point to the local JDK location.
Adding DSO to an Existing Project
You add Terracotta capabilities to an existing Java project by invoking the project context menus and selecting the Add Terracotta Nature item under the Terracotta menu.
A dialog will be displayed asking for the name of any existing Terracotta configuration file that may already exist in your project, defaulting to tc-config.xml, as well as any Java options that should be used when running the Terracotta server.
If no configuration file exists at the specified location, a default configuration file will be created. A folder named terracotta will be created at the root of your project workspace, meant to be the location of log files and other artifacts that are created during the execution of your DSO system. Each of your Java modules are inspected for the purpose of providing graphical adornments associated with the configuration you provided. Finally, the project node in the workspace Browser will be adorned with an indication that Terracotta capabilities have been added.
Creating a new DSO Project
To create a new DSO project invoke the New Project Wizard using the New|Project... menu and select Java|Terracotta Projects|Terracotta DSO Project.
A default config file, tc-config.xml, will be created as well as a top-level folder, terracotta, meant to contain DSO-related filesystem artifacts generated by your running DSO system. Such artifacts include server and client logs and the database used to maintain your distributed object state.
Configuring Your DSO Project
There are five (5) different ways to accomplish configuration tasks. The methods you employ is a matter of personal taste in most cases.
- Config View
- JavaEditor context menus
- Structured views context menus
- Config Editor
- manually editing the config file
The Config View
The most direct and efficient configuration method entails using the Config View, which allow for a drag&drop interaction style. The Config View is a part of the Terracotta perspective, along with the BootJar View, although it can be utilized independently, as can any view.
The Config View is a structured display of the Terracotta configuration associated with the project of the document currently being edited. The top-level elements correspond to the tabs of the DSO Config page of the DSO Config Editor: Roots, Locks, Transient fields, Instrumented classes, Distributed methods, and Additional boot classes.
To add a new root to your configuration, drag a field from one of the structured views such as the Package Explorer or Outline View and drop it onto the Roots node. To remove a root, select it and either use the Delete context- or view-menu.
To auto-lock all the methods of a shared type, drop that type onto the Autolocks node. To change the lock method expression or the lock-type, use the context-menus on that lock item.
JavaEditor Context Menus
Configuration operations can be taken directly within the JavaEditor using the Terracotta context-menu. For example, to add a new root, select the field and display the context-menu in whatever way is appropriate for you platform.
Structured Views Context Menus
Configuration operations can be taken directlry with the standard structured views, such as the Package Explorer or Outline View. For example, to specify a transient field use the context-menu on the target field.
The Config Editor
The multi-page Config Editor is a forms&fields presentation of the Terracotta configuration. The Config Editor is displayed via the Show Config Editor item on the Terracotta workbench menu.
The first page of the Config Editor displays the raw XML form of the configuration file.
The second page, DSO config, presents the portion of the configuration model that specified how your application is to be treated as a DSO application. The subsections of the DSO Config page map directly to the top-level nodes found in the DSO View, described earlier.
The third page, Servers config, presents the portion of the configuration model that specified settings to be used by the Terracotta Server, such as networking ports and log file locations.
The last page, Clients config, presents the portion of the configuration model that specified settings to be all DSO clients, such as the client log file locations and debug options.
Manually Editing the Config File
Finally, you can manually edit the Terracotta config file using any available editor. This may be necessary if you wish to change portions of the configuration model that have not yet been exposed by the Terracotta DSO plugin. When the config file is saved, the plugin parses it and updates all graphical adornments and open editors/views.
Any class that contains a field you would like to make a shared root or is a type whose instances will be part of a shared object graph must be instrumented by DSO. You can specify which classes in your project are to be instrumented in the Instrumented Classes tab of the DSO Config page of the Terracotta Config editor.
Specifying Instrumentation Patterns
The Instrumented classes tab lets you define rules for specifying which classes are instrumented by DSO. There are two types of rules: include and exclude. An include rule indicates that the specified classes are to be instrumented and lets you specify additional attributes to be assigned to the instrumented classes. An exclude rule indicates that the specified classes are not to be instrumented. It really only makes sense to exclude classes from a set that has previously been included.
Instances of instrumented classes may be shared. To indicate to DSO that any Java transient fields of a shared instance should not be shared, select the Honor transient checkbox. By default DSO includes all fields of a shared object for replication. In addition to fields marked as Java transient, a shared object may contain other fields that aren't appropriate for transparent replication. Those fields should be marked as DSO Transient Fields. One way or the other, those transient fields need to get re-initialized when a new copy of a shared object is materialized on a client. You can use the On load button to specify a method to invoke or some BeanShell script to execute on the shared instance. These two methods allow you to re-initialize any transient fields needed by a shared object.
Specifying Instrumentation Rules
You can manually enter a class pattern or select a class or package-fragment from a chooser. Alternately, you can select the class in the Package Explorer or Outline View, invoke the Terracotta context menu and choose Instrumented.
In addition to specifying which classes are to be instrumented, you can also specify classes that are to be excluded from instrumentation. This is useful because the pattern language for describing class includes and exclude allows for a shorthand wildcard notation, much like regular expressions. For convenience, you can specify that all classes under a particular package-fragment be instrumented. If there are actually some classes in that set that should not be instrumented, you can explicitly exclude them.
You can manually enter an excluded class pattern or select a class or package-fragment from a chooser. Alternately, you can select a class or package-fragment in the Workspace Explorer or Outline View, invoke the Terracotta context menu and choose Exclude.
A DSO instrumented class appears in the Project Explorer or Outline View with a red check adorning its label. An excluded class is adorned with a red crossmark.
Instrumentation Rule Precedence
The order of your instrumentation rules (include or exclude) are significant, earlier rules are superceded by later rules. You can change the order of an instrumentation rule by selecting it and using the arrow buttons to move the rule up or down the list.
The Pattern Language
The pattern language for specifying the set of your classes to be instrumented or excluded is based on those used in Aspect-oriented Programming frameworks for specify pointcuts. The following are valid instrumentation include and exclude patterns:
specifies only class Main in com.project
specifies all classes in com.project
specifies all classes in com.project ending with Main
specifies all classes under com
For the complete description refer to the Aspectwerkz joinpoint selection pattern language.
With Terracotta DSO you specify which fields of your instrumented classes are to be treated a shared roots. To specify shared roots use the Roots tab of the DSO Config page of the Config editor.
You can manually enter a fully-qualified root field name...
... or select the field from a chooser.
Alternately, you can navigate to the field in the Workspace browser or Outline view, invoke the Terracotta context menu and choose the Shared root item.
Roots are indicated in the Workspace browser or Outline view with a red check adorning its label.
In the Java editor a root is indicated by an icon in the Overview ruler on the left gutter of the textview.
For more information on the concept of DSO roots refer to the Concept and Architecture Guide.
A DSO distributed lock is a form of a distributed semaphore, protecting areas of code that modify members of a shared root from simultaneous access. If you're familiar with distributed programming methods, you can think of a lock as a distributed synchronized method.
To specify a distributed lock, use the Locks tab of The DSO Application page of the configuration editor. You can manually enter a lock method pattern or you can select a method from a chooser. Alternately, you can navigate to a particular method in your project using the Workspace Browser or Outline View, invoke the Terracotta context menu and choose either Named lock or Auto lock.
For more information on the concept of DSO distributed locks refer to the Concept and Architecture Guide.
To transparently distribute a method in one of your instrumented classes simply list the method signature in the Distributed Methods tab of the DSO Application page of the configuration editor. You can manually enter the signature or you can select the method from a chooser. Alternately, you can navigate to the method in the Package Explorer or Outline View, invoke the Terracotta context menu and select Methods|Distributed method.
Sometimes an object referenced by a shared root contains fields that aren't appropriate for clustering. Some types of objects are just not meant to be shared across nodes, being inherently associated with a host-specific resource. For example, a Logger is meant to direct output to a file in a particular location on a specific host. Clustering a Logger would be problematic and shouldn't be done. For cases like this, DSO lets you specify the Logger instance, by fully-qualified field name, as a DSO transient field. Such as field will not be clustered by DSO, much like a field marked as a Java transient field does not participate in serialization.
Use the Transient fields tab of the DSO Config page of the Terracotta Config editor to list the fields of your shared objects that you would like to exclude from sharing.
You can manually list the fully-qualified names of your transient fields or select them from a chooser. Alternately, you can navigate to a field in the Workspace browser and use the Terracotta context menu to mark the fields as Transient.
To re-initialize your DSO transient fields when their containing instance is materialized on a client, use the On load attribute of containing types instrumentation rule to specify a method to be invoked or some BeanShell script to be executed.
For more information on the concept of DSO transient fields refer to the Concept and Architecture Guide.
If you need to use system classes in your DSO application shared object graphs, you may need to create a custom BootJar that contains instrumented versions of those class. BootJar classes take priority over all other classes.
Terracotta DSO comes with a BootJar containing pre-instrumented versions of many of the most commonly used system classes, such as java.util.HashMap, as well as the majority of the Swing data models, such as javax.swing.table.DefaultTableModel. However, if you're attempting to include a system class in a shared root graph and you are receiving a runtime exception stating that the class is not portable, you will need to include that class in a custom BootJar.
You can specify additional BootJar classes on the Boot classes tab of the DSO Config page of the Terracotta Config editor. Alternatively, you can select a system type in the Package Explorer or Outline View, invoke the Terracotta project menu and select Boot Jar. Note that types meant to be added to the BootJar are system types, such as those that make up the core Java platform, as opposed to classes you define or classes that are part of open-source or third-party libraries.
If you have declared BootJar classes, when you run your DSO application and your config file is newer than the BootJar, the BootJar will automatically be updated. You can also manually update the BootJar by invoking the project context menu and selecting Build BootJar.... The new BootJar will be created in the root of your project with a name that begins with dso-boot- and includes the compiler- and platform-name and Java version number (for example: dso-boot-hotspot_win32_142.jar).
When running your DSO Applications, that BootJar will automatically be used. If you no longer have a need for the BootJar be sure to delete it from your workspace.
Starting the Terracotta Server
Once you have created one or more server configurations you can run the Terracotta server using any one of those configurations by invoking the project's Servers context menu.
Assuming the configuration you created was valid and there isn't already another server listening on the prescribed DSO listen port, you will see a startup message from the newly running server in the Console window.
If you start a server from outside of the Eclipse environment, the DSO plugin will be unable to provide any indication of its state.
Running Your Terracotta Client
To run your DSO client application, and create a new DSO launch configuration as a side-effect, select your instrumented class containing a main method, and choose the Run As or Debug As|Terracotta DSO Application context menu. A DSO Launch Configuration named after the class you are running or debugging will be created automatically, which you can further edit using the Debug or Run launch configuration editor dialogs.
How to Tell that your DSO Application is Running
If you start your application using a launch shortcut or a standard launch configuration other than Terracotta DSO Application, your application will start but it will not be using the Terracotta DSO runtime and, therefore, will act as a standard Java application. You can tell when the DSO runtime is in use by the startup output that appears in the Console View.
DSO Application Problem Feedback
When problems relating to your application configuration are encountered, such as attempts to share instances of non-portable types, a resolution dialog is shown providing an opportunity to remedy the problem by taking actions that update your DSO configuration. The dialog displays an overview of the type of problem encountered, a list of specific issues that need to be resolved, and the application data that caused the problem. For example, if in the completed Slider tutorial you were to remove
javax.swing.DefaultBoundedRangeModel as an additional-boot-jar-class and then try to run the Slider application, the non-portable resolution dialog would be displayed, showing the
tutorial.Slider.rangeModel field as being a non-portable system class. You could then choose to add
DefaultBoundedRangeModel as an additional-boot-jar-class, and your configuration file would be updated accordingly.
The types of problems encountered will be:
- attempt to share an inherently non-shareable type
- attempt to share a system type not loaded from the DSO boot jar
- attempt to share a type that has not been declared to be Terracotta instrumented
Declaring Transient Data
Any problematic object field can be excluded from sharing by declaring that field as a Terracotta transient field. Transient fields generally must be re-constituted when their containing object is loaded from the Terracotta Server into a DSO client application. This can be accomplished using a scripting mechanism or by arranging for a particular method to be invoked on the containing object.
A good use for Terracotta transient fields are members whose types are never appropriate to share, such as objects associated with VM-specific resources such as threads or Files. These types of objects are never shareable, with Terracotta DSO or any other clustering strategy.
For more information about specifying and handling transient data, see the Concept and Architecture Guide.
Sharing System Types
Certain system types must be loaded from the boot classpath in order to be shareable with Terracotta DSO. Many of the most commonly shared system types are automatically pre-instrumented and included in the default DSO bootjar. If other system types are required to be shared, they can be listed in the additional-boot-jar-classes section of your configuration file, and a custom bootjar will be created and used as needed. If an attempt is made to share an instance of such a system type not loaded from the DSO bootjar, the offending objects will be displayed in the non-portable resolution dialog, at which time you can choose to have them added to your custom DSO bootjar.
For more information about the DSO bootjar, see the Concept and Architecture Guide.
Adding Additional Instrumented Types
In order to share your application types, they must declared in the instrumented-classes section of your DSO configuration file. The instrumentation process occurs at load-time and allows Terracotta to inject the code required to manage your object state between the Terracotta Server and the DSO client application participating in the cluster. If an attempt is made to share an instance that was not declared for instrumentation, the offending objects will be displayed in the NonPortable resolution dialog, at which time you can choose to add those types to the set of instrumented classes in your configuration.
For more information about object portability, see the Concept and Architecture Guide.
Monitoring the Terracotta Server
Use the Show AdminConsole... Terracotta menubar item to monitor running Terracotta Servers and their connected clients.
For more information about the Administration Console refer to the Admin Console Guide.
Stopping the Terracotta Server
You can terminate a running Terracotta Server by invoking the project context menu or Terracotta menubar menu and selecting Terracotta|Servers|<server name>.
Any Terracotta Servers started outside of the Eclipse environment cannot be managed by the Terracotta plugin.
Removing Terracotta From Your Project
You can remove Terracotta capabilities from an existing Terracotta project by invoking the project context menu and selecting Remove Terracotta Nature from the Terracotta menu. You can also select the Terracotta project and use the Terracotta|Remove Terracotta Nature menubar item.