blob: 9f7a037e295cb734970d67029753cff691b31503 [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="s1.html" rel="prev">&lt;&lt;&nbsp;&sect;1&nbsp;Teams and Roles</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.html" rel="next">&sect;3&nbsp;Callout Binding&nbsp;&gt;&gt;</a></td>
</tr>
</table>
<div class="chapter" id="s2">
<div class="headl">
<div class="headr">
<h1>&sect;2&nbsp;Role Binding</h1>
</div>
</div>
<div id="toc-box">
<ul class="toc-box">
<li><a href="s2.html">&sect;2&nbsp;Role Binding</a></li>
<li><a href="#s2.1">&sect;2.1&nbsp;playedBy relation</a></li>
<li><a href="#s2.2">&sect;2.2&nbsp;Lowering</a></li>
<li><a href="#s2.3">&sect;2.3&nbsp;Lifting</a></li>
<li><a href="#s2.4">&sect;2.4&nbsp;Explicit role creation</a></li>
<li><a href="#s2.5">&sect;2.5&nbsp;Abstract Roles</a></li>
<li><a href="#s2.6">&sect;2.6&nbsp;Explicit base references</a></li>
<li><a href="#s2.7">&sect;2.7&nbsp;Advanced structures</a></li>
</ul>
</div>
<div class="intro">
<h3>Roles and base classes</h3>
<div class="line"></div>
<div class="term">playedBy relation</div>
<div class="termdesc">A role can be bound to a class outside the team by a <code>playedBy</code>
relation, which declares that each role instances is associated to a
base instances.
</div>
<div class="line"></div>
<div class="term">Base class</div>
<div class="termdesc">The class to which a role is bound (using <code>playedBy</code>) is called
its <strong>base class</strong>. Role instances may inherit and override
features from their base instance, which is declared using <strong>callout</strong>
(<a href="s3.html" title="&sect;3&nbsp;Callout Binding" class="sect">&sect;3</a>)
and <strong>callin</strong> (<a href="s4.html" title="&sect;4&nbsp;Callin Binding" class="sect">&sect;4</a>) method bindings.
</div>
<div class="line"></div>
<div class="term">Bound role</div>
<div class="termdesc">Each role class that declares a <code>playedBy</code> relation
is called a <strong>bound role</strong>. The term bound role may also be
used for the instances of such a class.
</div>
<div class="line"></div>
<div class="term">Lifting / lowering</div>
<div class="termdesc">Translations between a role and its base are called
<strong>lifting</strong> (base to role) (<a href="#s2.3" title="&sect;2.3&nbsp;Lifting" class="sect">&sect;2.3</a>)
and <strong>lowering</strong> (role to base) (<a href="#s2.2" title="&sect;2.2&nbsp;Lowering" class="sect">&sect;2.2</a>).
</div>
<div class="line"></div>
<div class="term">Translation polymorphism</div>
<div class="termdesc">Conformance between a role and a base is governed by <strong>translation polymorphism</strong>,
which refers to a substitutability that is achieved using either lifting or lowering.
</div>
<div class="line"></div>
<div class="term">Declared lifting</div>
<div class="termdesc">Generally, lifting happens implicitly at data flows between
a role object and its base. Team level methods provide additional
data flows, where lifting may be declared explicitly.
</div>
<div class="line"></div>
</div>
<div class="sect depth2" id="s2.1">
<h2 class="sect">&sect;2.1&nbsp;playedBy relation<a class="img" href="s2.html#s2.1"
title="PermaLink to &sect;2.1&nbsp;playedBy relation"><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</a></span></h2>
<div class="syntaxlink"><a href="sA.html#sA.1.1" title="&sect;A.1.1&nbsp;ClassDeclaration"
class="syntax">&rarr;&nbsp;Syntax&nbsp;&sect;A.1.1</a></div>
<div class="subsect depth3" id="s2.1.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Role-base binding</span><a class="img" href="s2.html#s2.1.a"
title="PermaLink to (a)&nbsp;Role-base binding"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Roles are bound to a base class by the <code>playedBy</code> keyword.
</p>
<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>class</b> MyRole <em><b>playedBy</b> MyBase</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> }</pre></td>
</tr>
<tr class="line odd">
<td class="ln">5</td>
<td><pre>}</pre></td>
</tr>
</table>
</div>
</div>
<div class="subsect depth3" id="s2.1.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Inheritance</span><a class="img" href="s2.html#s2.1.b" title="PermaLink to (b)&nbsp;Inheritance"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>The <code>playedBy</code> relation is inherited along
explicit and implicit (<a href="s1.html#s1.3.1.c"
title="&sect;1.3.1.(c)&nbsp;Overriding and implicit inheritance"
class="sect">&sect;1.3.1.(c)</a>)
role inheritance.
</p>
</div>
<div class="subsect depth3" id="s2.1.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Covariant refinement</span><a class="img" href="s2.html#s2.1.c"
title="PermaLink to (c)&nbsp;Covariant refinement"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>An <em>explicit</em> sub-role (sub-class using <code>extends</code>)
can refine the <code>playedBy</code> relation to a more
specific base class (this is the basis for
<a href="#s2.3.3" title="&sect;2.3.3&nbsp;Smart lifting" class="sect">smart lifting (&sect;2.3.3)</a>).<br />
If a role class inherits several <code>playedBy</code> relations from
its super-class and its super-interfaces, there must be a most specific
base-class among these relations, which is conform to all other base-classes.
This most specific base-class is the base-class of the current role.
</p>
</div>
<div class="subsect depth3" id="s2.1.d">
<h4 class="subsect">(d)&nbsp;<span class="title">No-variance</span><a class="img" href="s2.html#s2.1.d" title="PermaLink to (d)&nbsp;No-variance"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>An <em>implicit</em> sub-role (according to <a href="s1.html#s1.3.1.c"
title="&sect;1.3.1.(c)&nbsp;Overriding and implicit inheritance"
class="sect">&sect;1.3.1.(c)</a>)
may only add a <code>playedBy</code> relation but never change an existing one.<br />
Note however, that implicit inheritance may implicitly specialize an existing <code>playedBy</code>
relation (this advanced situation is illustrated in <a href="#s2.7.d" title="&sect;2.7.(d)&nbsp;Implicit playedBy specialization"
class="sect">&sect;2.7.(d)</a>).
</p>
</div>
<div class="subsect depth3" id="s2.1.e">
<h4 class="subsect">(e)&nbsp;<span class="title">Use of playedBy bindings</span><a class="img" href="s2.html#s2.1.e"
title="PermaLink to (e)&nbsp;Use of playedBy bindings"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>The <code>playedBy</code> relation by itself has no effect
on the behavior of role and base objects.
It is, however, the precondition for translation polymorphism
(lowering: <a href="#s2.2" title="&sect;2.2&nbsp;Lowering" class="sect">&sect;2.2</a> and lifting: <a href="#s2.3" title="&sect;2.3&nbsp;Lifting" class="sect">&sect;2.3</a>)
and for method bindings (callout: <a href="s3.html" title="&sect;3&nbsp;Callout Binding" class="sect">&sect;3</a> and callin: <a href="s4.html" title="&sect;4&nbsp;Callin Binding" class="sect">&sect;4</a>).
</p>
</div>
<div class="subsect depth3" id="s2.1.f">
<h4 class="subsect">(f)&nbsp;<span class="title">Effect on garbage collection</span><a class="img" href="s2.html#s2.1.f"
title="PermaLink to (f)&nbsp;Effect on garbage collection"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>A role and its base object form one conceptual entity. The garbage collector will see a role
and its base object as linked in a bidirectional manner. As a result, a role cannot be
garbage collected if its base is still reachable and vice versa.
<br />
Internally a team manages its roles and corresponding bases using weak references.
When using one of the <code>getAllRoles(..)</code>
methods (see <a href="s6.html#s6.1.a"
title="&sect;6.1.(a)&nbsp;Interface to the role registry"
class="sect">&sect;6.1.(a)</a>),
the result may be non-deterministic because these internal structures
may hold weak references to objects that will be collected by the next run of the
garbage collector. We advise clients of <code>getAllRoles(..)</code> to call
<code>System.gc()</code> prior to calling <code>getAllRoles(..)</code> in order
to ensure deterministic results.
</p>
</div>
<div class="sect depth3" id="s2.1.1">
<h3 class="sect">&sect;2.1.1&nbsp;Binding interfaces<a class="img" href="s2.html#s2.1.1"
title="PermaLink to &sect;2.1.1&nbsp;Binding interfaces"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#s2.1">&uarr;&nbsp;&sect;2.1</a></span></h3>
<p>Role base bindings may involve classes and/or interfaces.
An interface defined as a member of a team is a role interface and may therefore
have a <code>playedBy</code> clause. Also the type mentioned after the
<code>playedBy</code> keyword may be an interface.
</p>
<div class="note">
<h5>Implementation limitation:</h5>
The language implementation as of OTDT version 2.0
imposes one particular restriction when binding a role to a base interface:
A role binding to a base interface may not contain any callin bindings (<a href="s4.html" title="&sect;4&nbsp;Callin Binding" class="sect">&sect;4</a>).
</div>
</div>
<div class="sect depth3" id="s2.1.2">
<h3 class="sect">&sect;2.1.2&nbsp;Legal base classes<a class="img" href="s2.html#s2.1.2"
title="PermaLink to &sect;2.1.2&nbsp;Legal base classes"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#s2.1">&uarr;&nbsp;&sect;2.1</a></span></h3>
<p>Generally, the base class mentioned after <code>playedBy</code> must be
visible in the enclosing scope (see <a href="#s2.1.2.c" title="&sect;2.1.2.(c)&nbsp;Base class decapsulation"
class="sect">below (&sect;2.1.2.(c))</a> for an exception).
Normally, this scope is defined just by the imports of the enclosing team.
For role files (<a href="s1.html#s1.2.5.b" title="&sect;1.2.5.(b)&nbsp;Role files"
class="sect">&sect;1.2.5.(b)</a>)
also additional imports in the role file are considered.
<br /><a href="#s2.1.2.d" title="&sect;2.1.2.(d)&nbsp;Base imports" class="sect">&sect;2.1.2.(d)</a> below defines how imports can be constrained so that certain types
can be used as base types, only.
</p>
<div class="subsect depth4" id="s2.1.2.a">
<h4 class="subsect">(a)&nbsp;<span class="title">No role of the same team</span><a class="img" href="s2.html#s2.1.2.a"
title="PermaLink to (a)&nbsp;No role of the same team"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>The base class of any role class must not be a role of the same team.
<br />
It is also not allowed to declare a role class of the same name
as a base class bound to this or another role of the enclosing team,
if that base class is given with its simple name and resolved using a regular import.
Put differently, a base class mentioned after <code>playedBy</code>
may not be <em>shadowed</em> by any role class of the enclosing team.
<br /><em>Base imports</em> as defined below (<a href="#s2.1.2.d" title="&sect;2.1.2.(d)&nbsp;Base imports" class="sect">&sect;2.1.2.(d)</a>) relax this rule by
allowing to import a class as a base class only. In that case no shadowing occurs since the scopes for
base classes and roles are disjoint.
</p>
</div>
<div class="subsect depth4" id="s2.1.2.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Cycles</span><a class="img" href="s2.html#s2.1.2.b" title="PermaLink to (b)&nbsp;Cycles"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>The base class mentioned after <code>playedBy</code> should normally not be
an enclosing type (at any depth) of the role class being defined.
<br />
This rule discourages the creation of cycles where the base instance of
a given role <code>R</code> contains roles of the same type <code>R</code>.
<br />
More generally this concerns any sequence of classes <code>C<sub>1</sub>, C<sub>2</sub>, .. C<sub>n</sub></code>
were each <code>C<sub>i+1</sub></code> is either a member or the base class of
<code>C<sub>i</sub></code> and <code>C<sub>n</sub> = C<sub>1</sub></code>.
<br />
Such structures may be difficult to understand and have certain restrictions regarding
callout (<a href="s3.html#s3.1.a"
title="&sect;3.1.(a)&nbsp;Prerequisite: Class binding"
class="sect">&sect;3.1.(a)</a>) and base constructor calls (<a href="#s2.4.2"
title="&sect;2.4.2&nbsp;Role creation via a regular constructor"
class="sect">&sect;2.4.2</a>).
It is furthermore recommended to equip all roles that are played by an enclosing class with a guard predicate (<a href="s5.html#s5.4" title="&sect;5.4&nbsp;Guard predicates" class="sect">&sect;5.4</a>) like this:
</p>
<div class="listing plain"><pre><em>base</em><em> when</em> (MyTeam.this == <em>base</em>)</pre></div>
<p>
This will avoid that the role adapts other instances of the enclosing class which are not the enclosing instance.
</p>
<p>
It is prohibited to bind a role class to its own inner class.
</p>
</div>
<div class="subsect depth4" id="s2.1.2.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Base class decapsulation</span><a class="img" href="s2.html#s2.1.2.c"
title="PermaLink to (c)&nbsp;Base class decapsulation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>If a base class referenced after <code>playedBy</code> exists but is not visible under normal visibility rules of Java,
this restriction may be overridden. This concept is called <strong>decapsulation</strong>, i.e., the opposite of encapsulation
(see also <a href="s3.html#s3.4" title="&sect;3.4&nbsp;Overriding access restrictions"
class="sect">&sect;3.4</a>). A compiler should signal any occurrence of base class 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.
</p>
<p>
Binding to a <code>final</code> base class is also considered as decapsulation, since a <code>playedBy</code> relationship has
powers similar to an <code>extends</code> relationship, which is prohibited by marking a class as <code>final</code>.
</p>
<p>
Decapsulation is not allowed if the base class is a confined role (see <a href="s7.html#s7.2" title="&sect;7.2&nbsp;Confined roles" class="sect">&sect;7.2</a>).
</p>
<p>
Within the current role a decapsulated base class can be mentioned in the right-hand-side of any method binding
(<a href="s3.html" title="&sect;3&nbsp;Callout Binding" class="sect">callout (&sect;3)</a> or <a href="s4.html" title="&sect;4&nbsp;Callin Binding" class="sect">callin (&sect;4)</a>). Also arguments in these positions are allowed to mention the decapsulated base class:
</p>
<ul>
<li>the first argument of one of the role's constructors (see <a href="#s2.4.1"
title="&sect;2.4.1&nbsp;Role creation via a lifting constructor"
class="sect">lifting constructor (&sect;2.4.1)</a>).
</li>
<li>the base side of an argument with declared lifting (see <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 depth4" id="s2.1.2.d">
<h4 class="subsect">(d)&nbsp;<span class="title">Base imports</span><a class="img" href="s2.html#s2.1.2.d"
title="PermaLink to (d)&nbsp;Base imports"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>If the main type in a file denotes a team, the modifier <code>base</code> can be applied to a single import in order to specify that this type
should be imported for application as a base type only. Example:
</p>
<div class="listing example frame">
<table class="listing">
<tr class="line odd">
<td class="ln">1</td>
<td><pre><em><b>import</b> base</em> some.pack.MyBase;</pre></td>
</tr>
<tr class="line even">
<td class="ln">2</td>
<td><pre><b>public</b> <b>team</b> <b>class</b> MyTeam {</pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre> <span class="comment">// simple name resolves to imported class:</span></pre></td>
</tr>
<tr class="line even">
<td class="ln">4</td>
<td><pre> <b>protected</b> <b>class</b> MyRole <em><b>playedBy</b> MyBase</em> { } </pre></td>
</tr>
<tr class="line odd">
<td class="ln">5</td>
<td><pre> <span class="error"><em>MyBase</em> illegalDeclaration;</span> <span class="comment">// base import does not apply for this position</span></pre></td>
</tr>
<tr class="line even">
<td class="ln">6</td>
<td><pre>}</pre></td>
</tr>
</table>
</div>
<p>Base imports cannot be on-demand imports (using the wildcard <code>.*</code>).<br />
Types imported by a base import can only be used in the same positions where also base class decapsulation (<a href="#s2.1.2.c" title="&sect;2.1.2.(c)&nbsp;Base class decapsulation"
class="sect">&sect;2.1.2.(c)</a>)
is applicable.<br />
It is recommended that a type mentioned after the keyword <code>playedBy</code> is always imported with the <code>base</code> modifier, otherwise the compiler
will give a warning.<br />
Base imports create a scope that is disjoint from the normal scope. Thus, names that are imported as base will never clash
with normally visible names
(in contrast to <a href="s1.html#s1.4" title="&sect;1.4&nbsp;Name clashes" class="sect">&sect;1.4</a>). More specifically, it is not a problem to use a base class's name also for its role if a base import is used.
</p>
</div>
<div class="subsect depth4" id="s2.1.2.e">
<h4 class="subsect">(e)&nbsp;<span class="title">No free type parameters</span><a class="img" href="s2.html#s2.1.2.e"
title="PermaLink to (e)&nbsp;No free type parameters"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>
Neither the role class nor the base class in a playedBy binding must have any <em>free type parameters</em>.
If both classes are specified with a type parameter of the same name, both parameters are identified
and are not considered as <em>free</em>.
</p>
<p>
From this follows that a role class cannot have more type parameters than its base.
Conversely, only one situation exists where a base class can have more type parameters than a role class
bound to it: if the role class has no type parameters a generic base class can be bound using
the base class's raw type, i.e., without specifying type arguments.
</p>
<div class="note">
<h5>Note:</h5>
The information from the <code>playedBy</code> declaration is used at run-time
to associate role instances to base instances.
Specifying a base class with free type parameters would imply that only such base instances
are decorated by a role whose type is conform to the specified parameterized class.
However, type arguments are not available at run-time, thus the run-time environment
is not able to decide which base instances should have a role and which should not.
This is due to the design of generics in Java which are realized by erasure.
</div>
<p>The following example shows how generics can be used in various positions. Note, that some of the concepts used in the example
will be explained in later sections.
</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> ValueTrafo<em>&lt;T&gt;</em> {</pre></td>
</tr>
<tr class="line even">
<td class="ln">2</td>
<td><pre> <b>public</b> <em>T</em> transform(<em>T</em> val) <b>throws</b> Exception { /* ... */ }</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>team</b> <b>class</b> TransformTeam {</pre></td>
</tr>
<tr class="line odd">
<td class="ln">5</td>
<td><pre> <b>protected</b> <b>class</b> SafeTrafo<em>&lt;U&gt;</em> <b>playedBy</b> ValueTrafo<em>&lt;U&gt;</em> {</pre></td>
</tr>
<tr class="line even">
<td class="ln">6</td>
<td><pre> <em>U</em> transform(<em>U</em> v) <b>-&gt;</b> <em>U</em> transform(<em>U</em> val); </pre></td>
</tr>
<tr class="line odd">
<td class="ln">7</td>
<td><pre> <b>protected</b> <em>U</em> safeTransform(<em>U</em> v) {</pre></td>
</tr>
<tr class="line even">
<td class="ln">8</td>
<td><pre> <b>try</b> {</pre></td>
</tr>
<tr class="line odd">
<td class="ln">9</td>
<td><pre> <b>return</b> transform(v);</pre></td>
</tr>
<tr class="line even">
<td class="ln">10</td>
<td><pre> } <b>catch</b> (Exception e) {</pre></td>
</tr>
<tr class="line odd">
<td class="ln">11</td>
<td><pre> <b>return</b> v;</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> }</pre></td>
</tr>
<tr class="line even">
<td class="ln">14</td>
<td><pre> }</pre></td>
</tr>
<tr class="line odd">
<td class="ln">15</td>
<td><pre> <em>&lt;V&gt; V</em> perform(ValueTrafo<em>&lt;V&gt;</em> <b>as</b> SafeTrafo<em>&lt;V&gt;</em> trafo, <em>V</em> value) {</pre></td>
</tr>
<tr class="line even">
<td class="ln">16</td>
<td><pre> <b>return</b> trafo.safeTransform(value);</pre></td>
</tr>
<tr class="line odd">
<td class="ln">17</td>
<td><pre> } </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>...</pre></td>
</tr>
<tr class="line even">
<td class="ln">20</td>
<td><pre>ValueTrafo<em>&lt;String&gt;</em> trafo = <b>new</b> ValueTrafo<em>&lt;String&gt;</em>();</pre></td>
</tr>
<tr class="line odd">
<td class="ln">21</td>
<td><pre>TransformTeam safeTrafo = <b>new</b> TransformTeam();</pre></td>
</tr>
<tr class="line even">
<td class="ln">22</td>
<td><pre>String s = safeTrafo.perform(trafo, "Testing");</pre></td>
</tr>
<tr class="line odd">
<td class="ln">23</td>
<td><pre></pre></td>
</tr>
</table>
</div>
<div class="codecomment">
<h5>Explanation</h5>
<ul>
<li>Line 5 shows a role with type parameter <code>U</code> where the type parameter is identified with the
corresponding type parameter of the role's base class (which is originally declared as <code>T</code> in line 1.
</li>
<li>Line 6 shows a callout binding (<a href="s3.html" title="&sect;3&nbsp;Callout Binding" class="sect">&sect;3</a>) which mappes a base method to a corresponding role method
while maintaining the flexible typing.
</li>
<li>The regular method in lines 7-13 just passes values of type <code>U</code> around.
</li>
<li>The generic method in line 15 ff. uses declared lifting (<a href="#s2.3.2" title="&sect;2.3.2&nbsp;Declared lifting" class="sect">&sect;2.3.2</a>) to obtain a role for a given base object.
The method has no knowledge about the concrete type arguments of either role nor base, but works under the guarantee
that both type arguments will be the same for any single invocation.
</li>
<li>Lines 20 ff. finally create instances of base and team and invoke the behavior thereby instantiating type parameters to <code>String</code>.
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect depth2" id="s2.2">
<h2 class="sect">&sect;2.2&nbsp;Lowering<a class="img" href="s2.html#s2.2"
title="PermaLink to &sect;2.2&nbsp;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;2</a></span></h2>
<p>Each instance of a bound role class internally stores a reference to its
base object. The reference is guaranteed to exist for each bound role
instance, and cannot be changed during its lifetime.
</p>
<div class="subsect depth3" id="s2.2.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Definition of lowering</span><a class="img" href="s2.html#s2.2.a"
title="PermaLink to (a)&nbsp;Definition of lowering"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Retrieving the base object from a role object is called <strong>lowering</strong>.
No other means exists for accessing the base reference.
</p>
</div>
<div class="subsect depth3" id="s2.2.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Places of lowering</span><a class="img" href="s2.html#s2.2.b"
title="PermaLink to (b)&nbsp;Places of lowering"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>The lowering translation is not meant to be invoked
by client code, but <strong>implicit translations</strong> are inserted by
the compiler at all places where a role type is provided while the
corresponding base type (or a super type) was expected.<br />
In other words: lowering translations are inserted by the compiler at
all places in a program which would otherwise not be type correct
and which using lowering are statically type correct.
This may concern:
</p>
<ul>
<li>the right hand side of an assignment wrt. the static type of the left hand side,</li>
<li>the argument values of a method or constructor call wrt. the static type of the corresponding formal parameter,</li>
<li>the return value of a method compared to the declared return type of the method.</li>
<li>a role parameter in a callout binding (<a href="s3.html#s3.3.d" title="&sect;3.3.(d)&nbsp;Typing rules" class="sect">&sect;3.3.(d)</a>)
</li>
<li>or the return value in a callin binding (<a href="s4.html#s4.5.d" title="&sect;4.5.(d)&nbsp;Typing rules" class="sect">&sect;4.5.(d)</a>)
</li>
</ul>
<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>class</b> <em>MyRole <b>playedBy</b> MyBase</em> { ... }</pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre> <b>void</b> useMyBase(<em>MyBase</em> myb) {...}</pre></td>
</tr>
<tr class="line even">
<td class="ln">4</td>
<td><pre> <em>MyRole</em> returnMyRole() {...}</pre></td>
</tr>
<tr class="line odd">
<td class="ln">5</td>
<td><pre> <b>public</b> <b>void</b> doSomething() {</pre></td>
</tr>
<tr class="line even">
<td class="ln">6</td>
<td><pre> <em>MyRole r</em> = <b>new</b> MyRole(<b>new</b> MyBase());</pre></td>
</tr>
<tr class="line odd">
<td class="ln">7</td>
<td><pre> <em>MyBase b</em> = <em>r</em>;</pre></td>
</tr>
<tr class="line even">
<td class="ln">8</td>
<td><pre> useMyBase(<em>r</em>);</pre></td>
</tr>
<tr class="line odd">
<td class="ln">9</td>
<td><pre> <em>MyBase b2</em> = returnMyRole();</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>}</pre></td>
</tr>
</table>
</div>
<div class="codecomment">
<h5>Effects:</h5>
<p>An instance of type <code>MyRole</code> is lowered to type <code>MyBase</code> when
</p>
<ul>
<li>assigning it to <code>b</code> (line 7)
</li>
<li>passing it as argument to a method with formal parameter of type <code>MyBase</code> (line 8)
</li>
<li>assigning the return value to a variable of type <code>MyBase</code> (line 9)
</li>
</ul>
<p><em>Note</em>: The constructor call in line 6 uses the <em>lifting constructor</em> as defined in <a href="#s2.4.1"
title="&sect;2.4.1&nbsp;Role creation via a lifting constructor"
class="sect">&sect;2.4.1</a></p>
</div>
<p>Lowering translations are <span class="underline">not</span> inserted for
</p>
<ul>
<li>reference comparison (using <code>==</code> or <code>!=</code>)
</li>
<li><code>instanceof</code> checks
</li>
<li>cast expressions</li>
<li>return values in callout bindings <a href="s3.html#s3.3.d" title="&sect;3.3.(d)&nbsp;Typing rules" class="sect">&sect;3.3.(d)</a>)
</li>
<li>parameters in callin bindings (<a href="s4.html#s4.5.d" title="&sect;4.5.(d)&nbsp;Typing rules" class="sect">&sect;4.5.(d)</a>)
</li>
</ul>
<p>For cases where lowering shall be <em>forced</em> see <a href="#s2.2.d" title="&sect;2.2.(d)&nbsp;Explicit lowering" class="sect">&sect;2.2.(d)</a> below.
</p>
</div>
<div class="subsect depth3" id="s2.2.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Typing</span><a class="img" href="s2.html#s2.2.c" title="PermaLink to (c)&nbsp;Typing"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>The static type of an implicit lowering translation is the base class
declared using <code>playedBy</code> in the respective role class.
</p>
</div>
<div class="subsect depth3" id="s2.2.d">
<h4 class="subsect">(d)&nbsp;<span class="title">Explicit lowering</span><a class="img" href="s2.html#s2.2.d"
title="PermaLink to (d)&nbsp;Explicit lowering"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>If a base type is also the super type of its role,
which frequently happens, if a base reference is known only by
the type <code>Object</code>, lowering cannot be deduced automatically,
since a type could be interpreted both as a role type and a base type.
These cases may need <strong>explicit lowering</strong>.
For this purpose the role class must declare to implement the interface
<strong><code>ILowerable</code></strong> (from <code>org.objectteams.ITeam</code>).
This will cause the compiler to generate a method
</p>
<div class="listing plain"><pre><b>public</b> Object lower()</pre></div>
<p>for the given role class. Client code may use this method to
explicitly request the base object of a given role object.
</p>
<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>class</b> MyRole <em><b>implements</b> ILowerable</em> <b>playedBy</b> MyBase { ... }</pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre> <b>public</b> <b>void</b> doSomething() {</pre></td>
</tr>
<tr class="line even">
<td class="ln">4</td>
<td><pre> MyRole r = <b>new</b> MyRole(<b>new</b> MyBase());</pre></td>
</tr>
<tr class="line odd">
<td class="ln">5</td>
<td><pre> Object oMyRole = r;</pre></td>
</tr>
<tr class="line even">
<td class="ln">6</td>
<td><pre> Object oMyBase = r.<em>lower()</em>;</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>}</pre></td>
</tr>
</table>
</div>
</div>
<div class="subsect depth3" id="s2.2.e">
<h4 class="subsect">(e)&nbsp;<span class="title">Lowering of arrays</span><a class="img" href="s2.html#s2.2.e"
title="PermaLink to (e)&nbsp;Lowering of arrays"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Lowering also works for arrays of role objects.
In order to lower an array of role objects,
a new array is created and filled with base objects, one for each
role object in the original array. The array may have any number
of dimensions at any shape. The lowered array will have exactly the
same shape.<br />
Note, that each lowering translation will create a new array.
</p>
</div>
<div class="subsect depth3" id="s2.2.f">
<h4 class="subsect">(f)&nbsp;<span class="title">Ambiguous lowering</span><a class="img" href="s2.html#s2.2.f"
title="PermaLink to (f)&nbsp;Ambiguous lowering"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>When assigning a value of a bound role type to a variable or argument of type <code>java.lang.Object</code>
this situation is considered as ambiguous lowering because the assignment could apply either (a) a direct upcast to <code>Object</code>
or (b) lowering and then upcasting.
In such situations the compiler will <em>not</em> insert a lowering translation, but a configurable warning will be issued.
</p>
</div>
</div>
<div class="sect depth2" id="s2.3">
<h2 class="sect">&sect;2.3&nbsp;Lifting<a class="img" href="s2.html#s2.3" title="PermaLink to &sect;2.3&nbsp;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</a></span></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.html#s2.3.a"
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.html#s2.3.b"
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.html#s3.3.c" title="&sect;3.3.(c)&nbsp;Result translation"
class="sect">Callout bindings (&sect;3.3.(c))</a> (result)
</li>
<li><a href="s4.html#s4.5.a" 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.html#s2.3.c" 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.html#s2.3.d"
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.html#s2.3.1"
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="#s2.3">&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.html#s2.3.1.a"
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.html#s2.3.1.b"
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.html#s2.3.1.c"
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 class="subsect depth4" id="s2.3.1.d">
<h4 class="subsect">(d)&nbsp;<span class="title">Fine-tuning role instantiation</span><a class="img" href="s2.html#s2.3.1.d"
title="PermaLink to (d)&nbsp;Fine-tuning role instantiation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>If the lifting operation as defined above degrades the program performance, the lifting semantics can be modified per role
class
by adding the annotation <code>@org.objectteams.Instantiation</code> which requires an argument of type
<code>org.objectteams.InstantiationPolicy</code> in order to select between the following behaviors:
</p>
<dl>
<dt>ONDEMAND</dt>
<dd>This is the default behavior as defined above.</dd>
<dt>ALWAYS</dt>
<dd>This strategy avoids maintaining the internal role cache, but instead a fresh role instance is created for each lifting request.
This may increase the number of role instances but cuts the costs of accessing the cache, which could otherwise become
expensive if a cache grows large. As a result of this strategy role state can no longer be shared
over time, thus it is discouraged to define fields in a role with this strategy. Also, comparing roles could lead
to
unexpected results. Therefor, roles with this strategy should implement custom <code>equals</code> and <code>hashCode</code>
methods, which should simply delegate to the base instance (using callout <a href="s3.html" title="&sect;3&nbsp;Callout Binding" class="sect">&sect;3</a>).
</dd>
<dt>NEVER</dt>
<dd>Roles with this instantiation policy are never instantiated by lifting.
Such roles cannot define non-static fields.
Otherwise this optimization is fully transparent, specifically callout bindings will refer to the correct base instance.<br />
As of version 2.0 the OT/J compiler does not implement this strategy.
</dd>
<dt>SINGLETON</dt>
<dd>Roles declaring this strategy will be instantiated at most once per team. Subsequent lifting requests in the same team
will always answer the same role instance. Such roles may receive triggers from callin bindings, but cannot define
callout bindings.<br />
As of version 2.0 the OT/J compiler does not implement this strategy.
</dd>
</dl>
</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.html#s2.3.2"
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="#s2.3">&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.html#s2.3.2.a"
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.html#s2.3.2.b"
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.html#s2.3.2.c"
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.html#s2.3.2.d"
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.html#s2.3.2.e"
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.html#s2.3.3"
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="#s2.3">&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.html#s2.3.3.a"
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.html#s4.5.d" 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.html#s2.3.3.b"
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.html#s2.3.3.c"
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.html#s2.3.3.d"
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" 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.html#s2.3.4"
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="#s2.3">&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.html#s2.3.4.a"
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" 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.html#s2.3.4.b"
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>
<p>Definite binding ambiguity also occurs in cases of generic declared lifting <a href="#s2.3.2.e" 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" 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.html#s2.3.4.c"
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.html#s2.3.4.d"
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>
<div class="sect depth3" id="s2.3.5">
<h3 class="sect">&sect;2.3.5&nbsp;Consequences of lifting problems<a class="img" href="s2.html#s2.3.5"
title="PermaLink to &sect;2.3.5&nbsp;Consequences of lifting problems"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#s2.3">&uarr;&nbsp;&sect;2.3</a></span></h3>
<p>The rules for lifting and role binding allow (after issuing a warning) two problematic situations:</p>
<ol>
<li>A potential binding ambiguity makes selection of the approprate role type impossible (<a href="#s2.3.4.a" title="&sect;2.3.4.(a)&nbsp;Potential ambiguity"
class="sect">&sect;2.3.4.(a)</a>)
</li>
<li>A role which might be relevant for lifting is abstract (<a href="#s2.5.b" title="&sect;2.5.(b)&nbsp;Relevant roles" class="sect">&sect;2.5.(b)</a>)
</li>
</ol>
<p>Whenever lifting fails for one of these reasons an <code>org.objectteams.LiftingFailedException</code> (<a href="s6.html#s6.2.d" title="&sect;6.2.(d)&nbsp;Exceptions" class="sect">&sect;6.2.(d)</a>)
is thrown.
Given that this is a checked exception and depending on the location requiring lifting this has the following consequences:
</p>
<div class="subsect depth4" id="s2.3.5.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Problematic declared lifting</span><a class="img" href="s2.html#s2.3.5.a"
title="PermaLink to (a)&nbsp;Problematic declared lifting"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>A method with declared lifting (<a href="#s2.3.2" title="&sect;2.3.2&nbsp;Declared lifting" class="sect">&sect;2.3.2</a>) may have to declare <code>org.objectteams.LiftingFailedException</code>.
</p>
</div>
<div class="subsect depth4" id="s2.3.5.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Problematic callout binding</span><a class="img" href="s2.html#s2.3.5.b"
title="PermaLink to (b)&nbsp;Problematic callout binding"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>The role method of a callout binding with result lifting (<a href="s3.html#s3.3.c" title="&sect;3.3.(c)&nbsp;Result translation"
class="sect">&sect;3.3.(c)</a>) may have to declare <code>org.objectteams.LiftingFailedException</code>.
</p>
</div>
<div class="subsect depth4" id="s2.3.5.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Problematic callin binding</span><a class="img" href="s2.html#s2.3.5.c"
title="PermaLink to (c)&nbsp;Problematic callin binding"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>A callin binding (<a href="s4.html" title="&sect;4&nbsp;Callin Binding" class="sect">&sect;4</a>) may silently fail due to a <code>org.objectteams.LiftingFailedException</code>.
This exception will actually remain hidden because the callin binding is not explicitly invoked from any source code
but implicitly
by the runtime dispatch mechanism. To signal this situation the compiler raises an error against such callin binding.
</p>
<p>However, the compiler should allow to configure this error and understand the warning token <code>"hidden-lifting-problem"</code>
for suppressing this problem (<a href="s4.html#s4.1.b"
title="&sect;4.1.(b)&nbsp;Prerequisite: Class binding"
class="sect">&sect;4.1.(b)</a>).
If the problem is ignored/suppressed and if at runtime the lifting problem occurs,
triggering of the callin binding will silently fail, i.e., the program will continue in this situation as if the binding
hadn't existed in the first place.
</p>
</div>
<div class="subsect depth4" id="s2.3.5.d">
<h4 class="subsect">(d)&nbsp;<span class="title">Incompatible redefinition of a role hierarchy</span><a class="img" href="s2.html#s2.3.5.d"
title="PermaLink to (d)&nbsp;Incompatible redefinition of a role hierarchy"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Consider a team <code>T1</code> with a method <code>m</code> with declared lifting regarding role <code>R</code>,
where no lifting problems are detected.
Consider next a sub-team <code>T2</code> which modifies the hierarchy of role <code>R</code> such that lifting
to <code>T2.R</code> is problematic due to a binding ambiguity.
In this case clients invoking <code>T1.m()</code> could face the situation at runtime that an instance
of <code>T2</code> is used that <em>unexpectedly</em> fails to lift to its role <code>R</code>.
Here, the compiler signals a specific error against <code>T2</code> alerting of the incompatible change.
</p>
</div>
</div>
</div>
<div class="sect depth2" id="s2.4">
<h2 class="sect">&sect;2.4&nbsp;Explicit role creation<a class="img" href="s2.html#s2.4"
title="PermaLink to &sect;2.4&nbsp;Explicit 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</a></span></h2>
<p>Lifting is the normal technique by which role objects are created implicitly.
This section defines under which conditions a role can also be created explicitly.
</p>
<div class="sect depth3" id="s2.4.1">
<h3 class="sect">&sect;2.4.1&nbsp;Role creation via a lifting constructor<a class="img" href="s2.html#s2.4.1"
title="PermaLink to &sect;2.4.1&nbsp;Role creation via a lifting constructor"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#s2.4">&uarr;&nbsp;&sect;2.4</a></span></h3>
<p>Lifting uses the default constructor for roles (see <a href="#s2.3.1" title="&sect;2.3.1&nbsp;Implicit role creation" class="sect">&sect;2.3.1</a>).
This constructor can be invoked from client code, if the following rules are respected.
</p>
<div class="subsect depth4" id="s2.4.1.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Team context</span><a class="img" href="s2.html#s2.4.1.a"
title="PermaLink to (a)&nbsp;Team context"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>The lifting constructor can be used only within the enclosing team of
the role to be instantiated. Thus, qualified allocation expressions
(<code>someTeam.new SomeRole(..)</code>) may never use the lifting constructor.
</p>
</div>
<div class="subsect depth4" id="s2.4.1.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Fresh base object</span><a class="img" href="s2.html#s2.4.1.b"
title="PermaLink to (b)&nbsp;Fresh base object"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>If the argument to a lifting constructor invocation is a <code>new</code>
expression, creating a fresh base object, the use of the lifting constructor
is safe. Otherwise the rules of (c) below apply.
</p>
</div>
<div class="subsect depth4" id="s2.4.1.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Duplicate role runtime check</span><a class="img" href="s2.html#s2.4.1.c"
title="PermaLink to (c)&nbsp;Duplicate role runtime check"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>If it cannot be syntactically derived, that the argument to a lifting
constructor is a freshly created base object (b), a compile time warning will
signal that an additional runtime check is needed: It must be prevented that
a new role is created for a base object, which already has a role of the
required type in the given team. It is not possible to replace an existing
role by use of the lifting constructor. At runtime, any attempt to do so
will cause a <code>org.objectteams.DuplicateRoleException</code> to be thrown.
This exception can only occur in situations where the mentioned compile
time warning had been issued.
<br /><a href="s6.html#s6.1" title="&sect;6.1&nbsp;Reflection" class="sect">&sect;6.1</a> will introduce reflective functions
which can be used to manually prevent errors like a duplicate role.
</p>
</div>
</div>
<div class="sect depth3" id="s2.4.2">
<h3 class="sect">&sect;2.4.2&nbsp;Role creation via a regular constructor<a class="img" href="s2.html#s2.4.2"
title="PermaLink to &sect;2.4.2&nbsp;Role creation via a regular constructor"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#s2.4">&uarr;&nbsp;&sect;2.4</a></span></h3>
<p>Roles may also be created explicitly using a custom constructor with arbitrary signature
other than the signature of the lifting constructor.<br />
Within role constructors, four kinds of self-calls are possible:
</p>
<dl>
<dt><code>base(..)</code></dt>
<dd>A constructor of the corresponding base class (<a href="sA.html#sA.5.3" title="&sect;A.5.3&nbsp;BaseCall" class="sect">&sect;A.5.3</a>(c)),
<span class="underline">unless</span> the role is involved in base class circularity (<a href="#s2.1.2.b" title="&sect;2.1.2.(b)&nbsp;Cycles" class="sect">&sect;2.1.2.(b)</a>),
in which case a base constructor call is illegal.
</dd>
<dt><code>this(..)</code></dt>
<dd>Another constructor of the same class.</dd>
<dt><code>super(..)</code></dt>
<dd>A constructor of the super-class (normal <code>extends</code>), <span class="underline">unless</span> the super-class is bound to a different base class, in which case calling <code>super(..)</code> is not legal.
</dd>
<dt><code>tsuper(..)</code></dt>
<dd>A constructor of the corresponding role of the super-team (<a href="sA.html#sA.5.4" title="&sect;A.5.4&nbsp;TSuperCall" class="sect">&sect;A.5.4</a>(e)). Also see the constraint in <a href="s1.html#s1.3.2.c"
title="&sect;1.3.2.(c)&nbsp;Constructors and overridden 'extends' "
class="sect">&sect;1.3.2.(c)</a>.
</dd>
</dl>
<div class="subsect depth4" id="s2.4.2.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Unbound roles</span><a class="img" href="s2.html#s2.4.2.a"
title="PermaLink to (a)&nbsp;Unbound roles"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Each constructor of a role that is <strong>not bound</strong> to a base class must use
one of <code>this(..)</code>, <code>super(..)</code> or <code>tsuper(..)</code>.
</p>
</div>
<div class="subsect depth4" id="s2.4.2.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Bound roles</span><a class="img" href="s2.html#s2.4.2.b" title="PermaLink to (b)&nbsp;Bound roles"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Each constructor of a <strong>bound role</strong> must directly or indirectly invoke either
a <code>base(..)</code> constructor or a lifting constructor (see <a href="#s2.3.1" title="&sect;2.3.1&nbsp;Implicit role creation" class="sect">&sect;2.3.1</a>).
Indirect calls to the base constructor or lifting constructor may use any of <code>this(..)</code>, <code>super(..)</code>
or <code>tsuper(..)</code>, which simply delegates the obligation to the called constructor.
<br />
If a constructor referenced by <code>base(..)</code> is not visible according to the
regular rules of Java, it may still be called using <b>decapsulation</b> (see
also <a href="s3.html#s3.4" title="&sect;3.4&nbsp;Overriding access restrictions"
class="sect">&sect;3.4</a>, <a href="#s2.1.2.c" title="&sect;2.1.2.(c)&nbsp;Base class decapsulation"
class="sect">&sect;2.1.2.(c)</a>).
<br />
Note, that if the super or tsuper role is not bound, delegating the obligation to that unbound role will not work.
</p>
</div>
<div class="subsect depth4" id="s2.4.2.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Super-call for bound roles</span><a class="img" href="s2.html#s2.4.2.c"
title="PermaLink to (c)&nbsp;Super-call for bound roles"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Instead of or prior to calling <code>base(..)</code> a constructor of a bound role explicitly or implicitly calls a super constructor.
Which constructor is applicable depends on the super role and its <code>playedBy</code> clause.
</p>
<ul>
<li>If the super role is bound to the same base class as the current role is,
<ul>
<li>not writing a super-call causes the lifting constructor of the super role to be invoked.</li>
<li>explicitly calling a super constructor requires the super constructor to <i>either</i><ol>
<li>create a role instance using a base constructor call (directly or indirectly), <i>or</i></li>
<li>be a lifting constructor receiving a base instance, which the current role must provide as the argument.</li>
</ol>
</li>
</ul>
</li>
<li>If the super role is bound but the current role refines the <code>playedBy</code>
relationship (cf. <a href="#s2.1.c" title="&sect;2.1.(c)&nbsp;Covariant refinement" class="sect">&sect;2.1.(c)</a>),
<ul>
<li>a lifting constructor must be called explicitly passing a base object as the argument.</li>
</ul>
</li>
<li>If the role has an explicit or implicit super role which is unbound the constructor may optionally
call a super constructor (using <code>super(..)</code> or <code>tsuper(..)</code>) prior to calling
<code>base(..)</code>. Otherwise the default constructor is implicitly invoked.
</li>
</ul>
<p>When invoking a lifting constructor of a super role the base object can optionally be obtained by using a base constructor
call as an expression:
</p>
<div class="listing plain"><pre>super(base(<i>&lt;args&gt;</i>));</pre></div>
</div>
<p>The language system evaluates the base constructor by creating an
instance of the appropriate base class using a constructor with matching
signature. Also the internal links are setup that are needed for accessing the
base object from the role and for lifting the base object to the new role
in the future.
</p>
<p>The syntax for base constructors follows the rule that role implementations
never directly refer to any names of base classes or their features.
</p>
</div>
<div class="sect depth3" id="s2.4.3">
<h3 class="sect">&sect;2.4.3&nbsp;Role creation in the presence of smart lifting<a class="img" href="s2.html#s2.4.3"
title="PermaLink to &sect;2.4.3&nbsp;Role creation in the presence of smart lifting"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#s2.4">&uarr;&nbsp;&sect;2.4</a></span></h3>
<p>Explicitly instantiating a role <code>R1</code> bound to a base <code>B</code> where smart lifting of <code>B</code> to <code>R1</code> would actually
provide a subrole <code>R2</code> is dangerous: Instantiation enters the <code>R1</code> into the team's internal cache. If at any time later lifting
this <code>B</code> to <code>R2</code> is requested, which is a legal request, the runtime system will answer by throwing a <code>org.objectteams.WrongRoleException</code>
because it finds the <code>R1</code> instead of the required <code>R2</code>.
For this reason, in this specific situation the explicit instantiation <code>new R1(..)</code> will be flagged by a warning.
The problem can be avoided by using <code>R2</code> in the instantiation expression.
</p>
<h5 class="listing">Example code (WrongRoleException):</h5>
<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> B { <b>void</b> bm() {} }</pre></td>
</tr>
<tr class="line even">
<td class="ln">2</td>
<td><pre><b>public</b> <b>team</b> <b>class</b> T {</pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre> <b>protected</b> <b>class</b> R1 <b>playedBy</b> B {...}</pre></td>
</tr>
<tr class="line even">
<td class="ln">4</td>
<td><pre> <b>protected</b> <b>class</b> R2 <b>extends</b> R1 { <span class="comment">// inherits the binding to B</span></pre></td>
</tr>
<tr class="line odd">
<td class="ln">5</td>
<td><pre> <b>void</b> rm() { <span class="comment">/* body omitted */</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> <b>public</b> B getDecoratedB() {</pre></td>
</tr>
<tr class="line even">
<td class="ln">8</td>
<td><pre> <b>return</b> <em><b>new</b> R1</em>(<b>new</b> B()); <span class="comment">// <span class="error">compile-time warning!</span></span></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> <b>public</b> <b>void</b> requestLifting(B <b>as</b> R2 r) {}</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><span class="comment">// plus these calls:</span></pre></td>
</tr>
<tr class="line odd">
<td class="ln">13</td>
<td><pre>T t = <b>new</b> T();</pre></td>
</tr>
<tr class="line even">
<td class="ln">14</td>
<td><pre>B b = t.getDecoratedB(); <span class="comment">// creates an R1 for b</span></pre></td>
</tr>
<tr class="line odd">
<td class="ln">15</td>
<td><pre>t.requestLifting(b); <span class="comment">// =&gt; <span class="error"><code>org.objectteams.WrongRoleException!</code></span></span></pre></td>
</tr>
</table>
</div>
<div class="codecomment">
<ul>
<li>A note on line 8: this line passes a fresh instance of <code>B</code> to the lifting constructor of <code>R1</code>
(see <a href="#s2.4.1.b" title="&sect;2.4.1.(b)&nbsp;Fresh base object"
class="sect">&sect;2.4.1.(b)</a>). In order to return this <code>B</code> instance lowering is implicitly used for the return statement.
</li>
<li>When line 15 is executed, a lifting of <code>b</code> to <code>R2</code> is requested but due to line 8 an <code>R1</code> is found in the internal cache.
</li>
</ul>
</div>
</div>
</div>
<div class="sect depth2" id="s2.5">
<h2 class="sect">&sect;2.5&nbsp;Abstract Roles<a class="img" href="s2.html#s2.5"
title="PermaLink to &sect;2.5&nbsp;Abstract Roles"><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</a></span></h2>
<p>Overriding of role classes and dynamic binding of role types (<a href="s1.html#s1.3.1.e"
title="&sect;1.3.1.(e)&nbsp;Dynamic binding of types"
class="sect">&sect;1.3.1.(e)</a>)
adds new cases to <strong>creation</strong> with respect to abstract classes.
</p>
<div class="subsect depth3" id="s2.5.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Using abstract classes for creation</span><a class="img" href="s2.html#s2.5.a"
title="PermaLink to (a)&nbsp;Using abstract classes for creation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Abstract role classes can indeed be used for object creation.
The effect of such a statement is that the team must be
marked <code>abstract</code>. Only those sub-teams are concrete
that provide concrete versions for all role classes used in
creation expressions.<br />
This includes the case, where a
super-team has a concrete role class and creates
instances of this role class and only the sub-team changes
the status of this role class to abstract. Also here
the sub-team must be marked abstract, because it contains
an abstract role class that is used in creation expressions.
</p>
<div class="note">
<h5>Interpretation:</h5>
Since the type in a role creation expression is late-bound relative to the enclosing team instance, abstract role classes
can be seen
as the hook in a <strong>template&amp;hook pattern</strong> that is raised from the method level to the class level:
A super-team may already refer to the constructor of an abstract role class,
only the sub-team will provide the concrete role class to fill the hook with the necessary implementation.
</div>
</div>
<div class="subsect depth3" id="s2.5.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Relevant roles</span><a class="img" href="s2.html#s2.5.b"
title="PermaLink to (b)&nbsp;Relevant roles"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>A team must be marked <code>abstract</code> if one of its <strong>relevant roles</strong> is abstract.
<br />
A role is relevant in this sense if
</p>
<ul>
<li>the role class is public <em>or if</em></li>
<li>an explicit <code>new</code> expression
would require to create instances of the role class, <em>or if</em></li>
<li>any of the lifting methods of the enclosing team
would require to create instances of the role class.<br />
A role is irrelevant with respect to lifting
if either of the following holds:
<ul>
<li>It is not bound to a base class, neither directly nor
by an inherited <code>playedBy</code> clause.
</li>
<li>It has a sub-role without a <code>playedBy</code> clause.
</li>
<li>It is bound to an abstract base class, and for all concrete
sub-classes of the base class, a binding to a more specific role class exists.
</li>
</ul>
</li>
</ul>
<p>If neither property, relevance nor irrelevance, can be shown for an abstract role,
a warning is given in case the enclosing team is not abstract.
</p>
</div>
</div>
<div class="sect depth2" id="s2.6">
<h2 class="sect">&sect;2.6&nbsp;Explicit base references<a class="img" href="s2.html#s2.6"
title="PermaLink to &sect;2.6&nbsp;Explicit base references"><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</a></span></h2>
<p>The role-base link is not meant to be accessed explicitly from programs,
but it is fully under the control of compiler and runtime environment.
Accessing features of a role's base object is done by
<a href="s3.html" title="&sect;3&nbsp;Callout Binding" class="sect">callout bindings (&sect;3)</a>.
Yet, a keyword <code>base</code> exists, which can be used in the following
contexts:
</p>
<div class="subsect depth3" id="s2.6.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Externalized roles of a base team</span><a class="img" href="s2.html#s2.6.a"
title="PermaLink to (a)&nbsp;Externalized roles of a base team"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>If the base class of a role <code>T1.R1</code> is again a team
<code>T2</code>, roles of that team <code>T2</code> can be
externalized (see <a href="s1.html#s1.2.2" title="&sect;1.2.2&nbsp;Externalized roles"
class="sect">&sect;1.2.2</a>)
using <code>base</code> as their type anchor. Given that
<code>R2</code> is a role of <code>T2</code>, one could write:
</p>
<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> T1 {</pre></td>
</tr>
<tr class="line even">
<td class="ln">2</td>
<td><pre> <b>protected</b> <b>class</b> R1 <em><b>playedBy</b> T2</em> {</pre></td>
</tr>
<tr class="line odd">
<td class="ln">3</td>
<td><pre> <b>protected</b> <em>R2&lt;@base&gt;</em> aRoleOfMyBase;</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>}</pre></td>
</tr>
</table>
</div>
<p>This syntax is only legal within the body of the role <code>T1.R1</code> which is bound
to the team <code>T2</code> containing role <code>R2</code>.
A static type prefix can be used to disambiguate a base anchor, so the explicit variant
of the above type would be <code>R2&lt;@<strong>R1</strong>.base&gt;</code>.
<br />
It is not legal to use a type anchor containing <code>base</code> as an element in a path
of references like <code>&lt;@base.<span class="error">field</span>&gt;</code>
or <code>&lt;@<span class="error">field</span>.base&gt;</code>.
</p>
</div>
<div class="subsect depth3" id="s2.6.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Explicit base object creation</span><a class="img" href="s2.html#s2.6.b"
title="PermaLink to (b)&nbsp;Explicit base object creation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Within a role constructor (which is not the lifting constructor)
the syntax <code>base(<em>arguments</em>)</code> causes an instance
of the bound base class to be created and linked (see <a href="#s2.4.2"
title="&sect;2.4.2&nbsp;Role creation via a regular constructor"
class="sect">&sect;2.4.2</a>).
</p>
</div>
<div class="subsect depth3" id="s2.6.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Base call in callin method</span><a class="img" href="s2.html#s2.6.c"
title="PermaLink to (c)&nbsp;Base call in callin method"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Within a <a href="s4.html#s4.2.d" title="&sect;4.2.(d)&nbsp;Callin methods"
class="sect">callin method (&sect;4.2.(d))</a>
an expression <code>base.m(<em>args</em>)</code> is used to invoke the
originally called method (see <a href="s4.html#s4.3" title="&sect;4.3&nbsp;Base calls" class="sect">&sect;4.3</a>).
</p>
</div>
<div class="subsect depth3" id="s2.6.d">
<h4 class="subsect">(d)&nbsp;<span class="title">Base guard predicates</span><a class="img" href="s2.html#s2.6.d"
title="PermaLink to (d)&nbsp;Base guard predicates"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p><a href="s5.html#s5.4" title="&sect;5.4&nbsp;Guard predicates" class="sect">Guard predicates (&sect;5.4)</a> can
be specified to act on the base side using the <code><strong>base when</strong></code> keywords.
Within such a base guard predicate <code>base</code> is interpreted as a special identifier
holding a reference to the base object that is about to be lifted
for the sake of a callin method interception (see <a href="s5.html#s5.4.2.a" title="&sect;5.4.2.(a)&nbsp;Base object reference"
class="sect">&sect;5.4.2.(a)</a>).
</p>
</div>
<div class="subsect depth3" id="s2.6.e">
<h4 class="subsect">(e)&nbsp;<span class="title">Parameter mappings</span><a class="img" href="s2.html#s2.6.e"
title="PermaLink to (e)&nbsp;Parameter mappings"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>An expression at the right-hand side of a parameter mapping
(parameter in a callin binding (<a href="s4.html#s4.4" title="&sect;4.4&nbsp;Callin parameter mapping"
class="sect">&sect;4.4</a>) or
result in a callout binding (<a href="s3.html#s3.2.c" title="&sect;3.2.(c)&nbsp;Result mapping"
class="sect">&sect;3.2.(c)</a>) ) may use the keyword <code>base</code>
to refer to the bound base instance. Such usage requires the role method bound in this method binding to be non-static.
</p>
</div>
<div class="subsect depth3" id="s2.6.f">
<h4 class="subsect">(f)&nbsp;<span class="title">Inhibition of modification</span><a class="img" href="s2.html#s2.6.f"
title="PermaLink to (f)&nbsp;Inhibition of modification"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>In all cases, the <code>base</code> reference is immutable,
i.e., <code>base</code> can never appear as the left-hand-side of an assignment.
</p>
</div>
<div class="subsect depth3" id="s2.6.g">
<h4 class="subsect">(g)&nbsp;<span class="title">Decapsulation via base reference</span><a class="img" href="s2.html#s2.6.g"
title="PermaLink to (g)&nbsp;Decapsulation via base reference"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>In cases <a href="#s2.6.d" title="&sect;2.6.(d)&nbsp;Base guard predicates"
class="sect">&sect;2.6.(d)</a> and <a href="#s2.6.e" title="&sect;2.6.(e)&nbsp;Parameter mappings" class="sect">&sect;2.6.(e)</a> above, members of the base
object may be accessed that would not be visible under Java's visibility rules.
Such references are treated as decapsulation in accordance with <a href="s3.html#s3.4.a"
title="&sect;3.4.(a)&nbsp;Callout to inaccessible base method"
class="sect">&sect;3.4.(a)</a> and <a href="s3.html#s3.5.e" title="&sect;3.5.(e)&nbsp;Access control"
class="sect">&sect;3.5.(e)</a>.<br />
Note that accessing a base field via <code>base</code> only gives reading access to this field.
</p>
</div>
<div class="newpage"></div>
</div>
<div class="sect depth2" id="s2.7">
<h2 class="sect">&sect;2.7&nbsp;Advanced structures<a class="img" href="s2.html#s2.7"
title="PermaLink to &sect;2.7&nbsp;Advanced structures"><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</a></span></h2>
<p>This section discusses how role containment and the playedBy relationship can be combined.
It does not define new rules, but illustrates rules defined above. The central idea is that any class
can have more than one of the three flavors <em>team, role, </em>and<em> base</em>.
</p>
<div class="subsect depth3" id="s2.7.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Nesting</span><a class="img" href="s2.html#s2.7.a" title="PermaLink to (a)&nbsp;Nesting"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>If a role (contained in a team) is also a team (marked with the <code>team</code> modifier)
it is a <strong>nested team</strong>. The depth of nesting is not restricted.
</p>
</div>
<div class="subsect depth3" id="s2.7.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Stacking</span><a class="img" href="s2.html#s2.7.b" title="PermaLink to (b)&nbsp;Stacking"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>If the base class to which a role is bound using <code>playedBy</code> is a team,
the role is said to be <strong>stacked</strong> on the base team.
</p>
</div>
<div class="subsect depth3" id="s2.7.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Layering</span><a class="img" href="s2.html#s2.7.c" title="PermaLink to (c)&nbsp;Layering"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>If roles of a team <code>Secondary</code> are played by roles of another team <code>Primary</code>
(i.e., base classes are roles), the team <code>Secondary</code> defines a <strong>layer</strong> over the team <code>Primary</code>.
Such layering requires a final reference <code>anchor</code> from <code>Secondary</code> to an instance of <code>Primary</code>.
All playedBy declarations within <code>Secondary</code> specify their base classes anchored to that final link <code>anchor</code>.
</p><img src="../images/Layering.png" alt="Team layering example" /><p>Due to the anchored base types, layered teams implicitly support the following guarantee:
all base objects of roles of <code>Secondary</code> are contained within the team instance specified by the link <code>anchor</code>.
If roles of <code>Secondary</code> contain any callin bindings to non-static base methods, these will be triggered only
when a base method is invoked on a base instance contained in the team specified by <code>anchor</code>.
<br />
In accordance with <a href="#s2.6.a" title="&sect;2.6.(a)&nbsp;Externalized roles of a base team"
class="sect">&sect;2.6.(a)</a> the anchor in such anchored playedBy declarations
could also be the pseudo identifier <code>base</code>, provided that <code>Secondary</code> is a nested team,
which has a playedBy binding to <code>Primary</code> as its base class.
This situation is part of the second example <a href="#s2.7.d" title="&sect;2.7.(d)&nbsp;Implicit playedBy specialization"
class="sect">below (&sect;2.7.(d))</a> (see <code>T1 playedBy TB1</code>).
</p>
</div>
<div class="newpage"></div>
<div class="subsect depth3" id="s2.7.d">
<h4 class="subsect">(d)&nbsp;<span class="title">Implicit playedBy specialization</span><a class="img" href="s2.html#s2.7.d"
title="PermaLink to (d)&nbsp;Implicit playedBy specialization"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>According to <a href="#s2.1.d" title="&sect;2.1.(d)&nbsp;No-variance" class="sect">&sect;2.1.(d)</a> an implicit sub-role may <em>implicitly</em> specialize an existing <code>playedBy</code> relation.
This requires the base class to be specified relative to some implicit (<code>OuterTeam.this</code>) or explicit (<code>OuterTeam.base</code>) team anchor.
Specializing that team anchor automatically specializes the playedBy declaration, too.
This rule never requires any action from a programmer but only explains the interpretation of a playedBy declaration in
complex situations.
</p>
<h5>Two advanced examples demonstrating the above are:</h5>
<table border="0">
<colgroup span="1">
<col align="left" span="1" />
<col align="left" span="1" />
</colgroup>
<tr>
<td rowspan="1" colspan="1">
<ul>
<li>If a role <code>TOuter1.T.R</code> of a <strong>nested team </strong><code>TOuter1.T</code> is played by
another role of the outer enclosing team <code>TOuter1.B</code>, subclassing the outer team <code>TOuter1</code> to <code>TOuter2</code>
will produce a new role <code>TOuter2.T.R</code> which is automatically played by <code>TOuter2.B</code>,
an implicit sub class of the original base class <code>TOuter1.B</code>.
</li>
</ul>
</td>
<td rowspan="1" colspan="1"><img src="../images/implicitly_overriding_playedby.png"
alt="Implicitly overriding playedBy" /></td>
</tr>
<tr>
<td rowspan="1" colspan="1">
<ul>
<li>Consider the case where a <strong>nested </strong><code>T1</code> as a role of <code>TOuter</code> is <strong>stacked</strong>
on a base team <code>TB1</code>. Also, <code>T1</code> is a <strong>layered team</strong> over <code>TB1</code>
because its role <code>R</code> adapts role <code>TB1.B</code>.
<br />
In this situation the playedBy relation of role <code>TOuter.T1.R</code> is given by a base-anchored type <code>B&lt;@T1.base&gt;</code>.
If furthermore <code>TOuter.T1</code> is subclassed to <code>TOuter.T2</code> which covariantly refines the inherited
playedBy declaration to <code>TB2</code>, then <code>TOuter.T2.R</code> will automatically refine the inherited playedBy relation
to <code>TB2.B</code> to follow the new interpretation of the <code>base</code> anchor.
</li>
</ul>
</td>
<td rowspan="1" colspan="1"><img src="../images/implicitly_overriding_playedby_base.png"
alt="Implicitly overriding playedBy base" /></td>
</tr>
</table>
</div>
</div>
</div>
<table class="nav">
<tr>
<td class="back"><a href="s1.html" rel="prev">&lt;&lt;&nbsp;&sect;1&nbsp;Teams and Roles</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.html" rel="next">&sect;3&nbsp;Callout 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: 2015-06-09
</div>
</body>
</html>