ObjectTeams/Java Language Definition - §1.

A role class must have exactly one of the access modifiers public or protected.

A protected role can only be accessed from within the enclosing team or any of its sub-teams. The actual border of encapsulation is the enclosing team instance. The rules for protected roles are given in §1.2.3 below.

Only public roles can ever be accessed outside their enclosing team. Accessing a role outside the enclosing team instance is governed by the rules of externalized roles, to be defined next (§1.2.2).

A role class has to be marked abstract if any of its methods is not effective.
The methods of a role class comprise direct methods and methods acquired by inheritance. In addition to regular inheritance a role class may acquire methods also via implicit inheritance (§1.3.1).
A method may become effective by either:

• implementation (i.e., a regular method body), or
• a callout binding (see §3.).

§2.5 will discuss under which circumstances abstract roles force the enclosing team to be abstract, too.

Access modifiers for members of roles have some special interpretation:

1. A private member is also visible in any implicit sub role (see implicit inheritance §1.3.1(c)).
   In contrast to inner classes in Java, private members of a role are not visible to the enclosing team.
2. The default visibility of role members restricts access to the current class and its sub-classes (explicit and implicit).
3. protected role members can be accessed from the enclosing team only.
4. public role members grant unrestricted access.

Only public members can ever be accessed via an externalized role.

In contrast to inner classes in pure Java, a role class may indeed define static methods. A static role method requires no role instance but it still requires a team instance in scope. Static role methods can be called:

• from the enclosing team,
• via callin (see §4.7).

Within a static role method the syntax MyTeam.this is available for accessing the enclosing team instance.

A static field of a role class must not have a non-constant initialization expression. Static initialization blocks are already prohibited for inner classes by Java.

Note, that already two levels of initialization are performed prior to role instantiation: static initialization of the (outer most) enclosing team class and instantiation of the enclosing team(s). Static initialization of a role class would add nothing new to this.

Only instances of a public role class can ever be externalized.

Outside a team role types are legal only if denoted relative to an existing team instance (further on called "anchored types"). The syntax is: In the syntax anchor.Type the expression to the left of the dot can be a simple name or a path. It must refer to an instance of a team class, the type at the right hand side of the dot must be the simple name of a role directly contained in the given team (including roles that are acquired by implicit inheritance).
Note: The syntax presented in this section is no longer recommended. Section §9.2.1 defines an alternative syntax for anchored types, which is more versatile. Generally, any anchored type myTeam.RoleClass can also be written as RoleClass<@myTeam>.

Anchoring the type of an externalized role to a team instance requires the team to be referenced by a variable which is marked final (i.e., immutable). The type anchor can be a path v.f1.f2... where v is any final variable and f1 ... are final fields.

The current team instance can be used as a default anchor for role types:

1. In non-static team level methods role types are by default interpreted as anchored to this (referring to the team instance). I.e., the following two declarations express the same:
   public RoleX getRoleX (RoleY r) { stmts }
   public this.RoleX getRoleX (this.RoleY r) { stmts }
2. In analogy, role methods use the enclosing team instance as the default anchor for any role types.

Note, that this and Outer.this are always final.
The compiler uses the pseudo identifier tthis to denote such implicit type anchors in error messages.

Conformance between two types teamA.RoleX and teamB.RoleY not only requires the role types to be compatible, but also the team instances to be provably the same object. The compiler must be able to statically analyze anchor identity.

Only two substitutions are considered for determining team identity:

1. For type checking the application of team methods, this is substituted by the actual call target. For role methods a reference of the form Outer.this is substituted by the enclosing instance of the call target.

2. Assignments from a final identifier to another final identifier are transitively followed, i.e., if t1, t2 are final, after an assignment t1=t2 the types t1.R and t2.R are considered identical. Otherwise t1.R and t2.R are incommensurable.
   Attaching an actual parameter to a formal parameter in a method call is also considered as an assignment with respect to this rule.

Anchored types for externalized roles may be used in the following contexts:

1. Declaration of an attribute
2. Declaration of a local variable
3. Declaration of a parameter or result type of a method or constructor
4. In the playedBy clause of a role class (see §2.1).

It is not legal to inherit from an anchored type, since this would require membership of the referenced team instance, which can only be achieved by class nesting.

