§2 Role Binding

(a) No role of the same team

The base class of any role class must not be a role of the same team.
It is also not allowed to declare a role class of the same name as a base class bound to this or another role of the enclosing team, if that base class is given with its simple name and resolved using a regular import. Put differently, a base class mentioned after playedBy may not be shadowed by any role class of the enclosing team.
Base imports as defined below (§2.1.2.(d)) relax this rule by allowing to import a class as a base class only. In that case no shadowing occurs since the scopes for base classes and roles are disjoint.

(b) No cycles

The base class mentioned after playedBy may not be an enclosing type (at any depth) of the role class being defined.
This rule prohibits the creation of cycles where the base instance of a given role R contains roles of the same type R.
More generally any sequence of classes C1, C2, .. Cn were each Ci+1 is either a member or the base class of Ci and Cn = C1 is forbidden.
Conversely, it is also prohibited to bind a role class to its own inner class.

(c) Base class decapsulation

If a base class referenced after playedBy exists but is not visible under normal visibility rules of Java, this restriction may be overridden. This concept is called decapsulation, i.e., the opposite of encapsulation (see also §3.4). A compiler should signal any occurrence of base class decapsulation. If a compiler supports to configure warnings this may be used to let the user choose to (a) ignore base class decapsulation, (b) treat it as a warning or even (c) treat it as an error.
Decapsulation is not allowed if the base class is a confined role (see §7.2).
Within the current role a decapsulated base class can be mentioned in the right-hand-side of any method binding (callout (§3) or callin (§4)). Also arguments in these positions are allowed to mention the decapsulated base class:

• the first argument of one of the role's constructors (see lifting constructor (§2.4.1)).
• the base side of an argument with declared lifting (see declared lifting (§2.3.2)).

(d) Base imports

If the main type in a file denotes a team, the modifier base can be applied to an import in order to specify that this type should be imported for application as a base type only. Example:

import base some.pack.MyBase;

public team class MyTeam {

  // simple name resolves to imported class:

  protected class MyRole playedBy MyBase { } 

  MyBase illegalDeclaration; // base import does not apply for this position

}

Types imported by a base import can only be used in the same positions where also base class decapsulation (§2.1.2.(c)) is applicable.
It is recommended that a type mentioned after the keyword playedBy is always imported with the base modifier, otherwise the compiler will give a warning.
Base imports create a scope that is disjoint from the normal scope. Thus, names that are imported as base will never clash with normally visible names (in contrast to §1.4). More specifically, it is not a problem to use a base class's name also for its role if a base import is used.

(e) No parameterized base class

It is not possible to specify a parameterized type as a role's base class. If a class to be bound as base class is generic the raw type must be used instead.

(a) Reuse of existing role objects

A role object is considered suitable for reuse during lifting, if these three items are identical:

1. the given base object
2. the given team object
3. the statically required role type

For the relation between the statically required role type and the actual type of the role object see "smart lifting" (§2.3.3).

(b) Default lifting constructor

Lifting uses a default constructor which takes exactly one argument of the type of the declared base class (after playedBy). By default the compiler generates such a constructor for each bound role. On the other hand, default constructors that take no arguments (as in JLS §8.8.7) are never generated for bound roles.
The super-constructor to be invoked by a default lifting constructor depends on whether the role's super class is a bound role or not.

• If the super-class is a bound role, the default lifting constructor will invoke the default lifting constructor of the super-class.
• If the super-class is not a bound role, the default lifting constructor will invoke the normal argumentless default constructor of the super-class.

(c) Custom lifting constructor

If a role class declares a custom constructor with the same signature as the default lifting constructor, this constructor is used during lifting. This custom constructor may pre-assume that the role has been setup properly regarding its base-link and registered in the team's internal map of roles.
If a bound role has an unbound super-class without an argumentless constructor, providing a custom lifting constructor is obligatory, because no legal default lifting constructor can be generated.

(a) Parameters with declared lifting

A non-static team-level method or constructor may declare a parameter with two types in order to explicitly denote a place of lifting. Using the syntax

public void m (BaseClass as RoleClass param) { stmts }

