ObjectTeams/Java Language Definition - §6.
 
 
 
  §5. Team activation   Table of  Contents §7. Role encapsulation 
§6. Object Teams API

The role of predefined types and methods

Application Program Interface (API) Some features of ObjectTeams/Java are supported without introducing new syntax but by predefined types and methods.
 

§6.1. Reflection

Object Teams supports reflection with respect to teams, roles, and role-base relationships.
 (a) Interface to the role registry
Each team instance internally has a registry of known role objects indexed by their base object. Programmers may make use of this registry using the following reflective methods defined in org.objectteams.Team:
boolean hasRole ( Object aBase ) ;
This method checks whether a role for the passed base object already exists in the target team.
boolean hasRole ( Object aBase, Class expectedRole ) ;
This method checks whether a instance of type expectedRole as a role for the passed base object aBase already exists in the target team. The role may also be of any subtype of the specified role type.
Object getRole ( Object aBase ) ;
If the passed base object aBase already has a role in the target team, this role is returned. Otherwise null is returned.
Object getRole ( Object aBase, Class expectedRole ) ;
If the passed base object aBase already has a role of type expectedRole in the target team, this role is returned. Otherwise null is returned.
Object[] getAllRoles () ;
Retrieves all existing (registered) roles in the target team.
This method uses internal structures of weak references. For that reason it may return role instances which were about to be reclaimed by the garbage collector. If performance permits, it is thus advisable to always call System.gc() prior to calling getAllRoles() in order to achieve deterministic results (see also §2.1(f)).
Object[] getAllRoles ( Class expectedRole ) ;
Retrieves all existing (registered) roles of type expectedRole in the target team. Class expectedRole must be a top-most bound role, ie., it must have a playedBy clause and no regular super class with a playedBy clause.
Note, that the returned array is actually an array of Object, ie., elements have to be cast to exepctedRole individually.
See the note about garbage collection above.
void unregisterRole ( Object aRole ) ;
This method unregisters the passed role object from the target team. Thus the corresponding base looses this role. After calling this method the role should no longer be used.
void unregisterRole ( Object aRole, Class roleClass ) ;
This method unregisters the passed role object from the target team. Thus the corresponding base looses this role. After calling this method the role should no longer be used. The only difference to the previous method is improved speed because no search for the corresponding registry has to be performed.
It is desirable and possible to use these methods within guards (see §5.4.). These methods allow to write the specification of guards in a more concise and more expressive way. Determined by the signature, the first four methods can only be used in a base-level guard (§5.4.2) because they require a reference to a base object.

Example code:

1 
 public team class SpecialConditions {
2 
    public void participate(Account as BonusAccount ba) {}
3 
    public class BonusAccount playedBy Account
4 
       base when(SpecialConditions.this.hasRole(base, BonusAccount.class))
5 
    {
6 
       callin void creditBonus(int amount) {
7 
          base.creditBonus(amount + bonus);
8 
       }
9 
       void creditBonus(int amount) <- replace void credit(int i)
10 
          base when (i > 1000);
11 
    }
12 
 }

Effects:

    This teams provides a bonus system for registered Accounts. Every time an amount of more than 1000 is deposited to a registered account, additional 1% of the amount is credited.
  • The team level methode partipate in line 2 uses declared lifting (see §2.3.2) to allow the passed Account object to participate the bonus system provided by the SpecialConditions team.
  • The base guard in line 4 uses the reflective method hasRole to check whether the base object already has a role of type BonusAccount in the surrounding team. The expression BonusAccount.class returns the java.lang.Class object representing the role BonusAccount (see JLS §15.8.2). This guard ensures, that only accounts explicitly registered via participate are ever decorated with a role of type BonusAccount.
  • The method binding guard in line 10 restricts the callin to creditBonus to calls where the base method argument amount is greater than 1000.
 (b) Behavioral reflection
The following reflective methods defined in org.objectteams.Team can be used to inspect the dynamic behavior of a team:
boolean isExecutingCallin () ;
This method is used to inspect whether a control flow has already been intercepted by at least one callin binding of the current team. It can be used to avoid undesirable re-entrance to a team.
boolean isActive () ;
This method checks whether the team instance is active for the current thread.
boolean isActive ( Thread aThread ) ;
This method checks whether the team instance is active for the thread aThread.
 (c) Class literals for roles
The Java syntax for so-called class literals, MyClass.class (see JLS §15.8.2) can be used for role types with slightly changed semantics: Role types are virtual types (§1.3.1) that are bound dynamically (§1.3.1(e)). This applies to role class literals, too. From this follows the constraint that a role class literal can only be used within the non-static context of a team, ie., for evaluating a role class literal an enclosing team instance must be in scope.
Unlike regular type checking for role types, the class literal itself does not have a dependent type. Thus type checking of calls to methods like hasRole(Object,Class) cannot detect, whether the Class instance has actually been obtained from the correct team instance. Any attempt to pass a class that is not known as a bound role within the given team results in an IllegalArgumentException at run-time.
 

§6.2. Other API Elements

 (a) Interfaces for role encapsulation
A set of pre-defined types exist that do not extend java.lang.Object and have no features except the operators == and !=.
Note: The JLS defines that each interface declares all methods defined in java.lang.Object (JLS §9.2) and also each object referenced by an interface type can be widened to java.lang.Object. Compilers commonly implement this by declaring java.lang.Object the super-type of all interfaces. Such implementation has no visible difference with respect to the more complex definition in the JLS.
These predefined types are
regular interface org.objectteams.IConfined
role interface org.objectteams.Team.IConfined
role class org.objectteams.Team.Confined

These types provide no new functionality but inheriting from these types influences the semantics with respect to encapsulation. The purpose and usage of these types is described in §7.

 (b) Interface for explicit lowering
The following role interface exists for the purpose of allowing explicit lowering:
role interface   org.objectteams.Team.ILowerable

This interface was introduced in detail in §2.2(d).

 (c) Team activation methods
Every team can be activated and deactivated by predefined methods of the class org.objectteams.Team.
Methods for activation of a team: activate() and activate(Thread th)
Methods for deactivation of a team: deactivate() and deactivate(Thread th)

The usage of these Methods is described in §5.2(b).

 (d) Exceptions
The following Exceptions can be thrown during the execution of an ObjectTeam/Java program:
ResultNotProvidedException
Thrown if a replace callin without a base call does not provide the necessary (primitive type) base result (see §4.3(e)).
LiftingFailedException
Thrown if an actual ambiguity occurs during lifting (see §2.3.4(c)).
WrongRoleException
Thrown during lifting if the base object has, with respect to the same team instance, previously been lifted to a role type that is not conform to the currently requested type (see §2.3.4(d) and §2.4.3).
DuplicateRoleException
Thrown during explicit role creation, if a new role is created for a base object, which already has a role of the required type in the given team (see §2.4.1(c)).
RoleCastException
Thrown during cast of an externalized role, if the casted expression is anchored to a different team instance than the cast type (see §1.2.4(b)).


  §5. Team activation   Table of  Contents §7. Role encapsulation 
© Stephan Herrmann, Christine Hundt
OT/J Version 1.0 — Last modified: Fri Mar 30 2007