Creating a role as externalized using the syntax
requires the enclosing instance outer to be declared final. The expression has the type outer.Role following the rules of externalized roles.
The type Role in this expression must be a simple (unqualified) name.

It is neither useful nor legal to import a role type. Note that outside their team role types can only be used relative to a type anchor, which implicitly grants access to all its public roles.

 team class FlightBonus extends Bonus {

   public class Subscriber {

     void clearCredits() { ... };

   }

   void unshow(this.Subscriber subscr) { ... }

 }

 class ClearAction extends Action {

   final FlightBonus context;

   context.Subscriber subscriber;

   ClearAction (final FlightBonus bonus,

                bonus.Subscriber subscr) {

     context    = bonus;   // unique assignemt to 'context'

     subscriber = subscr;

   }

   void actionPerformed () {

     subscriber.clearCredits();

   }

   void finalize () {

     context.unshow(subscriber);

   }

 }

It is not allowed to import a protected role class.

The name of a protected role class may not be used qualified, neither by its enclosing type nor by a variable as type anchor. I.e., it may never appear right of a dot (".") (cf. §1.2.2(a)).

An externalized role type is never compatible to an unqualified role type, except for the substitutions in §1.2.2(f), where an explicit anchor can be matched with the implicit anchor this.

Since protected role types can not be used for externalization, instances of these types are already quite effectively encapsulated by their enclosing team. Based on this concept, encapsulation for protected roles can be made even stricter by the rules of role confinement. On the contrary, even protected roles can be externalized as opaque roles which still expose (almost) no information. Confinement and opaque roles are subject of §7.

For role types the instanceof operator yields true only if both components of the type match: the dynamic role type must be compatible to the given static type, and also type anchors must be the same instance.

Casts may also fail, if the casted expression is anchored to a different team instance than the cast type. Such failure is signaled by a org.objectteams.RoleCastException.

In the directory of the team class a new directory is created which has the same name as the team without the .java suffix.

Role classes are stored in this directory (a). The file names are derived from the role class name extended by .java.
A role file must contain exactly one top-level type.

A role class in a role file declares as its package the fully qualified name of the enclosing team class. The package statement of a role file must use the team modifier as its first token.

A team should mention in its javadoc comment each role class which is stored externally using a @role tag.

The type in a role file must not be an enum.

 package org.objectteams.examples;

 public team class MyTeamA {

   /**

    * @author Stephan Herrmann

    * @date 20.02.2002

    * @file MyTeamA.java

    * @role MyRole

    */

   ... 

 }

 team package org.objectteams.examples.MyTeamA;

 public class MyRole { 

   ...

 }

 public team class S {

   protected class R0 {...}

   protected class R1 extends R0 {

     boolean ok;

     R2 m() {...}

     void n(R2 r) {...}

   }

 }

   protected class R2 {...}

 }

 public team class T extends S {

   protected class R1 {

     R2 m() {

       if(ok) { return tsuper.m(); }

       else { return null; }

     }

     void doIt() {

       n(m());

     }

   }

 }

A team T which extends a super-team S has one role class T.R corresponding to each role S.R of the super-team. The new type T.R overrides R for the context of T and its roles. Acquisition of role classes can either be direct (see (b) below), or it may involve overriding and implicit inheritance ((c) below).

In the above example the team S operates on types S.R0, S.R1 and S.R2, while T operates on types T.R0, T.R1 and T.R2.

Within a sub-team T each role S.R of its super-team S is available by the name T.R without further declaration. In the lexical context of T also the short name R refers to the role T.R.

The role R2 can be used in the sub-team T (line 13), because this role type is defined in the super class of the enclosing team.

If a team contains a role class definition by the same name as a role defined in its super-team, the new role class overrides the corresponding role from the super-team and implicitly inherits all of its features. Such relation is established only by name correspondence.
It is an error to override a role class with an interface or vice versa. A final role cannot be overridden.
Unlike regular inheritance, constructors are also inherited along implicit inheritance, and can be overridden just like normal methods.

R1 in T implicitly inherits all features of R1 in S. This is, because its enclosing team T extends the team S (line 11) and the role definition uses the same name R1 (line 12). Hence the attribute ok is available in the method m() in T.R1 (line 14).