a liftable parameter can be declared, provided the second type (RoleClass) is a role of (playedBy) the first type (BaseClass). Furthermore, the role type must be a role of the enclosing team class defining the given method. The role type must be given by its simple (i.e., unqualified) name.
Such a signature requires the caller to provide a base object (here BaseClass), but the callee receives a role object (here RoleClass). In fact, the client sees a signature in which the "as RoleClass" part is omitted.
Compatibility between caller and callee sides is achieved by an implicitly inserted lifting translation. A signature using declared lifting is only valid, if the requested lifting is possible (see §2.3.3 and §2.3.4 for details).

(b) Super in the context of declared lifting

Calling super or tsuper in a method or constructor which declares lifting for one or more parameters refers to a method or constructor with role type parameters, i.e., lifting takes place before super invocation. Nevertheless, the super method may also have a declared lifting signature. It will then see the same role instance(s) as the current method.

(c) Declared lifting of arrays

If a parameter involving explicit lifting should be of an array type, the syntax is

public void m (BaseClass as RoleClass param[]) ...

Here the brackets denoting the array apply to both types, BaseClass and RoleClass.

(d) Declared lifting for catch blocks

Also the argument of a catch block may apply declared lifting like in:

catch (BaseException as RoleClass param) { stmts }

This syntax is only valid in a non-static scope of a team (directly or nested). In the given example, RoleClass must be played by BaseException. Note, that RoleClass itself need not be a throwable. As the effect of this declaration the catch block will catch any exception of type BaseException and provides it wrapped with a RoleClass instance to the subsequent block.
Also note, that re-throwing the given instance param has the semantics of implicitly lowering the role to its base exception before throwing, because the role conforms to the required type Throwable only via lowering.

(a) Static adjustment

If a base class B shall be lifted to a role class R that is not bound to (playedBy) B, but if a subclass of R — say R2 — is bound to B, lifting is statically setup to use R2, the most general subclass of R that is bound to B or one of its super-types.

(b) Dynamic selection of a role class

At runtime also the dynamic type of a base object is considered: Lifting always tries to use a role class that is bound to the exact class of the base object. Lifting considers all role–base pairs bound by playedBy such that the role class is a sub-class of the required (statically declared) role type and the base class is a super-class of the dynamic type of the base object.
From those possible pairs the most specific base class is chosen. If multiple role classes are bound to this base class the most specific of these classes is chosen.

(c) Team as closed world

In the above analysis gathering all role-base pairs is performed at compile-time. From this follows, that a team class can only be compiled when all its contained role classes are known and a role class can never be compiled without its team.
The analysis includes all roles and their bindings that are inherited from the super-team.

(d) Selection regardless of abstractness

Smart lifting is not affected by abstractness of role classes. For the effect of abstract role classes see §2.5.

(a) Potential ambiguity

A potential ambiguity is given, if two role classes R1 and R2 exist such that

• R1 and R2 are played by the same base class B, and
• R1 and R2 have a common super role R0, which is also bound to a base class B0, and
• neither role class R1 nor R2 is a (indirect) sub-class of the other.

In the above situation, trying to lift an instance of type B to the role type R0 is an illegal lifting request. If R0 is bound to the same base class B as its sub-roles R1 and R2 are, role R0 is unliftable, meaning that no instance of R0 can ever by obtained by lifting.

Example code (Potential Ambiguity):

team class MyTeam {

  public class SuperRole playedBy MyBase {...}

  public class SubRoleA extends SuperRole {...}

  public class SubRoleB extends SuperRole {...}

}

(b) Definite ambiguity

A definite ambiguity is given if

• the situation of potential ambiguity according to (a) above is given and
• lifting is requested (either by method binding or explicitly (§2.3.2)) from the shared base class B to any role class R0 that is a common super role for R1 and R2.

Example code (Definite Ambiguity):

team class MyTeam {

  public class SuperRole playedBy MyBase {...}

  public class SubRoleA extends SuperRole playedBy SubBase {...}

  public class SubRoleB extends SuperRole playedBy SubBase {...}

  public void useSuperRole(SubBase as SuperRole r) {...}

}

(c) Actual ambiguity

At runtime actual ambiguity may occur if for the dynamic type of a base to be lifted the conditions of (b) above hold accordingly. Actual ambiguity is only possible in cases reported by the compiler as potential ambiguity.

