ObjectTeams/Java Language Definition

§3.1. Callout method binding

A role class may acquire the implementation for any of its (expected) methods by declaring a callout binding.

(a) Prerequisite: Class binding

A callout binding requires the enclosing class to be a role class bound to a base class according to §2.1.

(b) Definition

A callout binding maps an abstract role method ("expected method") to a concrete base method ("provided method"). It may appear within the role class at any place where feature declarations are allowed. It is denoted by

expected_method_designator "->" provided_method_designator;

The effect is that any call to the role method will be forwarded to the associated base object using the provided base method.

Example code:

 team class Company { 
    public class Employee playedBy Person { 
       abstract String getIdentification();	
       // callout binding see below...
    }
 }

A method designator may either be a method name

4	getIdentification -> getName;

or a complete method signature including parameter declarations and return type declaration, but excluding any modifiers.

4	String getIdentification() -> String getName();

Effects:

Line 4 declares a callout binding for the role method getIdentification(), providing an implementation for the abstract method defined in line 3.
In combination with the role binding in line 2 this has the following effect:
Any call to Emloyee.getIdentification is forwarded to the method Person.getName.

Both sides of a callout binding must use the same kind of designators, i.e., designators with and without signature may not be mixed.
Each method designator must uniquely select one method. For this selection method signatures must match exactly without any implicit conversions. If overloading is involved, signatures must be used to disambiguate.

(d) Inheritance of role method declarations

The role method being bound by a callout may be declared in the same class as the binding or it may be inherited from a super class or super interface.

(e) Callout override

If an inherited role method is concrete, callout binding regarding this method must use the token "=>" instead of "->" in order to declare that this binding overrides an existing implementation.
Using the "=>" operator for an abstract method is an error.
It is also an error (and not useful anyway) to callout-bind a method that is implemented in the same class as the binding.

(f) Inheritance of callout bindings

Callout bindings are inherited along explicit and implicit inheritance. Inherited callout bindings can be overridden using "=>".

(g) Duplicate bindings

It is an error if a role class has multiple callout bindings for the same role method.

(h) Declared Exceptions

It is an error if a base method to be bound by callout declares in its throws clause any exceptions that are not declared by the corresponding role method.

(i) Shorthand definition

A callout binding whose method designators specify full method signatures does not require an existing role method. If no role method is found matching the expected method of such a callout binding, a new method is implicitly generated. The new method has default visibility and none of the possible modifiers for methods are set. The new method declares the same exceptions as the bound base method.

A callout binding either attaches an implementation to a previously declared method or adds (3.1(i) above) a forwarding method to a role class. Apart from this implementation, callout-bound methods do not differ from regular methods.

When we say, a callout binding defines forwarding this means that control is passed to the base object. In contrast, by a delegation semantics control would remain at the role object, such that self-calls would again be dispatched starting at the role. Callout bindings on their own do not support delegation. However, in conjunction with method overriding by means of callin bindings (see §4.) the effect of delegation can easily be achieved.

§3.2. Callout parameter mapping

Syntax: §A.4.1

(a) with clause

If the method designators in a callout binding are signatures (not just method names), parameters and return value may be mapped by a with{...} sub-clause.

(b) Mapping one parameter

For each parameter of the provided base method, exactly one parameter mapping defines, which value will actually be passed to the base method. Callout parameter mappings have this form:

expression->base_method_parameter_name

The return value of a callout method may be provided by a result mapping:

"result" "<-" expression

The right hand side expression of a result mapping may use the special identifier result to refer to the value returned by the base method.
In a method binding with parameter mappings, it is an error to use result as the name of a regular method argument.

Example code:

1	Integer absoluteValue(Integer integer) -> int abs(int i) with {
2	integer.intValue() -> i,
3	result <- new Integer(result)
4	}

(d) Visible names

Each identifier that appears within the expressions of a parameter mapping must be either:

a feature visible in the scope of the role instance.
a parameter of the role method (for parameter mappings).
the special name result (for result mappings).

The names of base method arguments (i.e., names after mapping) are only legal in the position given in §3.2(b).

(e) Implicit parameter mappings

If parameter mappings should be omitted the following conditions must hold:

each method parameter of the role method must conform to the corresponding parameter of the base method, and
the result type of the base method must conform to the result type of the role method.

Here conformance includes translation polymorphism (cf. §3.3(d)).
Parameter correspondence without parameter mapping is determined by declaration order not by names.
Two adjustments can, however, be performed implicitly:

If the role method has more parameters than the base method, unused trailing parameters may be silently ignored.
If the role method returns void, any result from the base method may be silently ignored.

Example code:

 public team class MyTeamA {
   public class abstract Role1 {
     abstract void payEuro(float euro);
     abstract float earnEuro();
     void idle(int seconds) { /* do nothing */ };
   }
   Role1 boss, worker = // initialization omitted
   public void transaction () {
      boss.payEuro(worker.earnEuro());
      boss.idle(123);
   }
 }
 public class Staff { // a base class 
											
   public void payDM (float dm) { … };
   public float earnDM () { … };
   public int doze() { … };
   // other methods omitted
 }
 public team class MySubTeam extends MyTeamA {
   public class Role1 playedBy Staff {
     void payEuro(float euro) -> void payDM(float dm) with {
       euro * 1.95338f -> dm
     }
     float earnEuro() -> float earnDM () with {
       result <- result / 1.95338f
     }
     idle => doze // override existing implementation of idle()
   }
   void doit() {
      transaction();
   }
 }