Direct acquisition of roles from a super-team and implicit inheritance do not establish a subtype relation. A role of a given team is never conform (i.e., substitutable) to any role of any other team. S.R and T.R are always incommensurable.
Note, that this rule is a direct consequence of §1.2.2(e).

Overriding an acquired role by a new role class has the following implication: If an expression or declaration, which is evaluated on behalf of an instance of team T or one of its contained roles, refers to a role R, R will always resolve to T.R even if R was introduced in a super-team of T and even if the specific line of code was inherited from a super-team or one of its roles. Only the dynamic type of the enclosing team-instance is used to determine the correct role class (see below for an example).

A special case of dynamically binding role types relates to so-called class literals (see JLS 15.8.2). Role class literals are covered in §6.1(c).

The above is strictly needed only for cases involving implicit inheritance. It may, however, help intuition, to also consider the directly acquired role T.R in (b) to override the given role S.R.

In line 18 the implicitly inherited method n is called with the result of an invocation of m. Although n was defined in S (thus with argument type S.R2, see line 6) in the context of T it expects an argument of T.R2. This is correctly provided by the invocation of m in the context of T.

Super calls along implicit inheritance use the new keyword tsuper. While super is still available along regular inheritance, a call tsuper.m() selects the version of m of the corresponding role acquired from the super-team.

See § 2.4.2 for tsuper in the context of role constructors.

tsuper can only be used to invoke a corresponding version of the enclosing method or constructor, i.e., an expression tsuper.m() may only occur within the method m with both methods having the same signature (see §2.3.2(b) for an exception, where both methods have slightly different signatures).

R1 in T overrides the implicitly inherited method m() from S.
tsuper.m() calls the overridden method m() from S.R1 (line 14).

If a role class has an explicit super class (using extends) this relation is inherited along implicit inheritance.

The role R1 in T has T.R0 as its implicitly inherited super class, because the corresponding role in the super-team extends R0 (line 3).

Overriding an implicitly inherited super class is governed by §1.3.2b, below.
The list of implemented interfaces is merged along implicit inheritance.

A role class must provide at least as much access as the implicit super role, or a compile-time error occurs (this is in analogy to JLS 8.4.6.3). Access rights of methods overridden by implicit inheritance follow the same rules as for normal overriding.

When creating a role instance using new not only the type to instantiate is bound dynamically (cf. (e)), but also the constructor to invoke is dynamically bound in accordance to the concrete type.
Within role constructors all this(..) and super(..) calls are, however, bound statically with respect to explicit and implicit inheritance.
See also §2.5(a) on using constructors of abstract role classes.

The rules of JLS 8.4.6 also apply to methods and constructors inherited via implicit inheritance.

 public team class MyTeamA {

   protected class MyRole {

     String name;

     public MyRole (String n) { name = n; }

     public void print()     { System.out.println("id="+name); }

   }

   public MyRole getRole()  { return new MyRole("Joe"); }

 }

 public team class MySubTeam extends MyTeamA {

   protected class MyRole {

     int age;

     public void setAge(int a) { age = a; }

     public void print() { 

       tsuper.print();

       System.out.println("age="+age);

     }

   }

   public void doit() {

     MyRole r = getRole();

     r.setAge(27);

     r.print();

   }

 }

 ...

 MySubTeam myTeam = new MySubTeam();

 myTeam.doit();

 id=Joe

 age=27

If the super-class of a role is again a role it must be a role of an enclosing team.
This rule is simply enforced by disallowing type anchors in the extends clause (see §1.2.2(g)).
As an effect, the super class may only see fewer enclosing instances, never more.

If a role overrides another role by implicit inheritance, it may change the inherited extends clause (see 1.3.1(g) above) only if the new super-class is a sub-class of the class in the overridden extends clause. Ie., an implicit sub-role may specialize the extends clause of its implicit super-role.

Each constructor of a role class that overrides the extends clause of its implicit super-role must invoke a constructor of this newly introduced explicit super-class. Thus it may not use a tsuper constructor (see §2.4.2).

implements declarations are additive, i.e., an implicit sub-role may add more interfaces but has to implement all interfaces of its implicit super-role, too.