blob: 1a1844f910fc6bd46ae05945abbd9cf01e940c85 [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</title>
</head>
<body class="otdt">
<div id="content">
<table class="nav">
<tr>
<td class="back"><a id="top"></a><a href="s2.2.html" rel="prev">&lt;&lt;&nbsp;&sect;2.2&nbsp;Lowering</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="s2.4.html" rel="next">&sect;2.4&nbsp;Explicit role creation&nbsp;&gt;&gt;</a></td>
</tr>
</table>
<div class="breadcrumb"><a class="nav" href="s2.html" rel="section">&sect;2&nbsp;Role Binding</a></div>
<div class="sect depth2" id="s2.3">
<h2 class="sect">&sect;2.3&nbsp;Lifting<a class="img" href="s2.3.html" title="PermaLink to &sect;2.3&nbsp;Lifting"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h2>
<p>Lifting is the reverse translation of lowering. However, lifting is
a bit more demanding, since a given base object may have zero to
many role objects bound to it. Therefor, the lifting translation
requires more context information and may require to create role
objects on demand.
</p>
<div class="subsect depth3" id="s2.3.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Definition of lifting</span><a class="img" href="s2.3.a.html"
title="PermaLink to (a)&nbsp;Definition of lifting"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Retrieving a role for a given base object is called <strong>lifting</strong>.
Lifting is guaranteed to yield the same role object for subsequent
calls regarding the same base object, the same team instance and
the same role class (see <a href="#s2.3.4" title="&sect;2.3.4&nbsp;Binding ambiguities" class="sect">&sect;2.3.4</a>
for cases of ambiguity that are signaled by compiler warnings
and possibly runtime exceptions).
</p>
</div>
<div class="subsect depth3" id="s2.3.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Places of lifting</span><a class="img" href="s2.3.b.html"
title="PermaLink to (b)&nbsp;Places of lifting"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>The lifting translation is not meant to be invoked
by client code, but translations are inserted by the compiler
at the following locations:
</p>
<ul>
<li><a href="s3.3.c.html" title="&sect;3.3.(c)&nbsp;Result translation"
class="sect">Callout bindings (&sect;3.3.(c))</a> (result)
</li>
<li><a href="s4.5.a.html" title="&sect;4.5.(a)&nbsp;Call target translation"
class="sect">Callin bindings (&sect;4.5.(a))</a> (call target and parameters)
</li>
<li><a href="#s2.3.2" title="&sect;2.3.2&nbsp;Declared lifting" class="sect">Declared lifting (&sect;2.3.2)</a></li>
</ul>
</div>
<div class="subsect depth3" id="s2.3.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Typing</span><a class="img" href="s2.3.c.html" title="PermaLink to (c)&nbsp;Typing"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>A lifting translation statically expects a specific role class.
This expected role class must have a <code>playedBy</code> clause
(either directly, or inherited (explicitly or implicitly)
from a super role), to which the given base type is conform.
</p>
</div>
<div class="subsect depth3" id="s2.3.d">
<h4 class="subsect">(d)&nbsp;<span class="title">Lifting of arrays</span><a class="img" href="s2.3.d.html"
title="PermaLink to (d)&nbsp;Lifting of arrays"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Lifting also works for arrays of role objects.
For lifting an array of base objects
a new array is created and filled with role objects, one for each
base object in the original array. In contrast to the role objects
themselves, lifted arrays are never reused for subsequent lifting
invocations.
</p>
</div>
<p id="s2.3.transpol">The term <strong>translation polymorphism</strong>
describes the fact that at certain points values can be passed which are not
conform to the respective declared type considering only regular
inheritance (<code>extends</code>). With translation polymorphism
it suffices that a value can be translated using lifting or lowering.
</p>
<div class="sect depth3" id="s2.3.1">
<h3 class="sect">&sect;2.3.1&nbsp;Implicit role creation<a class="img" href="s2.3.1.html"
title="PermaLink to &sect;2.3.1&nbsp;Implicit role creation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#top">&uarr;&nbsp;&sect;2.3</a></span></h3>
<p>Lifting tries to reuse existing role objects so that role state persists across
lifting and lowering. If no suitable role instance is found during lifting,
a new role is created.
</p>
<div class="subsect depth4" id="s2.3.1.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Reuse of existing role objects</span><a class="img" href="s2.3.1.a.html"
title="PermaLink to (a)&nbsp;Reuse of existing role objects"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>A role object is considered suitable for reuse during lifting, if
these three items are identical:
</p>
<ol>
<li>the given base object</li>
<li>the given team object</li>
<li>the statically required role type</li>
</ol>
<p>For the relation between the statically required role type and
the actual type of the role object see <a href="#s2.3.3" title="&sect;2.3.3&nbsp;Smart lifting" class="sect">"smart lifting" (&sect;2.3.3)</a>.
</p>
</div>
<div class="subsect depth4" id="s2.3.1.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Default lifting constructor</span><a class="img" href="s2.3.1.b.html"
title="PermaLink to (b)&nbsp;Default lifting constructor"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Lifting uses a default constructor which takes exactly one argument of the type
of the declared base class (after <code>playedBy</code>).
By default the compiler generates such a constructor for each bound role.
On the other hand, default constructors that take no arguments
(as in <a href="http://java.sun.com/docs/books/jls/second_edition/html/classes.doc.html#16823"
class="ext">JLS &sect;8.8.7</a>) are never generated for bound roles.
<br />
The super-constructor to be invoked by a default lifting constructor
depends on whether the role's super class is a bound role or not.
</p>
<ul>
<li>If the super-class is a bound role, the default lifting constructor will invoke the default lifting constructor of the super-class.</li>
<li>If the super-class is not a bound role, the default lifting constructor will invoke the normal argumentless default constructor
of the super-class.
</li>
</ul>
</div>
<div class="subsect depth4" id="s2.3.1.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Custom lifting constructor</span><a class="img" href="s2.3.1.c.html"
title="PermaLink to (c)&nbsp;Custom lifting constructor"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>If a role class declares a custom constructor with the same signature
as the default lifting constructor, this constructor is used during lifting.
This custom constructor may pre-assume that the role has been setup
properly regarding its base-link and registered in the team's internal map of roles.
<br />
If a bound role has an unbound super-class without an argumentless
constructor, providing a custom lifting constructor is obligatory,
because no legal default lifting constructor can be generated.
</p>
</div>
</div>
<div class="sect depth3" id="s2.3.2">
<h3 class="sect">&sect;2.3.2&nbsp;Declared lifting<a class="img" href="s2.3.2.html"
title="PermaLink to &sect;2.3.2&nbsp;Declared lifting"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#top">&uarr;&nbsp;&sect;2.3</a></span></h3>
<div class="syntaxlink"><a href="sA.html#sA.6.2" title="&sect;A.6.2&nbsp;LiftingType" class="syntax">&rarr;&nbsp;Syntax&nbsp;&sect;A.6.2</a></div>
<div class="subsect depth4" id="s2.3.2.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Parameters with declared lifting</span><a class="img" href="s2.3.2.a.html"
title="PermaLink to (a)&nbsp;Parameters with declared lifting"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>A non-static team-level method or constructor may declare a parameter with two types
in order to explicitly denote a place of <strong>lifting</strong>. Using the syntax
</p>
<div class="listing plain"><pre><b>public</b> <b>void</b> m (BaseClass <em>as</em> RoleClass param) { <i>stmts</i> }</pre></div>
<p>a liftable parameter can be declared, provided the second type
(<code>RoleClass</code>) is a role of (<code>playedBy</code>) the first type (<code>BaseClass</code>).
Furthermore, the role type must be a role of the enclosing team class defining the given method.
The role type must be given by its simple (i.e., unqualified) name.
<br />
Such a signature requires the caller to provide a base object (here <code>BaseClass</code>), but
the callee receives a role object (here <code>RoleClass</code>).
In fact, the client sees a signature in which the "<code>as RoleClass</code>" part is omitted.
<br />
Compatibility between caller and callee sides is achieved by an implicitly inserted lifting translation.
A signature using declared lifting is only valid, if the requested lifting is possible
(see <a href="#s2.3.3" title="&sect;2.3.3&nbsp;Smart lifting" class="sect">&sect;2.3.3</a> and <a href="#s2.3.4" title="&sect;2.3.4&nbsp;Binding ambiguities" class="sect">&sect;2.3.4</a> for details).
</p>
</div>
<div class="subsect depth4" id="s2.3.2.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Super in the context of declared lifting</span><a class="img" href="s2.3.2.b.html"
title="PermaLink to (b)&nbsp;Super in the context of declared lifting"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Calling <code>super</code> or <code>tsuper</code> in a method or constructor which
declares lifting for one or more parameters refers to a method or constructor with role type parameters,
i.e., lifting takes place <em>before</em> super invocation. Nevertheless, the super method may also
have a declared lifting signature. It will then see the same role instance(s) as the current method.
</p>
</div>
<div class="subsect depth4" id="s2.3.2.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Declared lifting of arrays</span><a class="img" href="s2.3.2.c.html"
title="PermaLink to (c)&nbsp;Declared lifting of arrays"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>If a parameter involving explicit lifting should be of an <strong>array</strong> type, the syntax is
</p>
<div class="listing plain"><pre><b>public</b> <b>void</b> m (BaseClass <b>as</b> RoleClass param[]) ...</pre></div>
<p>Here the brackets denoting the array apply to both types, <code>BaseClass</code>
and <code>RoleClass</code>.
</p>
</div>
<div class="subsect depth4" id="s2.3.2.d">
<h4 class="subsect">(d)&nbsp;<span class="title">Declared lifting for catch blocks</span><a class="img" href="s2.3.2.d.html"
title="PermaLink to (d)&nbsp;Declared lifting for catch blocks"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Also the argument of a catch block may apply declared lifting like in:
</p>
<div class="listing plain"><pre><b>catch</b> (BaseException <b>as</b> RoleClass param) { <i>stmts</i> }</pre></div>
<p>This syntax is only valid in a non-static scope of a team (directly or nested).
In the given example, <code>RoleClass</code> must be played by <code>BaseException</code>.
Note, that <code>RoleClass</code> itself need not be a throwable.
As the effect of this declaration the catch block will catch any exception of type <code>BaseException</code>
and provides it wrapped with a <code>RoleClass</code> instance to the subsequent block.
<br />
Also note, that re-throwing the given instance <code>param</code> has the semantics of implicitly lowering
the role to its base exception before throwing, because the role conforms to the required type
<code>Throwable</code> only via lowering.
</p>
</div>
<div class="subsect depth4" id="s2.3.2.e">
<h4 class="subsect">(e)&nbsp;<span class="title">Generic declared lifting</span><a class="img" href="s2.3.2.e.html"
title="PermaLink to (e)&nbsp;Generic declared lifting"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>A method with declared lifting may introduce a type parameter that is bounded relative to a given role type.
Such bound is declared as:
</p>
<div class="listing plain"><pre>&lt;AnyBase <b>base</b> SuperRole&gt;
<b>void</b> teamMethod(AnyBase <b>as</b> SuperRole arg) {
<span class="comment">// body using arg as of type SuperRole</span>
}</pre></div>
<p>This means that <code>AnyBase</code> is a type parameter whose instantiations must all be liftable to role <code>SuperRole</code>.
</p>
<p>
The given type bound requires the call site to supply an argument that is compatible to any base class
for which the current team contains a bound role that is a sub class of <code>SuperRole</code>, including <code>SuperRole</code> itself.
However, <code>SuperRole</code> itself need not be bound to any base class.
On the other hand, different valid substitutions for <code>AnyBase</code> need not be related by inheritance.
</p>
<div class="note">
<h5>Note:</h5>
This feature supports generalized treatment of otherwise unrelated base classes.
This is done by defining one bound role for each base under consideration and by
having all these roles extend a common unbound role.
</div>
</div>
<h5 class="listing">Example code (Declared Lifting):</h5>
<div class="listing example frame" id="l2.3.2">
<table class="listing">
<tr class="line odd">
<td class="ln">1</td>
<td><pre><b>team</b> <b>class</b> Super {</pre></td>
</tr>
<tr class="line even">
<td class="ln">2</td>
<td><pre> <b>public</b> <b>class</b> MyRole <b>playedBy</b> MyBase { ... }</pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre> <b>void</b> m (MyRole o) { ... };</pre></td>
</tr>
<tr class="line even">
<td class="ln">4</td>
<td><pre>}</pre></td>
</tr>
<tr class="line odd">
<td class="ln">5</td>
<td><pre><b>team</b> <b>class</b> Sub <b>extends</b> Super {</pre></td>
</tr>
<tr class="line even">
<td class="ln">6</td>
<td><pre> <b>void</b> m (<em>MyBase <b>as</b> MyRole o</em>) {</pre></td>
</tr>
<tr class="line odd">
<td class="ln">7</td>
<td><pre> <span class="comment">// inside this method o is of type MyRole</span></pre></td>
</tr>
<tr class="line even">
<td class="ln">8</td>
<td><pre> super.m(o);</pre></td>
</tr>
<tr class="line odd">
<td class="ln">9</td>
<td><pre> }</pre></td>
</tr>
<tr class="line even">
<td class="ln">10</td>
<td><pre>}</pre></td>
</tr>
<tr class="line odd">
<td class="ln">11</td>
<td><pre>Sub s_<b>team</b> = <b>new</b> Sub();</pre></td>
</tr>
<tr class="line even">
<td class="ln">12</td>
<td><pre>MyBase b = <b>new</b> MyBase();</pre></td>
</tr>
<tr class="line odd">
<td class="ln">13</td>
<td><pre>s_team.m(b); <span class="comment">// clients see a parameter "MyBase o"</span></pre></td>
</tr>
</table>
</div>
<div class="codecomment">
<h5>Effects:</h5>
<ul>
<li>Clients use method <code>m</code> with a base instance (type <code>MyBase</code>) as its argument (line 13).
</li>
<li>Before executing the body of <code>m</code>, the argument is lifted such that the method body receives
the argument as of type <code>MyRole</code> (line 8).
</li>
</ul>
</div>
</div>
<div class="sect depth3" id="s2.3.3">
<h3 class="sect">&sect;2.3.3&nbsp;Smart lifting<a class="img" href="s2.3.3.html"
title="PermaLink to &sect;2.3.3&nbsp;Smart lifting"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#top">&uarr;&nbsp;&sect;2.3</a></span></h3>
<p>In situations where role and base classes are part of some inheritance
hierarchies (<code>extends</code>), choosing the appropriate role class during
lifting involves the following rules:
</p>
<div class="subsect depth4" id="s2.3.3.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Static adjustment</span><a class="img" href="s2.3.3.a.html"
title="PermaLink to (a)&nbsp;Static adjustment"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>If a base class <code>B</code> shall be lifted to a role class
<code>R</code> that is not bound to (<code>playedBy</code>)
<code>B</code>, but if a subclass of <code>R</code>
&mdash; say <code>R2</code> &mdash;
is bound to <code>B</code>, lifting is statically setup to use
<code>R2</code>, the most general subclass of <code>R</code> that
is bound to <code>B</code> or one of its super-types.
</p>
<div class="note">
<h5>Restriction:</h5>
This step is not applicable for parameter mappings of <code>replace</code>
callin bindings (<a href="s4.5.d.html" title="&sect;4.5.(d)&nbsp;Typing rules" class="sect">&sect;4.5.(d)</a>).
</div>
</div>
<div class="subsect depth4" id="s2.3.3.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Dynamic selection of a role class</span><a class="img" href="s2.3.3.b.html"
title="PermaLink to (b)&nbsp;Dynamic selection of a role class"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>At runtime also the dynamic type of a base object is considered:
Lifting always tries to use a role class that is bound to the
exact class of the base object. Lifting considers all role&ndash;base
pairs bound by <code>playedBy</code> such that the role class is a
sub-class of the required (statically declared) role type
and the base class is a super-class of the
dynamic type of the base object.
<br />
From those possible pairs the most specific base class is chosen.
If multiple role classes are bound to this base class the most
specific of these classes is chosen.
</p>
</div>
<div class="subsect depth4" id="s2.3.3.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Team as closed world</span><a class="img" href="s2.3.3.c.html"
title="PermaLink to (c)&nbsp;Team as closed world"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>In the above analysis gathering all role-base pairs is performed at
compile-time. From this follows, that a team class can only be
compiled when all its contained role classes are known and a role class
can never be compiled without its team.
<br />
The analysis includes all roles and their bindings that are inherited
from the super-team.
</p>
</div>
<div class="subsect depth4" id="s2.3.3.d">
<h4 class="subsect">(d)&nbsp;<span class="title">Selection regardless of abstractness</span><a class="img" href="s2.3.3.d.html"
title="PermaLink to (d)&nbsp;Selection regardless of abstractness"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Smart lifting is not affected by abstractness of role classes.
For the effect of abstract role classes see <a href="s2.5.html" title="&sect;2.5&nbsp;Abstract Roles" class="sect">&sect;2.5</a>.
</p>
</div>
<h5>Complex Example:</h5>
<p><img src="../images/smart_lifting_small.png" alt="smart lifting example" /></p>
<table border="2" width="80%">
<colgroup span="1">
<col align="left" span="1" />
<col align="left" span="1" />
</colgroup>
<tr>
<th rowspan="1" colspan="1">role class</th>
<th rowspan="1" colspan="1">base class</th>
</tr>
<tr>
<td rowspan="1" colspan="1">class R1</td>
<td rowspan="1" colspan="1">&nbsp;</td>
</tr>
<tr>
<td rowspan="1" colspan="1">class R2 extends R1 playedBy B2</td>
<td rowspan="1" colspan="1">class B2</td>
</tr>
<tr>
<td rowspan="1" colspan="1">class R3 extends R2 <em>/* inherited: playedBy B2 */ </em></td>
<td rowspan="1" colspan="1">class B3 extends B2</td>
</tr>
<tr>
<td rowspan="1" colspan="1">class R4 extends R3 playedBy B4</td>
<td rowspan="1" colspan="1">class B4 extends B3</td>
</tr>
<tr>
<td rowspan="1" colspan="1">class R5 extends R4 <em>/* inherited: playedBy B4 */</em></td>
<td rowspan="1" colspan="1">&nbsp;</td>
</tr>
<tr>
<td rowspan="1" colspan="1">&nbsp;</td>
<td rowspan="1" colspan="1">class B6 extends B4</td>
</tr>
<tr>
<td rowspan="1" colspan="1">class R7 extends R5 playedBy B7</td>
<td rowspan="1" colspan="1">class B7 extends B6</td>
</tr>
</table>
<div class="codecomment">
<ul>
<li>If declarations require lifting <code>B3</code> to <code>R1</code>
this is statically refined to use <code>R2</code> instead, because this
is the most general class declaring a binding to a super&ndash;class
of <code>B3</code>.
</li>
<li>If the dynamic base type in the same situation is <code>B6</code>,
three steps select the appropriate role:
<ol>
<li>By searching all <code>playedBy</code> clauses (including those
that are inherited) the following role&ndash;base pairs are
candidates:<br /><code>(R2,B2), (R3,B2), (R4,B4)</code> and <code>(R5,B4)</code>.
</li>
<li>From these pairs the two containing the most specific base class
<code>B4</code> are chosen.
</li>
<li>This makes <code>R4</code> and <code>R5</code> role candidates,
from which the most specific <code>R5</code> is finally chosen.
</li>
</ol>
</li>
</ul>
</div>
<p>If the inheritance hierarchies of the involved base and role classes are given (like in the figure above)
the smart lifting algorithm can be rephrased to the following "graphical" rule:<br /></p>
<div class="note">
Starting with the dynamic base type (<code>B6</code> in the example) move upwards the the inheritance
relation until you reach a base class bound to a role class indicated by a &laquo;playedBy&raquo;
arrow pointing to the base class (<code>B4</code>). This role class must be conform to the requested role type.
Switch to the role side along this arrow (<code>R4</code>). Now move downwards the role inheritance hierarchy
as long as the subrole does not refine the playedBy relationship (indicated by another &laquo;playedBy&raquo; arrow).
The bottom role you reach this way (<code>R5</code>) is the role type selected by smart lifting.
</div>
</div>
<div class="sect depth3" id="s2.3.4">
<h3 class="sect">&sect;2.3.4&nbsp;Binding ambiguities<a class="img" href="s2.3.4.html"
title="PermaLink to &sect;2.3.4&nbsp;Binding ambiguities"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#top">&uarr;&nbsp;&sect;2.3</a></span></h3>
<p>While all examples so far have only shown 1-to-1 class bindings,
several cases of multiple bindings are allowable. Ambiguities may be
detected at compile time and/or at runtime.
</p>
<div class="subsect depth4" id="s2.3.4.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Potential ambiguity</span><a class="img" href="s2.3.4.a.html"
title="PermaLink to (a)&nbsp;Potential ambiguity"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>A <strong>potential ambiguity</strong> is given,
if two role classes <code>R1</code> and <code>R2</code>
exist such that
</p>
<ul>
<li><code>R1</code> and <code>R2</code> are played by the
same base class <code>B</code>, and
</li>
<li><code>R1</code> and <code>R2</code> have a common
super role <code>R0</code>,
which is also bound to a base class <code>B0</code>, and
</li>
<li>neither role class <code>R1</code> nor
<code>R2</code> is a (indirect) sub-class of the other.
</li>
</ul>
<div class="note">
<h5>Note:</h5>
According to <a href="s2.1.c.html" title="&sect;2.1.(c)&nbsp;Covariant refinement"
class="sect">&sect;2.1.(c)</a>, if <code>B</code> is distinct from <code>B0</code>
it has to be a sub-class of <code>B0</code>.
</div>
<div class="note">
<h5>Effect:</h5>
In this case the compiler issues a warning, stating that the <code>B</code><em> may not be liftable,</em> because both role classes <code>R1</code>
and <code>R2</code> are candidates and there is no reason to prefer one over the other.
<br /><strong>If no potential ambiguity is detected, lifting will always be unambiguous.</strong></div>
<p>In the above situation, trying to lift an instance of type <code>B</code> to the role type
<code>R0</code> is an <strong>illegal lifting request</strong>. If <code>R0</code> is bound
to the same base class <code>B</code> as its sub-roles <code>R1</code> and <code>R2</code> are,
role <code>R0</code> is <strong>unliftable</strong>, meaning that no instance of <code>R0</code>
can ever by obtained by lifting.
</p>
<h5 class="listing">Example code (Potential Ambiguity):</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> MyTeam {</pre></td>
</tr>
<tr class="line even">
<td class="ln">2</td>
<td><pre> <b>public</b> <b>class</b> SuperRole <b>playedBy</b> MyBase {...}</pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre> <b>public</b> <b>class</b> SubRoleA <b>extends</b> SuperRole {...}</pre></td>
</tr>
<tr class="line even">
<td class="ln">4</td>
<td><pre> <b>public</b> <b>class</b> SubRoleB <b>extends</b> SuperRole {...}</pre></td>
</tr>
<tr class="line odd">
<td class="ln">5</td>
<td><pre>}</pre></td>
</tr>
</table>
</div>
</div>
<div class="subsect depth4" id="s2.3.4.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Definite ambiguity</span><a class="img" href="s2.3.4.b.html"
title="PermaLink to (b)&nbsp;Definite ambiguity"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>A <strong>definite ambiguity</strong> is given if
</p>
<ul>
<li>the situation of potential ambiguity according to (a)
above is given and
</li>
<li>lifting is requested (either by method binding or explicitly
(<a href="#s2.3.2" title="&sect;2.3.2&nbsp;Declared lifting" class="sect">&sect;2.3.2</a>)) from the shared base class <code>B</code> to any role
class <code>R0</code> that is a common super role for <code>R1</code> and <code>R2</code>.
</li>
</ul>
<div class="note">
<h5>Effect:</h5>
Definite ambiguity is a compile time error.
</div>
<h5 class="listing">Example code (Definite Ambiguity):</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> MyTeam {</pre></td>
</tr>
<tr class="line even">
<td class="ln">2</td>
<td><pre> <b>public</b> <b>class</b> SuperRole <b>playedBy</b> MyBase {...}</pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre> <b>public</b> <b>class</b> SubRoleA <b>extends</b> SuperRole <b>playedBy</b> SubBase {...}</pre></td>
</tr>
<tr class="line even">
<td class="ln">4</td>
<td><pre> <b>public</b> <b>class</b> SubRoleB <b>extends</b> SuperRole <b>playedBy</b> SubBase {...}</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> <b>public</b> <b>void</b> useSuperRole(SubBase <b>as</b> SuperRole r) {...}</pre></td>
</tr>
<tr class="line odd">
<td class="ln">7</td>
<td><pre>}</pre></td>
</tr>
</table>
</div>
</div>
<div class="subsect depth4" id="s2.3.4.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Actual ambiguity</span><a class="img" href="s2.3.4.c.html"
title="PermaLink to (c)&nbsp;Actual ambiguity"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>At runtime <strong>actual ambiguity</strong> may occur if for the
<em>dynamic type</em> of a base to be lifted the conditions of (b)
above hold accordingly. Actual ambiguity is only possible in cases
reported by the compiler as potential ambiguity.
</p>
<div class="note">
<h5>Effect:</h5>
An actual ambiguity is reported at runtime by throwing a
<code>org.objectteams.LiftingFailedException</code>.
</div>
<h5 class="listing">Example code (Actual Ambiguity):</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> MyTeam {</pre></td>
</tr>
<tr class="line even">
<td class="ln">2</td>
<td><pre> <b>public</b> <b>class</b> SuperRole <b>playedBy</b> MyBase {...}</pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre> <b>public</b> <b>class</b> SubRoleA <b>extends</b> SuperRole <b>playedBy</b> SubBase {...}</pre></td>
</tr>
<tr class="line even">
<td class="ln">4</td>
<td><pre> <b>public</b> <b>class</b> SubRoleB <b>extends</b> SuperRole <b>playedBy</b> SubBase {...}</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> <b>public</b> <b>void</b> useSuperRole(MyBase <b>as</b> SuperRole r) {...}</pre></td>
</tr>
<tr class="line odd">
<td class="ln">7</td>
<td><pre>}</pre></td>
</tr>
<tr class="line even">
<td class="ln">8</td>
<td><pre><span class="comment">// plus these calls:</span></pre></td>
</tr>
<tr class="line odd">
<td class="ln">9</td>
<td><pre>MyTeam mt = <b>new</b> MyTeam();</pre></td>
</tr>
<tr class="line even">
<td class="ln">10</td>
<td><pre>mt.useSuperRole(<b>new</b> SubBase());</pre></td>
</tr>
</table>
</div>
</div>
<div class="subsect depth4" id="s2.3.4.d">
<h4 class="subsect">(d)&nbsp;<span class="title">Mismatching role</span><a class="img" href="s2.3.4.d.html"
title="PermaLink to (d)&nbsp;Mismatching role"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>In cases of potential ambiguity another runtime error may occur:
a <strong>mismatching role</strong> is encountered when a role is found
in the cache, which is not conform to the required type.
This happens, if the base object has previously been lifted
to a type that is incompatible with the currently requested type.
</p>
<div class="note">
<h5>Effect:</h5>
This is reported by throwing a <code>org.objectteams.WrongRoleException</code>.
</div>
<h5 class="listing">Example code (Mismatching Role):</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> MyTeam {</pre></td>
</tr>
<tr class="line even">
<td class="ln">2</td>
<td><pre> <b>public</b> <b>class</b> SuperRole <b>playedBy</b> MyBase {...}</pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre> <b>public</b> <b>class</b> SubRoleA <b>extends</b> SuperRole {...}</pre></td>
</tr>
<tr class="line even">
<td class="ln">4</td>
<td><pre> <b>public</b> <b>class</b> SubRoleB <b>extends</b> SuperRole {...}</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> <b>public</b> <b>void</b> useRoleA(MyBase <b>as</b> SubRoleA r) {...}</pre></td>
</tr>
<tr class="line odd">
<td class="ln">7</td>
<td><pre> <b>public</b> <b>void</b> useRoleB(MyBase <b>as</b> SubRoleB r) {...}</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><span class="comment">// plus these calls:</span></pre></td>
</tr>
<tr class="line even">
<td class="ln">10</td>
<td><pre>MyTeam mt = <b>new</b> MyTeam();</pre></td>
</tr>
<tr class="line odd">
<td class="ln">11</td>
<td><pre>MyBase b = <b>new</b> MyBase();</pre></td>
</tr>
<tr class="line even">
<td class="ln">12</td>
<td><pre>mt.useRoleA(b); <span class="comment">// creates a SubRoleA for b</span></pre></td>
</tr>
<tr class="line odd">
<td class="ln">13</td>
<td><pre>mt.useRoleB(b); <span class="comment">// finds the SubRoleA which is not compatible</span></pre></td>
</tr>
<tr class="line even">
<td class="ln">14</td>
<td><pre> <span class="comment">// to the expected type SubRoleB.</span></pre></td>
</tr>
</table>
</div>
<p>From the second item of <a href="#s2.3.4.a" title="&sect;2.3.4.(a)&nbsp;Potential ambiguity"
class="sect">&sect;2.3.4.(a)</a> follows, that for binding ambiguities different
role hierarchies are analyzed in isolation.
For this analysis only those role classes are considered that are bound to a
base class (directly using <code>playedBy</code> or by inheriting this relation
from another role class).
I.e., two role classes that have no common bound super role will never cause
any ambiguity.
</p>
</div>
</div>
</div>
<table class="nav">
<tr>
<td class="back"><a href="s2.2.html" rel="prev">&lt;&lt;&nbsp;&sect;2.2&nbsp;Lowering</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="s2.4.html" rel="next">&sect;2.4&nbsp;Explicit role creation&nbsp;&gt;&gt;</a></td>
</tr>
</table>
<div class="breadcrumb"><a class="nav" href="s2.html" rel="section">&sect;2&nbsp;Role 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 &mdash; last modified: 2010-06-08
</div>
</body>
</html>