Google Git
Sign in
eclipse / gerrit / objectteams / org.eclipse.objectteams / c633a48739e084c65aa085099612bdcabcee388a / . / plugins / org.eclipse.objectteams.otdt.doc / guide / otjld / xdef / s3.2.html
blob: 7deaec7d6abe7666af7bfb8170db031b1d964f17 [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="s3.1.html" rel="prev">&lt;&lt;&nbsp;&sect;3.1&nbsp;Callout method 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="s3.3.html" rel="next">&sect;3.3&nbsp;Lifting and lowering&nbsp;&gt;&gt;</a></td>
</tr>
</table>
<div class="breadcrumb"><a class="nav" href="s3.html" rel="section">&sect;3&nbsp;Callout Binding</a></div>
<div class="sect depth2" id="s3.2">
<h2 class="sect">&sect;3.2&nbsp;Callout parameter mapping<a class="img" href="s3.2.html"
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></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.2.a.html" 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.2.b.html"
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.2.c.html" 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.2.d.html" 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.2.e.html"
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.html" 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>
<table class="nav">
<tr>
<td class="back"><a href="s3.1.html" rel="prev">&lt;&lt;&nbsp;&sect;3.1&nbsp;Callout method 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="s3.3.html" rel="next">&sect;3.3&nbsp;Lifting and lowering&nbsp;&gt;&gt;</a></td>
</tr>
</table>
<div class="breadcrumb"><a class="nav" href="s3.html" rel="section">&sect;3&nbsp;Callout Binding</a></div>
</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>