blob: 36756fe59e52ec037a58b97d361a1cb2967a9c6d [file] [log] [blame]
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "../xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<link rel="stylesheet" type="text/css" href="../css/ot.css" />
<link rel="stylesheet" type="text/css" href="../css/otjld.css" />
<title>OT/J Language Definition v1.3</title>
</head>
<body class="otdt">
<div id="content">
<table class="nav">
<tr>
<td class="back"><a id="top"></a></td>
<td class="top"><a href="index.html" rel="contents">&uarr;&nbsp;Table of Contents&nbsp;&uarr;</a></td>
<td class="next"><a href="s2.2.html" rel="next">&sect;2.2&nbsp;Lowering&nbsp;&gt;&gt;</a></td>
</tr>
</table>
<div class="breadcrumb"><a class="nav" href="s2.html" rel="section">&sect;2&nbsp;Role Binding</a></div>
<div class="sect depth2" id="s2.1">
<h2 class="sect">&sect;2.1&nbsp;playedBy relation<a class="img" href="s2.1.html"
title="PermaLink to &sect;2.1&nbsp;playedBy relation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></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.1.a.html"
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.1.b.html" 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.3.1.c.html"
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.1.c.html"
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.html" 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.1.d.html" 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.3.1.c.html"
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.html"
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.1.e.html"
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.html" title="&sect;2.2&nbsp;Lowering" class="sect">&sect;2.2</a> and lifting: <a href="s2.3.html" 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.1.f.html"
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.1.a.html"
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.1.1.html"
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="#top">&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.1.2.html"
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="#top">&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.2.5.b.html" 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.1.2.a.html"
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.1.2.b.html" 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.1.a.html" 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.html"
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.4.html" 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.1.2.c.html"
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.4.html" 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.2.html" 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.html"
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.html" 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.1.2.d.html" 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 an 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>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.4.html" 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.1.2.e.html"
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.html" 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>
<table class="nav">
<tr>
<td class="back"></td>
<td class="top"><a href="index.html" rel="contents">&uarr;&nbsp;Table of Contents&nbsp;&uarr;</a></td>
<td class="next"><a href="s2.2.html" rel="next">&sect;2.2&nbsp;Lowering&nbsp;&gt;&gt;</a></td>
</tr>
</table>
<div class="breadcrumb"><a class="nav" href="s2.html" rel="section">&sect;2&nbsp;Role Binding</a></div>
</div>
<div id="footer">
<hr /><a class="w3c img" href="http://jigsaw.w3.org/css-validator/check/referer"
shape="rect"><img src="../images/valid-css2-blue.png" alt="Valid CSS!" height="31" width="88" /></a><a class="w3c img" href="http://validator.w3.org/check?uri=referer" shape="rect"><img src="../images/valid-xhtml10-blue.png" alt="Valid XHTML 1.0 Strict" height="31"
width="88" /></a><address>&copy; Stephan Herrmann, Christine Hundt, Marco Mosconi</address>
OT/J version 1.3 &mdash; last modified: 2011-05-15
</div>
</body>
</html>