Features of the OTDT (version 1.4.x)

Version 3.5.0

The release 1.4.0 M1 is based on Eclipse 3.6.0 M3. It contains a modified version of the JDT core and several added plugins.

The following components are available:

• Compiler
• Wizards
• Editor
• Binding Editor
• Refactoring
• Structure Viewers
• Search
• Execution Environment
• OT/Equinox
• Debugging
• Help and additional Information

The Object Teams Compiler is an incremental compiler, based on the Eclipse Compiler for Java.

Language Definition

The compiler implements the language as defined in the OT/J language definition version 1.1 (OTJLD). The language definition has continuously been revised to precisely specify the language including various corner cases and combinations of features.

Language Implementation

The compiler supports all features of OT/J according to the OTJLD v1.1 §§1-7. Support for the join point sub-language ( OTJLD § 8) is not included in the stable release 1.3.x.

The compiler can be configured using global Preferences or project specific Properties.

• Configure OT/J-specific compiler diagnostics as "ignore", "warning" or "error".
  Any warnings configured on this property sheet can also be suppressed in the source code using the @SuppressWarnings annotation.
• Scoped keywords OTJLD § A.0.1 can be disabled (default is enabled).

Status of the Compiler

The OTDT is continuously tested using two growing test suites:

Name	Software under Test	Kind	Number of tests
Jacks	compiler and runtime environment	black box	>2000 (test programs)
JUnit	all of the OTDT	white box	>40000 tests.

Feel free to have a look at the test status and remaining known problems.

• The first step to developing with Object Teams in Eclipse is creating an  Object Teams Project. A wizard will guide you through that process. It will also add the Object Teams class library (otre.jar) to your project's classpath.
• Having done that, you can start adding classes — be it regular classes, or team or role classes — wizards will assist you in creating the classes properly.

• Editing Object Teams source code is supported by an outline view, showing the structure of the edited source file. This includes the Object Teams specific constructs, teams (), roles (), and method bindings (, , , ).
• The editor highlights the Object Teams keywords like "team" the same way standard Java keywords are highlighted.
• All constructs referencing other code elements are navigable. E.g. you can navigate super(), tsuper(), base() calls, as well as callin and callout bindings. The name in a team package declaration lets you navigate from a role file ( OTJLD § 1.2.5) to its enclosing team.
• Classes to which one or more roles are bound using playedBy are annotated with a marker (), that allows navigating to the role declaration(s). Similarly, methods in a base class that are bound with a callin binding are annotated with a marker (), that allows navigating to the method binding declaration(s).
  Because this feature may be resource-consuming in a large workspace the global Object Teams preferences page allows to completely disable the generation of callin markers.
• Semantic highlighting (checkbox "mark occurrences") is fully supported.
• Code completion (Ctrl-space) is widely supported. It is, e.g., possible to use completion in order to create a callout binding.
• Content assist provides quick-fixes (Ctrl-1) for a number of OT/J specific errors and warnings. Also a few templates for specific OT/J language constructs — namely with{} and within (Expression){} — are available.

• Supports easy creation of connector definitions using a table based graphical user interface. In this context, a connector is meant to be a team that inherits structure (roles) and functionality (methods) from its super-team, and its main purpose is to bind the inherited structure and functionality using playedBy declarations and callin/callout method bindings.
• Type bindings (playedBy) can be defined by choosing a provided role type and the desired base type with a type selection dialog.
• Method bindings (either callin or callout) can be established by choosing a role method and a base method from the provided role and base method list respectively.
  • Only appropriate binding kinds are selectable in the corresponding context (callin or callout).
  • Besides the provided role methods, a new role method can be implemented by selecting a provided base method, thus creating a callout binding.
• Parameter and result mappings are definable by typing in an expression in the corresponding text field of the parameter mapping configuration tab.

The binding editor can be opened either from the new team wizard or using the package explore's context menu ( Open Binding Editor).

Significant work has been put into supporting the automated refactoring of OT/J code. The following refactorings take into account the Object Teams-specific relationships (implicit role inheritance, team nesting, role-base bindings and method bindings).

• Extract Method (extended support currently unavailable)
• Move Method (extended support currently unavailable)
• Rename Method
• Rename Project
• Rename Source folder
• Rename Field

The Rename Package refactoring is also available, with the only limitation that you cannot rename team-packages. The Rename Type refactoring does not yet support role files ( OTJLD § 1.2.5).

The Package Explorer

• provides access to all project artifacts and their structure, i.e. source files, used libraries (jar-files), and other documents. Note that team and role classes are annotated with distinct icons ( for teams and for roles). (The same icons are used throughout the IDE, whenever a team or role is visible.)
• If "Java Type Indicators" is enabled under general preferences/label decorations, OT-specific decorations will also be applied to compilation units (files) and team packages.
• By opening the tree-branches, you can peek at the structure of e.g. classes.
• For team classes, there is special support for role files ( OTJLD § 1.2.5):
  Role files are separate files and can be shown either physically () as (separate) files in the team package or logically () as member types of the enclosing team.
• Furthermore, the Package Explorer provides the current context for other operations. The Team- and Role-Wizards, for example, have a pre-set source folder, package and enclosing class when a team is selected in the Package Explorer.

The Hierarchy View

• Object Teams intruduce a new type hierarchy. Besides the normal ("extends") inheritance, there is an additional "implicit" role inheritance, established by role name equality in a team hierarchy. In conjunction with team nesting roles support a controlled form of multiple inheritance.
• The new implicit inheritance has been integrated completely into the standard JDT Hierarchy View. The revised Hierarchy View supercedes the incomplete support which was provided by a specific "Implicit Hierarchy View" in previous releases of the OTDT.