Effects

Class MyTeamA is declaratively complete and can be type checked because it only uses methods that are visible or declared within this context. MyTeamA.Role1 can, however, not be instantiated, because it is abstract.
Line 30 has the normal effect of invoking transaction.
When executing transaction, the call of worker.earnEuro() is forwarded to the corresponding base object using method earnDM() (binding declaration in line 24). The result is converted by "result / 1.95338f" (line 25).
Within the same execution of transaction, the call of boss.payEuro() is forwarded to the corresponding base object using method payDM() (binding declaration in line 21). The parameter euro is converted by "euro * 1.95338f" (line 22).
Method idle is forwarded to doze without any parameter mapping. This requires doze to have a signature that is conformable to the signature of idle. In this case a role parameter and a base result are ignored.
Using the => operator, this binding overrides the existing implementation of idle.

If a callout binding shall bind to a private base method, that method must be defined in the exact base class to which the current role class is bound using playedBy. I.e., for private methods § 3.1(d) does not hold.
The same holds for private base fields (see below).
If a private base feature must indeed be callout-bound, a role class must be defined that is played by the exact base class defining the private feature. Another role bound to a sub-base-class can then be defined as a sub class of the first role. It will inherit the callout binding and through this it can access the desired feature.

public class SuperBase {
   private int secret;
}
public class SubBase extends SuperBase  { /* details omitted */ }
public team class MyTeam {
   protected class SuperRole playedBy SuperBase {
      int steal() -> get int secret; // OK
   }
   protected class SubRole extends SuperRole playedBy SubBase {
      int steal() -> get int secret;  // illegal!
   }
}

§3.5. Callout to field

Also fields of a base class can be made accessible using a callout binding.

(a) Syntax

Using one of the callout modifiers get or set a role method can be bound to a field of the role's base class:

1	getValue -> get value;
2	setValue -> set value;
3	int getValue() -> get int value;

where getValue, setValue are abstract role methods of appropriate signatures and value is a field of the bound base class.
A longer syntax is available, too (see line 3 above), which uses complete signatures. For the left hand side §3.1(c) applies, for the right hand side, this longer version prepends the field type to the field name.

(b) Compatibility

A role method bound with the modifier get should have no arguments (it may have arbitrary arguments, which are silently ignored) and should have a return type to which the base field is compatible. A role method returning void will ignore the given value and thus has no effect at all, which will be signaled by a compiler warning.
A role method bound with the modifier set must have a first argument that is compatible to the base field's type (additional arguments - if present - are silently ignored) and must not declare a return type.

Values can be mapped similar to parameter mappings in pure method bindings (§3.2). Such mappings can be used to establish compatibility as required above.
In both get and set bindings, the base side value is denoted by the field's name (lines 2 and 4 below).

1	Integer getValue() -> get int val
2	with { result <- new Integer(val) }
3	void setValue(Integer i) -> set int val
4	with { i.intValue() -> val }

(d) Effect

Callout-binding a role method to a base field generates an implementation for this role method, by which it acts as a getter or setter for the given field of the associated base object.

(e) Access control

For accessing an otherwise invisible field, the rules for decapsulation (§3.4) apply accordingly.
Recall, that according to JLS 8.3 fields may be hidden in sub-classes of a given base class. Therefore, it is relevant to know that a callout to a field will always access the field that is visible in the exact base class of the role class defining the callout. This is especially relevant for accessing private fields.

(f) Shorthand definition

Just as in §3.1(i) a shorthand definition allows to introduce a callout field access method without prior abstract declaration. This requires the callout field binding to specify types as in line 3 of (a) "Syntax" above.

(g) Callout override

Similar to method callouts a callout to field may override an existing role method if and only if the token => is used instead of -> (see §3.1(e) and §3.1(f)).


callout binding	A callout binding declares that a method call to a role object may be forwarded to a base method of the associated base object (the role object "calls out" to the base).

declarative completeness	Even if a role class does not implement all needed methods, but forwards some to its base, also these methods must be declared within the role. Secondly, no forwarding occurs, unless explicitly declared by a callout binding.

expected/provided	A callout binding binds an expected method of the role class (needed but not implemented here) to a provided method of the base class.

`-nodecapsulation`	No warnings.
default	Warn only if/that access restrictions are overridden.
`-decapsulation`	Detailed messages containing the binding and the hidden base method.

ObjectTeams/Java Language Definition - §3.

Notion of callout binding

§3.1. Callout method binding

Example code:

Effects:

§3.2. Callout parameter mapping

Example code:

Example code:

Effects

§3.3. Lifting and lowering

§3.4. Overriding access restrictions

§3.5. Callout to field