Gitiles
Code Review Sign In
git.eclipse.org / objectteams / org.eclipse.objectteams / 88c3ae23df5f12d0b13fbe9e1329d79859a39b2d / . / plugins / org.eclipse.objectteams.otdt.doc / guide / otjld / xdef / s2.3.4.html
blob: 017744babba8f1d8d89a813f14b902021ca3b4c8 [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.3.3.html" rel="prev">&lt;&lt;&nbsp;&sect;2.3.3&nbsp;Smart lifting</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.3.5.html" rel="next">&sect;2.3.5&nbsp;Consequences of lifting problems&nbsp;&gt;&gt;</a></td>
</tr>
</table>
<div class="breadcrumb"><a class="nav" href="s2.html" rel="section">&sect;2&nbsp;Role Binding</a>&nbsp;&gt;&nbsp;<a class="nav" href="s2.3.html" rel="section">&sect;2.3&nbsp;Lifting</a></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></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.html" 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>
<p>Definite binding ambiguity also occurs in cases of generic declared lifting <a href="s2.3.2.e.html" title="&sect;2.3.2.(e)&nbsp;Generic declared lifting"
class="sect">&sect;2.3.2.(e)</a>
if the specified role <code>R</code> is unbound and if two independent sub-roles <code>R1</code> and <code>R2</code>
exist that introduce a playedBy binding to the same base class <code>BX</code>.
In this case no potential ambiguity is flagged because roles <code>R1</code> and <code>R2</code>
have no shared bound super-role.
</p>
<div class="note">
<h5>Effect:</h5>
Code causing definite ambiguity is required to handle <code>org.objectteams.LiftingFailedException</code>.
</div>
<p>
In cases of definite binding ambiguity lifting will indeed fail except for some corner cases.
Such corner cases may arise if lifting already finds an appropriate role in the cache or
if an (indirect) subrole of the ambiguously bound role is an unambiguous lift target for the
concrete type of the base object at run-time. See also <a href="s2.3.5.html"
title="&sect;2.3.5&nbsp;Consequences of lifting problems"
class="sect">&sect;2.3.5</a>.
</p>
<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) {...} <span class="comment">// <span class="error">must declare LiftingFailedException</span></span></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 or definite 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>import</b> org.objectteams.LiftingFailedException;</pre></td>
</tr>
<tr class="line even">
<td class="ln">2</td>
<td><pre><b>team</b> <b>class</b> MyTeam {</pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre> <b>public</b> <b>class</b> SuperRole <b>playedBy</b> MyBase {...}</pre></td>
</tr>
<tr class="line even">
<td class="ln">4</td>
<td><pre> <b>public</b> <b>class</b> SubRoleA <b>extends</b> SuperRole <b>playedBy</b> SubBase {...}</pre></td>
</tr>
<tr class="line odd">
<td class="ln">5</td>
<td><pre> <b>public</b> <b>class</b> SubRoleB <b>extends</b> SuperRole <b>playedBy</b> SubBase {...}</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> <b>public</b> <b>void</b> useSuperRole(MyBase <b>as</b> SuperRole r) <b>throws</b> LiftingFailedException {...}</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>mt.useSuperRole(<b>new</b> SubBase()); <span class="comment">// <span class="error">will throw a LiftingFailedException</span></span></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>import</b> org.objectteams.LiftingFailedException;</pre></td>
</tr>
<tr class="line even">
<td class="ln">2</td>
<td><pre> <b>team</b> <b>class</b> MyTeam {</pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre> <b>public</b> <b>class</b> SuperRole <b>playedBy</b> MyBase {...}</pre></td>
</tr>
<tr class="line even">
<td class="ln">4</td>
<td><pre> <b>public</b> <b>class</b> SubRoleA <b>extends</b> SuperRole {...}</pre></td>
</tr>
<tr class="line odd">
<td class="ln">5</td>
<td><pre> <b>public</b> <b>class</b> SubRoleB <b>extends</b> SuperRole {...}</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> <b>public</b> <b>void</b> useRoleA(MyBase <b>as</b> SubRoleA r) <b>throws</b> LiftingFailedException {...}</pre></td>
</tr>
<tr class="line even">
<td class="ln">8</td>
<td><pre> <b>public</b> <b>void</b> useRoleB(MyBase <b>as</b> SubRoleB r) <b>throws</b> LiftingFailedException {...}</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><span class="comment">// plus these calls:</span></pre></td>
</tr>
<tr class="line odd">
<td class="ln">11</td>
<td><pre>MyTeam mt = <b>new</b> MyTeam();</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>mt.useRoleA(b); <span class="comment">// creates a SubRoleA for b</span></pre></td>
</tr>
<tr class="line even">
<td class="ln">14</td>
<td><pre>mt.useRoleB(b); <span class="comment">// <span class="error">finds the SubRoleA which is not compatible</span></span></pre></td>
</tr>
<tr class="line odd">
<td class="ln">15</td>
<td><pre> <span class="comment">// <span class="error">to the expected type SubRoleB.</span></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>
<table class="nav">
<tr>
<td class="back"><a href="s2.3.3.html" rel="prev">&lt;&lt;&nbsp;&sect;2.3.3&nbsp;Smart lifting</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.3.5.html" rel="next">&sect;2.3.5&nbsp;Consequences of lifting problems&nbsp;&gt;&gt;</a></td>
</tr>
</table>
<div class="breadcrumb"><a class="nav" href="s2.html" rel="section">&sect;2&nbsp;Role Binding</a>&nbsp;&gt;&nbsp;<a class="nav" href="s2.3.html" rel="section">&sect;2.3&nbsp;Lifting</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: 2011-05-15
</div>
</body>
</html>