Search references

• The Java Search functionality has been extended to include search results of Object Teams code, that is, callin and callout bindings, and playedBy-relationships.

Call hierarchy

• Also the call hierarchy has been extended for browsing control flows passing through method bindings (callin and callout).
• The OTDT introduced support for call hierarchies regarding field accesses (read, write, any) and class instantiations. As of version 3.4 this functionality has been adopted by Eclipse.

Aspect weaving

• All aspect oriented languages have some kind of weaving process, where the aspect code is combined with the other (base) code.
• Object Teams programs perform the weaving at application startup time, i.e. at the moment, the program is launched. In order to do this, there is the so-called Object Teams Runtime Environment (OTRE), that wraps around the standard launching procedure.
• All this is handled transparently using the standard Eclipse "Run" feature. Running any main class of an Object Teams project automatically includes the OTRE (This feature has been changed in the OTDT 1.2.2).

Aspect deployment/activation

• A new "Team Activation" tab in the "Run-Configuration" allows to instantiate and activate teams without modifying the program's source code.
• Teams that cause aspect code to be woven into an application can be added to a program
  • by explicit reference within the program source code or
  • by a configuration file which is mentioned as a parameter to the VM or
  • by adding them via the aforementioned "Team Activation" tab.
  No such configuration is needed for compilation.

Technology used

• Alternative support for a Java 5 based weaver. The original OT/J-weaver uses the JMangler framework for intercepting classes during class loading. The new version uses the Java-agent concept of Java 5 (JPLIS) instead, which means we are independent of JMangler. In the future this version will support aspect weaving not only at load time but also while an application is running.
  The launch configuration for OT/J applications contains a new checkbox for selecting the weaver ("Java 5 JPLIS Launching").

Starting with the OTDT version 0.9.9 it is possible to develop Eclipse plugins using OT/J as the implementation language.

• Using the plugin org.objectteams.otequinox, a plugin ("aspect plugin") may declare that it adapts classes from a specified other plugin ("base plugin").
• By an integration of the Object Teams Runtime Environment with new hooks in the Equinox implementation a team class from an aspect plugin can trigger byte-code aspect weaving into its base plugin at load-time. As a result an aspect plugin can indeed adapt the behaviour of another plugin. These bindings are declared using the extension point aspectBindings from the mentioned plugin org.objectteams.otequinox.
• The initial client of the OT/Equinox technology is a tiny plugin which extends Eclipse's "about plugins" dialog by additionally displaying which plugins are being adapted by which aspect plugins. This information is found in the version column of the mentioned dialog. This way a user of the OTDT can always check whether a given plugin performs as shipped, or whether it has been adapted by another plugin.
• The OTDT uses the capabilities of OT/Equinox for some parts of its own implementation. The technology is mainly used for making the JDT-UI aware of Object Teams without having to copy source code or modifying source code of the JDT-UI in place.
• A new project nature Object Teams Plugin Project is provided, supporting the development of plugins written in OT/J.
• Support for OT/Equinox is added to the run/debug dialogs for all Equinox related launches.
• If desired the load-time weaver can be disabled by commenting out or removing the following line from the file configuration/config.ini:
  osgi.hook.configurators.include=org.objectteams.eclipse.transformer.hook.HookConfigurator
  Ideally, disabling OT/Equinox will be handled by temporarily uninstalling this feature, but the required support by the p2 provisioning system is not yet stable enough to do this.

The debugger has been enhanced to support debugging of OT/J programs at the source code level. It is possible to set breakpoints and step through Object Teams code.

Stepping through Code

The following language features produce byte codes for which a standard Java debugger is not able to display appropriate source locations:

• Role files ( OTJLD § 1.2.5)
• Implicit inheritance ( OTJLD § 1.3.1)
• Callout bindings ( OTJLD § 3) (including callout override ( OTJLD § 3.1(e)))
• Callin bindings ( OTJLD § 4)

The OTDT-Debugger re-maps the byte codes produced by all this constructs to the appropriate source locations. As a result stepping through these sections of a program completely hides the internal translations from the user.

The following features are not yet fully supported by the debugger:

• Role constructors (see OTJLD § 2.4)
• Parameters with declared lifting ( OTJLD § 2.3.2 — code for lifting is not filtered out yet)

Setting Breakpoints

Use double click on ruler or context menu Toggle Breakpoint to set breakpoints in OT/J-Code. Setting breakpoint in role files is supported, too.

New View: "Team Monitor"

The team monitor () view helps to debug issues related to team activation ( OTJLD § 5). For this purpose it displays all known team instances and shows their activation status as one of

• inactive ,
• active (either globally or for the thread selected in the debug view), or
• implicitly active (temporarily active because the team or one of its roles is currently executing code).

Also, a selected team can be (de)activated interactively via the context menu.

Filtering variables

The OT/J compiler and the loadtime weaver both add some internal variables to the code. By default such internal variables are hidden within the Team Monitor as well as in the standard variables view. Both views can be configured to also show these internal variables if so desired.

Known Issues and Limitations

• Dynamic code evaluation is not supported yet, make sure to clear the Expression view.
• Hot code replacement of woven code is not supported.

The following sources for help and for further information are bundled with the release:

• A Tutorial (available via the welcome page) guiding through the first steps of using the OTDT.
• Example programs demonstrating key features of Object Teams (also via the welcome page).
• A detailed guide on using the OTDT via the Help Index, including a link to the language definition (which is also bundled).
• Problems that are listed in the problem view are linked (when possible) to a corresponding explanatory entry in the language definition. (Context menu ->  Go to Language Definition).