# OTDT 0.7 (Incubation) - New and Noteworthy

## Configuration

Migration of old OT-projects
since 0.7 M2
308029

When opening Object Teams project that have been created by a previous OTDT version (1.x from objectteams.org) some internal data need to be migrated to the new `org.eclipse.objectteams` prefix, notably:

`.project`
  project nature and builder
`META-INF/MANIFEST.MF`
  dependency on OT/Equinox plug-in
`plugin.xml`
  `aspectBinding` declarations

Diagnostics have been added to signal these issues as errors:

Quick fixes have been implemented for performing the necessary changes, like:

Use compiler options for plug-in export
since 0.7 M4
316553

When interactively exporting an OT plug-in (using the corresponding export wizard) it is now possible to tell the builder to use the OT/J compiler options from the project settings. In order to do so simply include the following directive in your `build.properties` file:

javacProjectSettings=true
This is a standard PDE setting which now applies to OT-specific compiler options, too.

## Views & Dialogs

Binding to callout-method via binding editor since 0.7 M4 315520 | The binding editor now also shows base methods that are defined by a callout binding (relevant in role-of-role situations): Also a new icon for the "New method()" entry was introduced.
Create callout-to-field via binding editor since 0.7 M4 315465 | The binding editor now supports the creation of callout-to-field bindings. Simply select (a) "New method()", (b) "->", (c) a base field: As the result you will see two new callout bindings (`get` and `set`) to the same field. If only a getter or only a setter was intended simply remove the undesired binding.
"Go to Language Definition" without using Problems view since 0.7 318071 | The action Go to Language Definition, which previously could only be invoked from the Problems view, can now be invoked in two more ways: Using the context menu on the problem marker in the editor's left gutter: Using a new button on the problem hover:

## Content assist

Create "precedence after" since 0.7 M3 313804 | When a quickfix is used for creating a `precedence` declaration that affects `after` callin bindings, the quickfix automatically creates the declaration as `precedence after` (see also the change of OTJLD §4.8(a) described here).

Add/remove signatures of method bindings
since 0.7 M3
310923

New quick assists support converting between method bindings with and without signatures. When, e.g., creating a method binding by means of completion, signatures are automatically included. In that case a quick assist can be used to convert that verbose binding into its shorter versions without signatures:

Conversely, a method binding without signatures can be converted to the long form:

The quick assist for removing signatures is disabled if argument names are used either in a parameter mapping or a guard predicate.

Proposal to override inherited role
since 0.7
302827

A new kind of completion proposal has been added for overriding a role class inherited from the super team:

Invoking this proposal will insert the following code:

        @Override
        protected class Subscriber  {
        }

The new role implicitly inherits all properties from the inherited role `Bonus.Subscriber` (OTJLD §1.3.1(c)) and may override methods and/or refine `extends` (OTJLD §1.3.2(b)) and `playedBy` (OTJLD §2.1(c)) relationships.

## Run / Debug

Fade out JMangler
since 0.7 M1
302976

Previous versions of the OTDT featured two alternative strategies for launching OT/J applications: JMangler and JPLIS. During the move to Eclipse.org, the support for JMangler was discontinued because the JPLIS launch mode has long matured and bringing JMangler to Eclipse.org would have caused additional license issues.

For users this means that launch configurations have been simplified as the checkbox Java 5 JPLIS Launching has been removed, leaving only the Enable OTRE checkbox:

Show "_OT$base" field
since 0.7
316907

The Variables view has the option to filter any synthetic variables generated by the OT/J compiler (Java > Show OT/J internal variables). However, the synthetic `_OT$base` field is special, as it holds the essential information to which base instance a given role instance is linked. The `_OT$base` field is now shown in the Variables view independent of the current filter setting:

Also note the similarity to the synthetic field `this$0` which refers to the enclosing (team) instance.

## API

Team serialization
since 0.7 M1
304728
304729

Teams and roles can now be serialized if they declare to implement `java.io.Serializable`. By default serialization does not handle any generated fields by which roles, teams and bases are linked (role caches, base-to-role backpointers). Team classes wishing to persist their roles can now do so by implementing a normal pair of `writeObject` / `readObject` methods. New API has been added to `org.objectteams.Team` for initializing a team after restoring from its persisted representation:

`void restore()`
  Serializable teams must invoke this method once from their readObject() method in order to re-initialize internal data structures.
`void restoreRole(Class<?> clazz, Object role)`
  Serializable teams must invoke this method from their readObject() method for each role that has been retrieved and shall be re-registered for this team.

Additionally, new API has been added for persisting / restoring the global activation state of a team:

`void writeGlobalActivationState(ObjectOutputStream out) throws IOException`
  If a serializable team wishes to persist its global activation status it must call this method from its `writeObject()` method and correspondingly call `readGlobalActivationState(ObjectInputStream)` from its `readObject()`.
