blob: 401e35478826795adfc2f89cd7839d636fce71ea [file] [log] [blame]
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "../xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<link rel="stylesheet" type="text/css" href="../css/ot.css" />
<link rel="stylesheet" type="text/css" href="../css/otjld.css" />
<title>OT/J Language Definition v1.3</title>
</head>
<body class="otdt">
<div id="content">
<table class="nav">
<tr>
<td class="back"><a id="top"></a><a href="s2.1.1.html" rel="prev">&lt;&lt;&nbsp;&sect;2.1.1&nbsp;Binding interfaces</a></td>
<td class="top"><a href="index.html" rel="contents">&uarr;&nbsp;Table of Contents&nbsp;&uarr;</a></td>
<td class="next"></td>
</tr>
</table>
<div class="breadcrumb"><a class="nav" href="s2.html" rel="section">&sect;2&nbsp;Role Binding</a>&nbsp;&gt;&nbsp;<a class="nav" href="s2.1.html" rel="section">&sect;2.1&nbsp;playedBy relation</a></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></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">No cycles</span><a class="img" href="s2.1.2.b.html" title="PermaLink to (b)&nbsp;No 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> may not be
an enclosing type (at any depth) of the role class being defined.
<br />
This rule prohibits 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 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> is forbidden.
<br />
Conversely, it is also 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) throws 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>
<table class="nav">
<tr>
<td class="back"><a href="s2.1.1.html" rel="prev">&lt;&lt;&nbsp;&sect;2.1.1&nbsp;Binding interfaces</a></td>
<td class="top"><a href="index.html" rel="contents">&uarr;&nbsp;Table of Contents&nbsp;&uarr;</a></td>
<td class="next"></td>
</tr>
</table>
<div class="breadcrumb"><a class="nav" href="s2.html" rel="section">&sect;2&nbsp;Role Binding</a>&nbsp;&gt;&nbsp;<a class="nav" href="s2.1.html" rel="section">&sect;2.1&nbsp;playedBy relation</a></div>
</div>
<div id="footer">
<hr /><a class="w3c img" href="http://jigsaw.w3.org/css-validator/check/referer"
shape="rect"><img src="../images/valid-css2-blue.png" alt="Valid CSS!" height="31" width="88" /></a><a class="w3c img" href="http://validator.w3.org/check?uri=referer" shape="rect"><img src="../images/valid-xhtml10-blue.png" alt="Valid XHTML 1.0 Strict" height="31"
width="88" /></a><address>&copy; Stephan Herrmann, Christine Hundt, Marco Mosconi</address>
OT/J version 1.3 &mdash; last modified: 2010-06-08
</div>
</body>
</html>