Example code (Actual Ambiguity):

team class MyTeam {

  public class SuperRole playedBy MyBase {...}

  public class SubRoleA extends SuperRole playedBy SubBase {...}

  public class SubRoleB extends SuperRole playedBy SubBase {...}

  public void useSuperRole(MyBase as SuperRole r) {...}

}

// plus these calls:

MyTeam mt = new MyTeam();

mt.useSuperRole(new SubBase());

(d) Mismatching role

In cases of potential ambiguity another runtime error may occur: a mismatching role is encountered when a role is found in the cache, which is not conform to the required type. This happens, if the base object has previously been lifted to a type that is incompatible with the currently requested type.

Example code (Mismatching Role):

team class MyTeam {

  public class SuperRole playedBy MyBase {...}

  public class SubRoleA extends SuperRole {...}

  public class SubRoleB extends SuperRole {...}

  public void useRoleA(MyBase as SubRoleA r) {...}

  public void useRoleB(MyBase as SubRoleB r) {...}

}

// plus these calls:

MyTeam mt = new MyTeam();

MyBase b = new MyBase();

mt.useRoleA(b); // creates a SubRoleA for b

mt.useRoleB(b); // finds the SubRoleA which is not compatible

                // to the expected type SubRoleB.

From the second item of §2.3.4.(a) follows, that for binding ambiguities different role hierarchies are analyzed in isolation. For this analysis only those role classes are considered that are bound to a base class (directly using playedBy or by inheriting this relation from another role class). I.e., two role classes that have no common bound super role will never cause any ambiguity.

(a) Team context

The lifting constructor can be used only within the enclosing team of the role to be instantiated. Thus, qualified allocation expressions (someTeam.new SomeRole(..)) may never use the lifting constructor.

(b) Fresh base object

If the argument to a lifting constructor invocation is a new expression, creating a fresh base object, the use of the lifting constructor is safe. Otherwise the rules of (c) below apply.

(c) Duplicate role runtime check

If it cannot be syntactically derived, that the argument to a lifting constructor is a freshly created base object (b), a compile time warning will signal that an additional runtime check is needed: It must be prevented that a new role is created for a base object, which already has a role of the required type in the given team. It is not possible to replace an existing role by use of the lifting constructor. At runtime, any attempt to do so will cause a org.objectteams.DuplicateRoleException to be thrown. This exception can only occur in situations where the mentioned compile time warning had been issued.
§6.1 will introduce reflective functions which can be used to manually prevent errors like a duplicate role.

(a) Unbound roles

Each constructor of a role that is not bound to a base class must use one of this(..), super(..) or tsuper(..).

(b) Bound roles

Each constructor of a bound role must directly or indirectly invoke either a base(..) constructor or a lifting constructor (see §2.3.1). Indirect calls to the base constructor or lifting constructor may use any of this(..), super(..) or tsuper(..), which simply delegates the obligation to the called constructor.
If a constructor referenced by base(..) is not visible according to the regular rules of Java, it may still be called using decapsulation (see also §3.4, §2.1.2.(c)).
Note, that if the super or tsuper role is not bound, delegating the obligation to that unbound role will not work.

(c) Super-call for bound roles

Instead of or prior to calling base(..) a constructor of a bound role explicitly or implicitly calls a super constructor. Which constructor is applicable depends on the super role and its playedBy clause.

• If the super role is bound to the same base class as the current role is,
  • not writing a super-call causes the lifting constructor of the super role to be invoked.
  • explicitly calling a super constructor requires the super constructor to either
    1. create a role instance using a base constructor call (directly or indirectly), or
    2. be a lifting constructor receiving a base instance, which the current role must provide as the argument.
• If the super role is bound but the current role refines the playedBy relationship (cf. §2.1.(c)),
  • a lifting constructor must be called explicitly passing a base object as the argument.
• If the role has an explicit or implicit super role which is unbound the constructor may optionally call a super constructor (using super(..) or tsuper(..)) prior to calling base(..). Otherwise the default constructor is implicitly invoked.

When invoking a lifting constructor of a super role the base object can optionally be obtained by using a base constructor call as an expression:

super(base(<args>));