blob: b693c3b392ce089883c1e4640415d8068b1e96b1 [file] [log] [blame]
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "../xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<link rel="stylesheet" type="text/css" href="../css/ot.css" />
<link rel="stylesheet" type="text/css" href="../css/otjld.css" />
<title>OT/J Language Definition v1.3.1</title>
</head>
<body class="otdt">
<div id="content">
<table class="nav">
<tr>
<td class="back"><a id="top"></a><a href="s2.html" rel="prev">&lt;&lt;&nbsp;&sect;2&nbsp;Role Binding</a></td>
<td class="top"><a href="index.html" rel="contents">&uarr;&nbsp;Table of Contents&nbsp;&uarr;</a></td>
<td class="next"><a href="s4.html" rel="next">&sect;4&nbsp;Callin Binding&nbsp;&gt;&gt;</a></td>
</tr>
</table>
<div class="chapter" id="s3">
<div class="headl">
<div class="headr">
<h1>&sect;3&nbsp;Callout Binding</h1>
</div>
</div>
<div id="toc-box">
<ul class="toc-box">
<li><a href="s3.html">&sect;3&nbsp;Callout Binding</a></li>
<li><a href="#s3.1">&sect;3.1&nbsp;Callout method binding</a></li>
<li><a href="#s3.2">&sect;3.2&nbsp;Callout parameter mapping</a></li>
<li><a href="#s3.3">&sect;3.3&nbsp;Lifting and lowering</a></li>
<li><a href="#s3.4">&sect;3.4&nbsp;Overriding access restrictions</a></li>
<li><a href="#s3.5">&sect;3.5&nbsp;Callout to field</a></li>
</ul>
</div>
<div class="intro">
<h3>Notion of callout binding</h3>
<div class="line"></div>
<div class="term">callout binding</div>
<div class="termdesc">A callout binding declares that a method call to a role
object may be <strong>forwarded</strong> to a base method of the associated
base object <em>(the role object "calls out" to the base)</em>.
</div>
<div class="line"></div>
<div class="term">declarative completeness</div>
<div class="termdesc"> 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.
</div>
<div class="line"></div>
<div class="term">expected/provided</div>
<div class="termdesc"> A callout binding binds an <strong>expected</strong> method of the role
class (needed but not implemented here) to a <strong>provided</strong>
method of the base class.
</div>
<div class="line"></div>
</div>
<div class="sect depth2" id="s3.1">
<h2 class="sect">&sect;3.1&nbsp;Callout method binding<a class="img" href="s3.html#s3.1"
title="PermaLink to &sect;3.1&nbsp;Callout method binding"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#top">&uarr;&nbsp;&sect;3</a></span></h2>
<div class="syntaxlink"><a href="sA.html#sA.3.2" title="&sect;A.3.2&nbsp;CalloutBinding"
class="syntax">&rarr;&nbsp;Syntax&nbsp;&sect;A.3.2</a></div>
<p>A role class may acquire the implementation for any of its
(expected) methods by declaring a <strong>callout</strong> binding.
</p>
<div class="subsect depth3" id="s3.1.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Prerequisite: Class binding</span><a class="img" href="s3.html#s3.1.a"
title="PermaLink to (a)&nbsp;Prerequisite: Class binding"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>A callout binding requires the enclosing class to be a role class
bound to a base class according to <a href="s2.html#s2.1" title="&sect;2.1&nbsp;playedBy relation" class="sect">&sect;2.1</a>. However, callout bindings are not
allowed if the role is involved in base class circularity (see <a href="s2.html#s2.1.2.b" title="&sect;2.1.2.(b)&nbsp;Cycles" class="sect">&sect;2.1.2.(b)</a>).
</p>
</div>
<div class="subsect depth3" id="s3.1.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Definition</span><a class="img" href="s3.html#s3.1.b" title="PermaLink to (b)&nbsp;Definition"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>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
</p>
<div class="listing plain"><pre><i>expected_method_designator</i> <b>-&gt;</b> <i>provided_method_designator;</i></pre></div>
<p>The effect is that any call to the role method will be forwarded to the
associated base object using the provided base method.
</p>
<h5 class="listing">Example code (Callout):</h5>
<div class="listing example frame">
<table class="listing">
<tr class="line odd">
<td class="ln">1</td>
<td><pre><b>team</b> <b>class</b> Company {</pre></td>
</tr>
<tr class="line even">
<td class="ln">2</td>
<td><pre> <b>public</b> <b>class</b> Employee <b>playedBy</b> Person {</pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre> <b>abstract</b> String getIdentification();</pre></td>
</tr>
<tr class="line even">
<td class="ln">4</td>
<td><pre> <span class="comment">// callout binding see below...</span></pre></td>
</tr>
<tr class="line odd">
<td class="ln">5</td>
<td><pre> }</pre></td>
</tr>
<tr class="line even">
<td class="ln">6</td>
<td><pre>}</pre></td>
</tr>
</table>
</div>
</div>
<div class="subsect depth3" id="s3.1.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Kinds of method designators</span><a class="img" href="s3.html#s3.1.c"
title="PermaLink to (c)&nbsp;Kinds of method designators"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>A method designator may either be a method name
</p>
<div class="listing example frame">
<table class="listing">
<tr class="line odd">
<td class="ln">4</td>
<td><pre>getIdentification <em>-&gt;</em> getName;</pre></td>
</tr>
</table>
</div>
<p><strong>or</strong>
a complete method signature including parameter declarations and
return type declaration, but excluding any modifiers and declared exceptions.
</p>
<div class="listing example frame">
<table class="listing">
<tr class="line odd">
<td class="ln">4</td>
<td><pre>String getIdentification() <em>-&gt;</em> String getName();</pre></td>
</tr>
</table>
</div>
<div class="codecomment">
<h5>Effects:</h5>
<ul>
<li> Line 4 declares a callout binding for the role method <code>getIdentification()</code>,
providing an implementation for the abstract method defined in line 3.
</li>
<li> In combination with the role binding in line 2 this has the following effect:</li>
<li> Any call to <code>Employee.getIdentification</code>
is forwarded to the method <code>Person.getName</code>.
</li>
</ul>
</div>
<p>Both sides of a callout binding must use the same kind of
designators, i.e., designators with and without signature may not be mixed.
<br />
Each method designator must uniquely select one method.
If a method designator contains a signature this signature must match exactly with the signature
of an existing method, i.e., no implicit conversions are applied for this matching.
If overloading is involved, signatures <em>must</em> be used to disambiguate.
</p>
</div>
<div class="subsect depth3" id="s3.1.d">
<h4 class="subsect">(d)&nbsp;<span class="title">Inheritance of role method declarations</span><a class="img" href="s3.html#s3.1.d"
title="PermaLink to (d)&nbsp;Inheritance of role method declarations"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>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.
</p>
</div>
<div class="subsect depth3" id="s3.1.e">
<h4 class="subsect">(e)&nbsp;<span class="title">Callout override</span><a class="img" href="s3.html#s3.1.e"
title="PermaLink to (e)&nbsp;Callout override"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>If an inherited role method is concrete, callout binding regarding this
method must use the token "<code>=&gt;</code>" instead of "<code>-&gt;</code>"
in order to declare that this binding overrides an existing implementation.
<br />
Using the "<code>=&gt;</code>" operator for an abstract method is an error.
<br />
It is also an error (and not useful anyway) to callout-bind a method that is
implemented in the same class as the binding.
</p>
</div>
<div class="subsect depth3" id="s3.1.f">
<h4 class="subsect">(f)&nbsp;<span class="title">Inheritance of callout bindings</span><a class="img" href="s3.html#s3.1.f"
title="PermaLink to (f)&nbsp;Inheritance of callout bindings"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p> Callout bindings are inherited along explicit and implicit inheritance.
Inherited callout bindings can be overridden using "<code>=&gt;</code>".
</p>
</div>
<div class="subsect depth3" id="s3.1.g">
<h4 class="subsect">(g)&nbsp;<span class="title">Duplicate bindings</span><a class="img" href="s3.html#s3.1.g"
title="PermaLink to (g)&nbsp;Duplicate bindings"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>It is an error if a role class has multiple callout bindings for the
same role method.
</p>
</div>
<div class="subsect depth3" id="s3.1.h">
<h4 class="subsect">(h)&nbsp;<span class="title">Declared exceptions</span><a class="img" href="s3.html#s3.1.h"
title="PermaLink to (h)&nbsp;Declared exceptions"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>It is an error if a base method to be bound by <strong>callout</strong>
declares in its <code>throws</code> clause any exceptions that
are not declared by the corresponding role method.
</p>
</div>
<div class="subsect depth3" id="s3.1.i">
<h4 class="subsect">(i)&nbsp;<span class="title">Shorthand definition</span><a class="img" href="s3.html#s3.1.i"
title="PermaLink to (i)&nbsp;Shorthand definition"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p> 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 is static iff the bound base method is static,
and it declares the same exceptions as the bound base method.
</p>
<p>
A shorthand callout may optionally declare a <strong>visibility modifier</strong>,
otherwise the generated method inherits the visibility modifier of the bound base method.
No further modifiers are set.
If a callout overrides an inherited method or callout,
it must not reduce the visibility of the inherited method/callout.
</p>
</div>
<div class="subsect depth3" id="s3.1.j">
<h4 class="subsect">(j)&nbsp;<span class="title">Inferred callout</span><a class="img" href="s3.html#s3.1.j"
title="PermaLink to (j)&nbsp;Inferred callout"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p> If a non-abstract role class inherits an abstract method the compiler
tries to infer a callout binding for implementing the abstract method.
Similarly, if a self-call in a role class cannot be resolved, the compiler
tries to infer a callout to resolve the self-call.<br />
Inference searches for a method in the bound base class such that
</p>
<ol>
<li>both methods have the same name</li>
<li>both methods have the same number of arguments</li>
<li>each argument of the abstract role method is compatible to the
corresponding argument of the base method directly, or using
boxing/unboxing or lowering.
</li>
</ol>
<p>
Callouts inferred from an interface have <code>public</code> visibility,
callouts inferred from a self-call have <code>private</code> visibility.
</p>
<p>
Per default inferred callout bindings are disabled, i.e., a compiler
must report these as an error. However, a compiler should allow to
configure reporting to produce a warning only (which can be suppressed
using a <code>@SuppressWarnings("inferredcallout")</code> annotation),
or to completely ignore the diagnostic.
</p>
</div>
<div class="subsect depth3" id="s3.1.k">
<h4 class="subsect">(k)&nbsp;<span class="title">Callout to generic method</span><a class="img" href="s3.html#s3.1.k"
title="PermaLink to (k)&nbsp;Callout to generic method"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>When referring to a generic base method</p>
<div class="listing example frame">
<table class="listing">
<tr class="line odd">
<td class="ln">1</td>
<td><pre>&lt;T&gt; T bm(T a)</pre></td>
</tr>
</table>
</div>
<p>a callout binding may either propagate the method's genericity as in</p>
<div class="listing example frame">
<table class="listing">
<tr class="line odd">
<td class="ln">2</td>
<td><pre>&lt;T&gt; T rm(T a) <b>-&gt;</b> T bm(T a);</pre></td>
</tr>
</table>
</div>
<p>or it may supply a valid substitution for the type parameter as in</p>
<div class="listing example frame">
<table class="listing">
<tr class="line odd">
<td class="ln">2</td>
<td><pre>String rm(String a) <b>-&gt;</b> String bm(String a);</pre></td>
</tr>
</table>
</div>
</div>
<p>A callout binding either attaches an implementation to a previously declared method
or adds (<a href="#s3.1.i" title="&sect;3.1.(i)&nbsp;Shorthand definition" class="sect">&sect;3.1.(i)</a> above) a forwarding method to a role class.
Apart from this implementation, callout-bound methods do not differ from regular methods.
</p>
<p>When we say, a callout binding defines <strong>forwarding</strong> this means that
control is passed to the base object. In contrast, by a <strong>delegation</strong>
semantics control <em>would</em> 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 <a href="s4.html" title="&sect;4&nbsp;Callin Binding" class="sect">&sect;4</a>)
the effect of delegation can easily be achieved.
</p>
</div>
<div class="sect depth2" id="s3.2">
<h2 class="sect">&sect;3.2&nbsp;Callout parameter mapping<a class="img" href="s3.html#s3.2"
title="PermaLink to &sect;3.2&nbsp;Callout parameter mapping"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#top">&uarr;&nbsp;&sect;3</a></span></h2>
<div class="syntaxlink"><a href="sA.html#sA.4.1" title="&sect;A.4.1&nbsp;CalloutParameterMappings"
class="syntax">&rarr;&nbsp;Syntax&nbsp;&sect;A.4.1</a></div>
<div class="subsect depth3" id="s3.2.a">
<h4 class="subsect">(a)&nbsp;<span class="title">with clause</span><a class="img" href="s3.html#s3.2.a" title="PermaLink to (a)&nbsp;with clause"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p> If the method designators in a callout binding are signatures
(not just method names), parameters and return value may
be mapped by a <code>with{...}</code> sub-clause. Parameter mappings may only occur if the enclosing role is a class, not an interface.
</p>
</div>
<div class="subsect depth3" id="s3.2.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Mapping one parameter</span><a class="img" href="s3.html#s3.2.b"
title="PermaLink to (b)&nbsp;Mapping one parameter"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p> 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:
</p>
<div class="listing plain"><pre><i>expression</i> <b>-&gt;</b> <i>base_method_parameter_name</i></pre></div>
</div>
<div class="subsect depth3" id="s3.2.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Result mapping</span><a class="img" href="s3.html#s3.2.c"
title="PermaLink to (c)&nbsp;Result mapping"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>The return value of a callout method may be provided by a result mapping:
</p>
<div class="listing plain"><pre>result <b>&lt;-</b> <i>expression</i></pre></div>
<p>The right hand side expression of a result mapping may use the special identifier
<code>result</code> to refer to the value returned by the base method.
<br />
In a method binding with parameter mappings, it is an error to use
<code>result</code> as the name of a regular method argument.
</p>
<h5 class="listing">Example code (Callout Parameter Mapping):</h5>
<div class="listing example frame">
<table class="listing">
<tr class="line odd">
<td class="ln">1</td>
<td><pre>Integer absoluteValue(Integer integer) <b>-&gt;</b> <b>int</b> abs(<b>int</b> i) <em><b>with</b> {</em></pre></td>
</tr>
<tr class="line even">
<td class="ln">2</td>
<td><pre> integer.intValue() <b>-&gt;</b> i,</pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre> <em>result</em> <b>&lt;-</b> <b>new</b> Integer(<em>result</em>)</pre></td>
</tr>
<tr class="line even">
<td class="ln">4</td>
<td><pre><em>}</em></pre></td>
</tr>
</table>
</div>
</div>
<div class="subsect depth3" id="s3.2.d">
<h4 class="subsect">(d)&nbsp;<span class="title">Visible names</span><a class="img" href="s3.html#s3.2.d" title="PermaLink to (d)&nbsp;Visible names"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Each identifier that appears within the expressions of a parameter
mapping must be either:
</p>
<ul>
<li>a feature visible in the scope of the role instance.</li>
<li>a parameter of the role method (for parameter mappings).</li>
<li>the special name <code>result</code> (for result mappings).
</li>
<li>in a result mapping also the special name <code>base</code> can be used
in order to refer to the bound base instance (provided the method being
bound is not static).
</li>
</ul>
<p>The names of base method arguments (i.e., names after mapping) are only
legal in the position given in <a href="#s3.2.b" title="&sect;3.2.(b)&nbsp;Mapping one parameter"
class="sect">&sect;3.2.(b)</a>.
</p>
</div>
<div class="subsect depth3" id="s3.2.e">
<h4 class="subsect">(e)&nbsp;<span class="title">Implicit parameter mappings</span><a class="img" href="s3.html#s3.2.e"
title="PermaLink to (e)&nbsp;Implicit parameter mappings"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>If parameter mappings should be omitted the following conditions must hold:
</p>
<ol>
<li>each method parameter of the role method must conform to the
corresponding parameter of the base method, <em>and</em></li>
<li>the result type of the base method must conform to the result type
of the role method.
</li>
</ol>
<p>Here conformance includes translation polymorphism (cf. <a href="#s3.3.d" title="&sect;3.3.(d)&nbsp;Typing rules" class="sect">&sect;3.3.(d)</a>).
<br />
Parameter correspondence without parameter mapping is determined by declaration order not by names.
<br />
Two adjustments can, however, be performed implicitly:
</p>
<ul>
<li>If the role method has more parameters than the base method,
unused trailing parameters may be silently ignored.
</li>
<li>If the role method returns <code>void</code>, any result from
the base method may be silently ignored.
</li>
</ul>
</div>
<h5 class="listing">Example code (Callout with Parameter Mapping):</h5>
<div class="listing example frame">
<table class="listing">
<tr class="line odd">
<td class="ln">1</td>
<td><pre><b>public</b> <b>team</b> <b>class</b> MyTeamA {</pre></td>
</tr>
<tr class="line even">
<td class="ln">2</td>
<td><pre> <b>public</b> <b>abstract</b> <b>class</b> Role1 {</pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre> <b>abstract</b> <b>void</b> payEuro(float euro);</pre></td>
</tr>
<tr class="line even">
<td class="ln">4</td>
<td><pre> <b>abstract</b> float earnEuro();</pre></td>
</tr>
<tr class="line odd">
<td class="ln">5</td>
<td><pre> <b>void</b> idle(<b>int</b> seconds) { <span class="comment">/* do nothing */</span> };</pre></td>
</tr>
<tr class="line even">
<td class="ln">6</td>
<td><pre> }</pre></td>
</tr>
<tr class="line odd">
<td class="ln">7</td>
<td><pre> Role1 boss, worker = <span class="comment">// initialization omitted</span></pre></td>
</tr>
<tr class="line even">
<td class="ln">8</td>
<td><pre> <b>public</b> <b>void</b> transaction () {</pre></td>
</tr>
<tr class="line odd">
<td class="ln">9</td>
<td><pre> boss.payEuro(worker.earnEuro());</pre></td>
</tr>
<tr class="line even">
<td class="ln">10</td>
<td><pre> boss.idle(123);</pre></td>
</tr>
<tr class="line odd">
<td class="ln">11</td>
<td><pre> }</pre></td>
</tr>
<tr class="line even">
<td class="ln">12</td>
<td><pre>}</pre></td>
</tr>
<tr class="line odd">
<td class="ln">13</td>
<td><pre><b>public</b> <b>class</b> Staff { <span class="comment">// a base class </span></pre></td>
</tr>
<tr class="line even">
<td class="ln">14</td>
<td><pre> <b>public</b> <b>void</b> payDM (float dm) { … };</pre></td>
</tr>
<tr class="line odd">
<td class="ln">15</td>
<td><pre> <b>public</b> float earnDM () { … };</pre></td>
</tr>
<tr class="line even">
<td class="ln">16</td>
<td><pre> <b>public</b> <b>int</b> doze() { … };</pre></td>
</tr>
<tr class="line odd">
<td class="ln">17</td>
<td><pre> <span class="comment">// other methods omitted</span></pre></td>
</tr>
<tr class="line even">
<td class="ln">18</td>
<td><pre>}</pre></td>
</tr>
<tr class="line odd">
<td class="ln">19</td>
<td><pre><b>public</b> <b>team</b> <b>class</b> MySubTeam <b>extends</b> MyTeamA {</pre></td>
</tr>
<tr class="line even">
<td class="ln">20</td>
<td><pre> <b>public</b> <b>class</b> Role1 <b>playedBy</b> Staff {</pre></td>
</tr>
<tr class="line odd">
<td class="ln">21</td>
<td><pre> <b>void</b> payEuro(float euro) <b>-&gt;</b> <b>void</b> payDM(float dm) <b>with</b> {</pre></td>
</tr>
<tr class="line even">
<td class="ln">22</td>
<td><pre> euro * 1.95583f <b>-&gt;</b> dm</pre></td>
</tr>
<tr class="line odd">
<td class="ln">23</td>
<td><pre> }</pre></td>
</tr>
<tr class="line even">
<td class="ln">24</td>
<td><pre> float earnEuro() <b>-&gt;</b> float earnDM () <b>with</b> {</pre></td>
</tr>
<tr class="line odd">
<td class="ln">25</td>
<td><pre> result <b>&lt;-</b> result / 1.95583f</pre></td>
</tr>
<tr class="line even">
<td class="ln">26</td>
<td><pre> }</pre></td>
</tr>
<tr class="line odd">
<td class="ln">27</td>
<td><pre> idle <b>=&gt;</b> doze; <span class="comment">// override existing implementation of idle()</span></pre></td>
</tr>
<tr class="line even">
<td class="ln">28</td>
<td><pre> }</pre></td>
</tr>
<tr class="line odd">
<td class="ln">29</td>
<td><pre> <b>void</b> doit() {</pre></td>
</tr>
<tr class="line even">
<td class="ln">30</td>
<td><pre> transaction();</pre></td>
</tr>
<tr class="line odd">
<td class="ln">31</td>
<td><pre> }</pre></td>
</tr>
<tr class="line even">
<td class="ln">32</td>
<td><pre>}</pre></td>
</tr>
</table>
</div>
<div class="codecomment">
<h5>Effects:</h5>
<ul>
<li>Class <code>MyTeamA</code> is declaratively complete and can be
type checked because it only uses methods that are visible or declared within this
context. <code>MyTeamA.Role1</code> can, however, not be instantiated, because it is
abstract.
</li>
<li>Line 30 has the normal effect of invoking <code>transaction</code>.
</li>
<li>When executing <code>transaction</code>, the call of <code>worker.earnEuro()</code>
is forwarded to the corresponding base object using method <code>earnDM()</code>
(binding declaration in line 24).
The result is converted by "<code>result / 1.95583f</code>" (line 25).
</li>
<li>Within the same execution of <code>transaction</code>, the call of
<code>boss.payEuro()</code>
is forwarded to the corresponding base object using method <code>payDM()</code>
(binding declaration in line 21).
The parameter <code>euro</code> is converted by "<code>euro * 1.95583f</code>"
(line 22).
</li>
<li>Method <code>idle</code> is forwarded to <code>doze</code> without any
parameter mapping. This requires <code>doze</code> to have a signature
that is conformable to the signature of <code>idle</code>.
In this case a role parameter and a base result are ignored.<br />
Using the <code>=&gt;</code> operator, this binding overrides the existing
implementation of <code>idle</code>.
</li>
</ul>
</div>
</div>
<div class="sect depth2" id="s3.3">
<h2 class="sect">&sect;3.3&nbsp;Lifting and lowering<a class="img" href="s3.html#s3.3"
title="PermaLink to &sect;3.3&nbsp;Lifting and lowering"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#top">&uarr;&nbsp;&sect;3</a></span></h2>
<p> (For basic definitions see <a href="s2.html#s2.2" title="&sect;2.2&nbsp;Lowering" class="sect">&sect;2.2</a> and <a href="s2.html#s2.3" title="&sect;2.3&nbsp;Lifting" class="sect">&sect;2.3</a>)
</p>
<div class="subsect depth3" id="s3.3.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Call target translation</span><a class="img" href="s3.html#s3.3.a"
title="PermaLink to (a)&nbsp;Call target translation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Invoking a base method due to a callout binding first
<strong>lowers</strong> the role object in order to obtain the effective call target.
</p>
</div>
<div class="subsect depth3" id="s3.3.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Parameter translation</span><a class="img" href="s3.html#s3.3.b"
title="PermaLink to (b)&nbsp;Parameter translation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Passing a role object as parameter to a callout method implicitly <strong>lowers</strong>
this parameter, if the base method declares a corresponding base type parameter.
<br />
Lifting of callout parameters is not possible.
</p>
</div>
<div class="subsect depth3" id="s3.3.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Result translation</span><a class="img" href="s3.html#s3.3.c"
title="PermaLink to (c)&nbsp;Result translation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p> When returning a base object from a callout method where the role
method declares the result to be of a role class,
this object is implicitly <strong>lifted</strong> to the appropriate role.
<br />
Lowering the result of a callout binding is not possible.
</p>
</div>
<div class="subsect depth3" id="s3.3.d">
<h4 class="subsect">(d)&nbsp;<span class="title">Typing rules</span><a class="img" href="s3.html#s3.3.d" title="PermaLink to (d)&nbsp;Typing rules"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>A parameter mapping (implicit by parameter position or explicit
by a <code>with</code> clause) is <strong>well typed</strong> if
the left hand side conforms to the right hand side, either by
</p>
<ul>
<li>type equality</li>
<li>implicit primitive type conversion</li>
<li>subtype polymorphism</li>
<li>translation polymorphism, here: <em>lowering</em>,
</li>
<li><em>or</em> by a combination of the above.
</li>
</ul>
<p>A result mapping (implicit or explicit by a <code>with</code> clause)
is well typed, if the value at the right hand side conforms to the
left hand side according to the rules given above, except that
translation polymorphism here applies <em>lifting</em> instead of
lowering.
</p>
</div>
<div class="subsect depth3" id="s3.3.e">
<h4 class="subsect">(e)&nbsp;<span class="title">Role arrays</span><a class="img" href="s3.html#s3.3.e" title="PermaLink to (e)&nbsp;Role arrays"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>For arrays of roles as parameters <a href="s2.html#s2.2.e" title="&sect;2.2.(e)&nbsp;Lowering of arrays"
class="sect">&sect;2.2.(e)</a> applies accordingly.
For arrays as a return value <a href="s2.html#s2.3.d" title="&sect;2.3.(d)&nbsp;Lifting of arrays"
class="sect">&sect;2.3.(d)</a> applies.
</p>
</div>
</div>
<div class="sect depth2" id="s3.4">
<h2 class="sect">&sect;3.4&nbsp;Overriding access restrictions<a class="img" href="s3.html#s3.4"
title="PermaLink to &sect;3.4&nbsp;Overriding access restrictions"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#top">&uarr;&nbsp;&sect;3</a></span></h2>
<p>In contrast to normal access restrictions, method bindings
may refer to hidden base methods.
This concept is the inverse of encapsulation, hence it is called
<strong>decapsulation</strong>.
<br />
Decapsulation may occur in these positions:
</p>
<ul>
<li><code>playedBy</code> declaration (see <a href="s2.html#s2.1.2.c"
title="&sect;2.1.2.(c)&nbsp;Base class decapsulation"
class="sect">&sect;2.1.2.(c)</a>)
</li>
<li>base constructor call (see <a href="s2.html#s2.4.2.b" title="&sect;2.4.2.(b)&nbsp;Bound roles"
class="sect">&sect;2.4.2.(b)</a>).
</li>
<li>callout bindings (see next)</li>
<li>callout to field (see <a href="#s3.5.e" title="&sect;3.5.(e)&nbsp;Access control" class="sect">&sect;3.5.(e)</a>)
</li>
<li>base call within a callin method (see <a href="s4.html#s4.6" title="&sect;4.6&nbsp;Overriding access restrictions"
class="sect">&sect;4.6</a>)
</li>
</ul>
<div class="subsect depth3" id="s3.4.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Callout to inaccessible base method</span><a class="img" href="s3.html#s3.4.a"
title="PermaLink to (a)&nbsp;Callout to inaccessible base method"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>By means of <strong>callout</strong> bindings it is possible to access
methods of a base class regardless of their access modifiers.
Method bindings are the only place in a program which may mention otherwise
inaccessible methods.
Access to the callout method at the role side is controlled by regular mechanisms,
based on the declaration of the role method.
</p>
</div>
<div class="subsect depth3" id="s3.4.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Sealing against decapsulation</span><a class="img" href="s3.html#s3.4.b"
title="PermaLink to (b)&nbsp;Sealing against decapsulation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>A base package may be "sealed" which re-establishes the standard Java visibility rules.
<br />
Sealing is achieved by the corresponding capability of Jar files.
</p>
</div>
<div class="subsect depth3" id="s3.4.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Warning levels</span><a class="img" href="s3.html#s3.4.c"
title="PermaLink to (c)&nbsp;Warning levels"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>A compiler should signal any occurrence of 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 (cf. <a href="s2.html#s2.1.2.c"
title="&sect;2.1.2.(c)&nbsp;Base class decapsulation"
class="sect">&sect;2.1.2.(c)</a>).
<br />
Optionally, a batch compiler may support three levels of verbosity with respect to decapsulation:
</p>
<table border="1">
<tr>
<td rowspan="1" colspan="1"><tt>-nodecapsulation</tt></td>
<td rowspan="1" colspan="1">No warnings.</td>
</tr>
<tr>
<td rowspan="1" colspan="1"><em>default</em></td>
<td rowspan="1" colspan="1">Warn only if/that access restrictions are overridden.</td>
</tr>
<tr>
<td rowspan="1" colspan="1"><tt>-decapsulation</tt></td>
<td rowspan="1" colspan="1">Detailed messages containing the binding and the hidden base method.</td>
</tr>
</table>
</div>
<div class="subsect depth3" id="s3.4.d">
<h4 class="subsect">(d)&nbsp;<span class="title">Private methods from super classes</span><a class="img" href="s3.html#s3.4.d"
title="PermaLink to (d)&nbsp;Private methods from super classes"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>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 <code>playedBy</code>. I.e., for private methods
<a href="#s3.1.d"
title="&sect;3.1.(d)&nbsp;Inheritance of role method declarations"
class="sect">&sect;3.1.(d)</a> does not hold.
<br />
The same holds for private base fields (see below).
<br />
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.
</p>
<div class="listing example frame">
<table class="listing">
<tr class="line odd">
<td class="ln">1</td>
<td><pre><b>public</b> <b>class</b> SuperBase {</pre></td>
</tr>
<tr class="line even">
<td class="ln">2</td>
<td><pre> <em><b>private</b> <b>int</b> secret;</em></pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre>}</pre></td>
</tr>
<tr class="line even">
<td class="ln">4</td>
<td><pre><b>public</b> <b>class</b> SubBase <b>extends</b> SuperBase { <span class="comment">/* details omitted */</span> }</pre></td>
</tr>
<tr class="line odd">
<td class="ln">5</td>
<td><pre><b>public</b> <b>team</b> <b>class</b> MyTeam {</pre></td>
</tr>
<tr class="line even">
<td class="ln">6</td>
<td><pre> <b>protected</b> <b>class</b> SuperRole <b>playedBy</b> SuperBase {</pre></td>
</tr>
<tr class="line odd">
<td class="ln">7</td>
<td><pre> <b>int</b> steal() <b>-&gt;</b> <b>get</b> <b>int</b> <em>secret</em>; <span class="comment">// <span class="green"><strong>OK</strong></span></span></pre></td>
</tr>
<tr class="line even">
<td class="ln">8</td>
<td><pre> }</pre></td>
</tr>
<tr class="line odd">
<td class="ln">9</td>
<td><pre> <b>protected</b> <b>class</b> SubRole <b>extends</b> SuperRole <b>playedBy</b> SubBase {</pre></td>
</tr>
<tr class="line even">
<td class="ln">10</td>
<td><pre> <b>int</b> steal() <b>-&gt;</b> <b>get</b> <b>int</b> <em>secret</em>; <span class="comment">// <span class="error"><strong>illegal!</strong></span></span></pre></td>
</tr>
<tr class="line odd">
<td class="ln">11</td>
<td><pre> }</pre></td>
</tr>
<tr class="line even">
<td class="ln">12</td>
<td><pre>}</pre></td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect depth2" id="s3.5">
<h2 class="sect">&sect;3.5&nbsp;Callout to field<a class="img" href="s3.html#s3.5"
title="PermaLink to &sect;3.5&nbsp;Callout to field"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#top">&uarr;&nbsp;&sect;3</a></span></h2>
<p>Also fields of a base class can be made accessible using a callout binding.
</p>
<div class="subsect depth3" id="s3.5.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Syntax</span><a class="img" href="s3.html#s3.5.a" title="PermaLink to (a)&nbsp;Syntax"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Using one of the callout modifiers <code>get</code> or <code>set</code> a role method
can be bound to a field of the role's base class:
</p>
<div class="listing example frame">
<table class="listing">
<tr class="line odd">
<td class="ln">1</td>
<td><pre>getValue <b>-&gt;</b> <em>get</em> value;</pre></td>
</tr>
<tr class="line even">
<td class="ln">2</td>
<td><pre>setValue <b>-&gt;</b> <em>set</em> value;</pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre><b>int</b> getValue() <b>-&gt;</b> <em>get</em> <b>int</b> value;</pre></td>
</tr>
</table>
</div>
<p>where <code>getValue</code>, <code>setValue</code> are abstract role methods of
appropriate signatures and <code>value</code> is a field of the bound base class.
<br />
A longer syntax is available, too (see line 3 above), which uses complete signatures.
For the left hand side <a href="#s3.1.c" title="&sect;3.1.(c)&nbsp;Kinds of method designators"
class="sect">&sect;3.1.(c)</a> applies, for the
right hand side, this longer version prepends the field type to the field name.
</p>
</div>
<div class="subsect depth3" id="s3.5.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Compatibility</span><a class="img" href="s3.html#s3.5.b" title="PermaLink to (b)&nbsp;Compatibility"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>A role method bound with the modifier <code>get</code>
should have no arguments
(it <em>may</em> 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.
<br />
A role method bound with the modifier <code>set</code> 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.
</p>
</div>
<div class="subsect depth3" id="s3.5.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Value mapping</span><a class="img" href="s3.html#s3.5.c" title="PermaLink to (c)&nbsp;Value mapping"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Values can be mapped similar to parameter mappings in pure method bindings
(<a href="#s3.2" title="&sect;3.2&nbsp;Callout parameter mapping" class="sect">&sect;3.2</a>). Such mappings can be used to establish compatibility as required above.
<br />
In both <code>get</code> and <code>set</code> bindings, the base side value is denoted
by the field's name (lines 2 and 4 below).
</p>
<div class="listing example frame">
<table class="listing">
<tr class="line odd">
<td class="ln">1</td>
<td><pre>Integer getValue() -&gt; <em>get</em> <b>int</b> val</pre></td>
</tr>
<tr class="line even">
<td class="ln">2</td>
<td><pre> <em>with</em> { result &lt;- <b>new</b> Integer(val) }</pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre><b>void</b> setValue(Integer i) -&gt; <em>set</em> <b>int</b> val</pre></td>
</tr>
<tr class="line even">
<td class="ln">4</td>
<td><pre> <em>with</em> { i.intValue() -&gt; val }</pre></td>
</tr>
</table>
</div>
</div>
<div class="subsect depth3" id="s3.5.d">
<h4 class="subsect">(d)&nbsp;<span class="title">Effect</span><a class="img" href="s3.html#s3.5.d" title="PermaLink to (d)&nbsp;Effect"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>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.
</p>
</div>
<div class="subsect depth3" id="s3.5.e">
<h4 class="subsect">(e)&nbsp;<span class="title">Access control</span><a class="img" href="s3.html#s3.5.e"
title="PermaLink to (e)&nbsp;Access control"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>For accessing an otherwise invisible field, the rules for
<a href="#s3.4" title="&sect;3.4&nbsp;Overriding access restrictions"
class="sect">decapsulation (&sect;3.4)</a> apply accordingly.
<br />
Recall, that according to
<a href="http://java.sun.com/docs/books/jls/second_edition/html/classes.doc.html#40898"
class="ext">JLS &sect;8.3</a>
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.
</p>
</div>
<div class="subsect depth3" id="s3.5.f">
<h4 class="subsect">(f)&nbsp;<span class="title">Shorthand definition</span><a class="img" href="s3.html#s3.5.f"
title="PermaLink to (f)&nbsp;Shorthand definition"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Just as in <a href="#s3.1.i" title="&sect;3.1.(i)&nbsp;Shorthand definition" class="sect">&sect;3.1.(i)</a> 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 href="#s3.5.a" title="&sect;3.5.(a)&nbsp;Syntax" class="sect">&sect;3.5.(a)</a> above.
The generated access method is static iff the bound base field is static.
</p>
<p>
A shorthand callout to field may optionally declare a <strong>visibility modifier</strong>,
otherwise the generated method inherits the visibility modifier of the bound base field.
No further modifiers are set.
If a callout to field overrides an inherited method or callout,
it must not reduce the visibility of the inherited method/callout.
</p>
</div>
<div class="subsect depth3" id="s3.5.g">
<h4 class="subsect">(g)&nbsp;<span class="title">Callout override</span><a class="img" href="s3.html#s3.5.g"
title="PermaLink to (g)&nbsp;Callout override"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Similar to method callouts a callout to field may override an existing role
method if and only if the token <code>=&gt;</code> is used instead of <code>-&gt;</code>
(see <a href="#s3.1.e" title="&sect;3.1.(e)&nbsp;Callout override" class="sect">&sect;3.1.(e)</a> and <a href="#s3.1.f" title="&sect;3.1.(f)&nbsp;Inheritance of callout bindings"
class="sect">&sect;3.1.(f)</a>).
</p>
</div>
<div class="subsect depth3" id="s3.5.h">
<h4 class="subsect">(h)&nbsp;<span class="title">Inferred callout</span><a class="img" href="s3.html#s3.5.h"
title="PermaLink to (h)&nbsp;Inferred callout"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p> If a statement or expression within the body of a bound role class
uses a simple name or a name qualified by <code>this</code>
which can not be resolved using normal rules,
the compiler may infer to use a callout to field instead,
given that a field of the required name can be found in the role's declared baseclass.
</p>
<p> If a callout to field has explicitly been declared it is used for the otherwise
unresolved name, if and only if:
</p>
<ul>
<li>the callout declares a role method name the is constructed from the token "set" for
a setter or "get" for a getter plus the field name with capital first letter,
</li>
<li>the base field referenced by the callout has exactly the required name, and</li>
<li>the callout kind (set/get) matches the application of the unresolved name as either
the left-hand side of an assignment (set) or as an expression (get).
</li>
</ul>
<p>
If a matching callout to field is not found, the compiler generates one automatically,
which has <code>private</code> visibility.
</p>
<p>
If a callout to field has been inferred it is an error to directly invoke the
implicitly generated callout accessor that is formed according to the above rules.
</p>
<p>
Per default inferred callout bindings are disabled, i.e., a compiler
must report these as an error. However, a compiler should allow to
configure reporting to produce a warning only (which can be suppressed
using a <code>@SuppressWarnings("inferredcallout")</code> annotation),
or to completely ignore the diagnostic. See also <a href="#s3.1.j" title="&sect;3.1.(j)&nbsp;Inferred callout" class="sect">&sect;3.1.(j)</a>.
</p>
</div>
</div>
</div>
<table class="nav">
<tr>
<td class="back"><a href="s2.html" rel="prev">&lt;&lt;&nbsp;&sect;2&nbsp;Role Binding</a></td>
<td class="top"><a href="index.html" rel="contents">&uarr;&nbsp;Table of Contents&nbsp;&uarr;</a></td>
<td class="next"><a href="s4.html" rel="next">&sect;4&nbsp;Callin Binding&nbsp;&gt;&gt;</a></td>
</tr>
</table>
</div>
<div id="footer">
<hr /><a class="w3c img" href="http://jigsaw.w3.org/css-validator/check/referer"
shape="rect"><img src="../images/valid-css2-blue.png" alt="Valid CSS!" height="31" width="88" /></a><a class="w3c img" href="http://validator.w3.org/check?uri=referer" shape="rect"><img src="../images/valid-xhtml10-blue.png" alt="Valid XHTML 1.0 Strict" height="31"
width="88" /></a><address>&copy; Stephan Herrmann, Christine Hundt, Marco Mosconi</address>
OT/J version 1.3.1 &mdash; last modified: 2013-05-28
</div>
</body>
</html>