`void readGlobalActivationState(ObjectInputStream in) throws IOException`
  If a serializable team wishes to persist its global activation status it must call this method from its `readObject()` method and correspondingly call `writeGlobalActivationState(ObjectOutputStream)` from its `writeObject()`. If a team is restored that was globally active when serialized, it will be activated correspondingly during deserialization when this method is called.

## Language

Semantics of precedence
since 0.7 M3
310917

The semantics of how exactly a `precedence` declaration should affect `after` callin bindings was underspecified in the OTJLD and the OTRE implemented unintended semantics.

To fix these issues OTJLD §4.8(a) has been extended to

- specify how a precedence declaration affects the execution order:
  for `before` and `replace` bindings a high precedence (i.e., being listed early) means early triggering, but for `after` bindings a high precedence means late triggering.
- require precedence declarations which affect after bindings to make this fact explicit by using `precedence after` instead of just `precedence`.

The new semantics have been implemented in the OTRE accordingly (see also the corresponding quickfix).

Merging precedence of different kinds
since 0.7 M4
316148

The semantics of how exactly `precedence` declarations of different kinds (class-based vs. binding-based) would be merged was underspecified. Consider the following precedence declarations:

      public team class MyTeam {
          precedence MyRoleB.bl1, MyRoleA.bl3;
              protected class MyRoleB playedBy MyBase {
                  precedence bl1, bl2;
                  ...
              }
          ...
      }

Here the C3 algorithm could produce two different orders (`bl1, bl3, bl2`) or (`bl1, bl2, bl3`) (both order are consistent with the input lists). Which order is chosen depends on in which order the two precedence lists are passed into the algorithm.

To fix these issues OTJLD §4.8(d) has been extended to specify that more deeply nested precedence declarations have higher priority than outer precedence declarations. So in the above example the final order of callin bindings will be: (`bl1, bl2, bl3`), because `bl2` is mentioned in the inner precedence declaration and thus comes before `bl3` which is mentioned only in the outer precedence declaration.

The compiler has been updated accordingly.

Callin in role with binding ambiguity
since 0.7 M4
316200

Previously, callin bindings in a particular situation would be flaged as illegal showing the following message:

Callin mapping not allowed here, because lifting to role TX.RY is not possible due to a reported binding ambiguity (OTJLD 4.1(b)).
A closer analysis revealed that despite lifting ambituity the callin could succeed in lifting if

1. a suitable role is already found in the cache (perhaps created explicitly), or
2. the actual base object has a type for which a specific role without binding ambiguity exists.

In order to support even such corner cases,

- Sections OTJLD §2.3.4(b) and OTJLD §4.1(b) have been extended
- The compiler message has been rephrased in a weaker way.
- A new warning token `"def-bind-ambiguity"` (definite binding ambiguity) has been introduced which can be used in a `@SuppressWarnings` annotation in order to silence that error.
  Additionally, option `Suppress optional errors with '@SuppressWarnings'` must be enabled in the Java Compiler preferences.
- The generated lift method has been changed to service case (1) above.

## Compiler

Warn about unused result
since 0.7 M2
310621

In an `after` callin binding where both methods declare a return type, users might expect the role method's result to be passed down to the original caller. However, `after` callin bindings may only look at the base method's result but never replace it with its own result. In order to alert users of this issue, a new warning has been introduced.

So this binding:

``int` foo() `<- after int` bar();`
Will yield this warning:
Callin after binding cannot return a value to the base caller, role method return value of type int will be ignored (OTJLD 4.4(a))
By contrast, the following declaration does not trigger the warning:
``void` foo() `<- after int` bar();`
If desired the warning can be suppressed using the token `"ignoredresult"`

## OT/Equinox

Aspect bindings for nested teams
since 0.7 M2
311109
311206

Previously, aspect bindings for nested teams could only be specified by using the internal name involving an ugly "$__OT__" prefix. Specifically, when selecting a nested team using the Browse button the resulting declaration would not work.

To fix these issues support has been added to OT/Equinox for interpreting the source and binary names of nested teams without the internal prefix, i.e., both

- `some.pack.OuterTeam.InnerTeam` and
- `some.pack.OuterTeam$InnerTeam`

will be understood by the OT/Equinox runtime.

Extension point for lifting participant
since 0.7
311081

The recently introduced concept of a lifting participant is now supported also within OT/Equinox. This is done using the new extension point `org.eclipse.objectteams.otequinox.liftingParticipant`. In any application at most one extension to this extension point is allowed. The extension must provide a class implementing `org.objectteams.ILiftingParticipant`.

## Object Teams Runtime Environment

Detect all system threads
since 0.7
316696

It was a long outstanding issue that per-thread (de)activation of teams could not correctly handle all system threads that are created before entering the `main` function. Only for the AWT-Event-Thread an incomplete workaround was implemented, which could print the following warning at runtime:

    Warning: Deactivation for the AWT-Event-Thread is not effective right now!

This problem could be resolved and the workaround is no longer used.