| <!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"><< §1 Teams and Roles</a></td> |
| <td class="top"><a href="index.html" rel="contents">↑ Table of Contents ↑</a></td> |
| <td class="next"><a href="s3.html" rel="next">§3 Callout Binding >></a></td> |
| </tr> |
| </table> |
| <div class="chapter" id="s2"> |
| <div class="headl"> |
| <div class="headr"> |
| <h1>§2 Role Binding</h1> |
| </div> |
| </div> |
| <div id="toc-box"> |
| <ul class="toc-box"> |
| <li><a href="s2.html">§2 Role Binding</a></li> |
| <li><a href="#s2.1">§2.1 playedBy relation</a></li> |
| <li><a href="#s2.2">§2.2 Lowering</a></li> |
| <li><a href="#s2.3">§2.3 Lifting</a></li> |
| <li><a href="#s2.4">§2.4 Explicit role creation</a></li> |
| <li><a href="#s2.5">§2.5 Abstract Roles</a></li> |
| <li><a href="#s2.6">§2.6 Explicit base references</a></li> |
| <li><a href="#s2.7">§2.7 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="§3 Callout Binding" class="sect">§3</a>) |
| and <strong>callin</strong> (<a href="s4.html" title="§4 Callin Binding" class="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="§2.3 Lifting" class="sect">§2.3</a>) |
| and <strong>lowering</strong> (role to base) (<a href="#s2.2" title="§2.2 Lowering" class="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">§2.1 playedBy relation<a class="img" href="s2.html#s2.1" |
| title="PermaLink to §2.1 playedBy relation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#top">↑ §2</a></span></h2> |
| <div class="syntaxlink"><a href="sA.html#sA.1.1" title="§A.1.1 ClassDeclaration" |
| class="syntax">→ Syntax §A.1.1</a></div> |
| <div class="subsect depth3" id="s2.1.a"> |
| <h4 class="subsect">(a) <span class="title">Role-base binding</span><a class="img" href="s2.html#s2.1.a" |
| title="PermaLink to (a) 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) <span class="title">Inheritance</span><a class="img" href="s2.html#s2.1.b" title="PermaLink to (b) 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="§1.3.1.(c) Overriding and implicit inheritance" |
| class="sect">§1.3.1.(c)</a>) |
| role inheritance. |
| |
| </p> |
| </div> |
| <div class="subsect depth3" id="s2.1.c"> |
| <h4 class="subsect">(c) <span class="title">Covariant refinement</span><a class="img" href="s2.html#s2.1.c" |
| title="PermaLink to (c) 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="§2.3.3 Smart lifting" class="sect">smart lifting (§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) <span class="title">No-variance</span><a class="img" href="s2.html#s2.1.d" title="PermaLink to (d) 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="§1.3.1.(c) Overriding and implicit inheritance" |
| class="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="§2.7.(d) Implicit playedBy specialization" |
| class="sect">§2.7.(d)</a>). |
| |
| </p> |
| </div> |
| <div class="subsect depth3" id="s2.1.e"> |
| <h4 class="subsect">(e) <span class="title">Use of playedBy bindings</span><a class="img" href="s2.html#s2.1.e" |
| title="PermaLink to (e) 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="§2.2 Lowering" class="sect">§2.2</a> and lifting: <a href="#s2.3" title="§2.3 Lifting" class="sect">§2.3</a>) |
| and for method bindings (callout: <a href="s3.html" title="§3 Callout Binding" class="sect">§3</a> and callin: <a href="s4.html" title="§4 Callin Binding" class="sect">§4</a>). |
| |
| </p> |
| </div> |
| <div class="subsect depth3" id="s2.1.f"> |
| <h4 class="subsect">(f) <span class="title">Effect on garbage collection</span><a class="img" href="s2.html#s2.1.f" |
| title="PermaLink to (f) 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="§6.1.(a) Interface to the role registry" |
| class="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">§2.1.1 Binding interfaces<a class="img" href="s2.html#s2.1.1" |
| title="PermaLink to §2.1.1 Binding interfaces"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#s2.1">↑ §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="§4 Callin Binding" class="sect">§4</a>). |
| |
| </div> |
| </div> |
| <div class="sect depth3" id="s2.1.2"> |
| <h3 class="sect">§2.1.2 Legal base classes<a class="img" href="s2.html#s2.1.2" |
| title="PermaLink to §2.1.2 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">↑ §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="§2.1.2.(c) Base class decapsulation" |
| class="sect">below (§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="§1.2.5.(b) Role files" |
| class="sect">§1.2.5.(b)</a>) |
| also additional imports in the role file are considered. |
| <br /><a href="#s2.1.2.d" title="§2.1.2.(d) Base imports" class="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) <span class="title">No role of the same team</span><a class="img" href="s2.html#s2.1.2.a" |
| title="PermaLink to (a) 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="§2.1.2.(d) Base imports" class="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) <span class="title">Cycles</span><a class="img" href="s2.html#s2.1.2.b" title="PermaLink to (b) 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="§3.1.(a) Prerequisite: Class binding" |
| class="sect">§3.1.(a)</a>) and base constructor calls (<a href="#s2.4.2" |
| title="§2.4.2 Role creation via a regular constructor" |
| class="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="§5.4 Guard predicates" class="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) <span class="title">Base class decapsulation</span><a class="img" href="s2.html#s2.1.2.c" |
| title="PermaLink to (c) 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="§3.4 Overriding access restrictions" |
| class="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="§7.2 Confined roles" class="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="§3 Callout Binding" class="sect">callout (§3)</a> or <a href="s4.html" title="§4 Callin Binding" class="sect">callin (§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="§2.4.1 Role creation via a lifting constructor" |
| class="sect">lifting constructor (§2.4.1)</a>). |
| </li> |
| <li>the base side of an argument with declared lifting (see <a href="#s2.3.2" title="§2.3.2 Declared lifting" class="sect">declared lifting (§2.3.2)</a>). |
| </li> |
| </ul> |
| </div> |
| <div class="subsect depth4" id="s2.1.2.d"> |
| <h4 class="subsect">(d) <span class="title">Base imports</span><a class="img" href="s2.html#s2.1.2.d" |
| title="PermaLink to (d) 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="§2.1.2.(c) Base class decapsulation" |
| class="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="§1.4 Name clashes" class="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) <span class="title">No free type parameters</span><a class="img" href="s2.html#s2.1.2.e" |
| title="PermaLink to (e) 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><T></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><U></em> <b>playedBy</b> ValueTrafo<em><U></em> {</pre></td> |
| </tr> |
| <tr class="line even"> |
| <td class="ln">6</td> |
| <td><pre> <em>U</em> transform(<em>U</em> v) <b>-></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><V> V</em> perform(ValueTrafo<em><V></em> <b>as</b> SafeTrafo<em><V></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><String></em> trafo = <b>new</b> ValueTrafo<em><String></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="§3 Callout Binding" class="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="§2.3.2 Declared lifting" class="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">§2.2 Lowering<a class="img" href="s2.html#s2.2" |
| title="PermaLink to §2.2 Lowering"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#top">↑ §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) <span class="title">Definition of lowering</span><a class="img" href="s2.html#s2.2.a" |
| title="PermaLink to (a) 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) <span class="title">Places of lowering</span><a class="img" href="s2.html#s2.2.b" |
| title="PermaLink to (b) 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="§3.3.(d) Typing rules" class="sect">§3.3.(d)</a>) |
| </li> |
| <li>or the return value in a callin binding (<a href="s4.html#s4.5.d" title="§4.5.(d) Typing rules" class="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="§2.4.1 Role creation via a lifting constructor" |
| class="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="§3.3.(d) Typing rules" class="sect">§3.3.(d)</a>) |
| </li> |
| <li>parameters in callin bindings (<a href="s4.html#s4.5.d" title="§4.5.(d) Typing rules" class="sect">§4.5.(d)</a>) |
| </li> |
| </ul> |
| <p>For cases where lowering shall be <em>forced</em> see <a href="#s2.2.d" title="§2.2.(d) Explicit lowering" class="sect">§2.2.(d)</a> below. |
| |
| </p> |
| </div> |
| <div class="subsect depth3" id="s2.2.c"> |
| <h4 class="subsect">(c) <span class="title">Typing</span><a class="img" href="s2.html#s2.2.c" title="PermaLink to (c) 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) <span class="title">Explicit lowering</span><a class="img" href="s2.html#s2.2.d" |
| title="PermaLink to (d) 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) <span class="title">Lowering of arrays</span><a class="img" href="s2.html#s2.2.e" |
| title="PermaLink to (e) 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) <span class="title">Ambiguous lowering</span><a class="img" href="s2.html#s2.2.f" |
| title="PermaLink to (f) 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">§2.3 Lifting<a class="img" href="s2.html#s2.3" title="PermaLink to §2.3 Lifting"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#top">↑ §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) <span class="title">Definition of lifting</span><a class="img" href="s2.html#s2.3.a" |
| title="PermaLink to (a) 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="§2.3.4 Binding ambiguities" class="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) <span class="title">Places of lifting</span><a class="img" href="s2.html#s2.3.b" |
| title="PermaLink to (b) 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="§3.3.(c) Result translation" |
| class="sect">Callout bindings (§3.3.(c))</a> (result) |
| </li> |
| <li><a href="s4.html#s4.5.a" title="§4.5.(a) Call target translation" |
| class="sect">Callin bindings (§4.5.(a))</a> (call target and parameters) |
| </li> |
| <li><a href="#s2.3.2" title="§2.3.2 Declared lifting" class="sect">Declared lifting (§2.3.2)</a></li> |
| </ul> |
| </div> |
| <div class="subsect depth3" id="s2.3.c"> |
| <h4 class="subsect">(c) <span class="title">Typing</span><a class="img" href="s2.html#s2.3.c" title="PermaLink to (c) 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) <span class="title">Lifting of arrays</span><a class="img" href="s2.html#s2.3.d" |
| title="PermaLink to (d) 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">§2.3.1 Implicit role creation<a class="img" href="s2.html#s2.3.1" |
| title="PermaLink to §2.3.1 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">↑ §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) <span class="title">Reuse of existing role objects</span><a class="img" href="s2.html#s2.3.1.a" |
| title="PermaLink to (a) 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="§2.3.3 Smart lifting" class="sect">"smart lifting" (§2.3.3)</a>. |
| |
| </p> |
| </div> |
| <div class="subsect depth4" id="s2.3.1.b"> |
| <h4 class="subsect">(b) <span class="title">Default lifting constructor</span><a class="img" href="s2.html#s2.3.1.b" |
| title="PermaLink to (b) 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 §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) <span class="title">Custom lifting constructor</span><a class="img" href="s2.html#s2.3.1.c" |
| title="PermaLink to (c) 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) <span class="title">Fine-tuning role instantiation</span><a class="img" href="s2.html#s2.3.1.d" |
| title="PermaLink to (d) 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="§3 Callout Binding" class="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">§2.3.2 Declared lifting<a class="img" href="s2.html#s2.3.2" |
| title="PermaLink to §2.3.2 Declared lifting"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#s2.3">↑ §2.3</a></span></h3> |
| <div class="syntaxlink"><a href="sA.html#sA.6.2" title="§A.6.2 LiftingType" class="syntax">→ Syntax §A.6.2</a></div> |
| <div class="subsect depth4" id="s2.3.2.a"> |
| <h4 class="subsect">(a) <span class="title">Parameters with declared lifting</span><a class="img" href="s2.html#s2.3.2.a" |
| title="PermaLink to (a) 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="§2.3.3 Smart lifting" class="sect">§2.3.3</a> and <a href="#s2.3.4" title="§2.3.4 Binding ambiguities" class="sect">§2.3.4</a> for details). |
| |
| </p> |
| </div> |
| <div class="subsect depth4" id="s2.3.2.b"> |
| <h4 class="subsect">(b) <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) 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) <span class="title">Declared lifting of arrays</span><a class="img" href="s2.html#s2.3.2.c" |
| title="PermaLink to (c) 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) <span class="title">Declared lifting for catch blocks</span><a class="img" href="s2.html#s2.3.2.d" |
| title="PermaLink to (d) 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) <span class="title">Generic declared lifting</span><a class="img" href="s2.html#s2.3.2.e" |
| title="PermaLink to (e) 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><AnyBase <b>base</b> SuperRole> |
| <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">§2.3.3 Smart lifting<a class="img" href="s2.html#s2.3.3" |
| title="PermaLink to §2.3.3 Smart lifting"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#s2.3">↑ §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) <span class="title">Static adjustment</span><a class="img" href="s2.html#s2.3.3.a" |
| title="PermaLink to (a) 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> |
| — say <code>R2</code> — |
| 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="§4.5.(d) Typing rules" class="sect">§4.5.(d)</a>). |
| |
| </div> |
| </div> |
| <div class="subsect depth4" id="s2.3.3.b"> |
| <h4 class="subsect">(b) <span class="title">Dynamic selection of a role class</span><a class="img" href="s2.html#s2.3.3.b" |
| title="PermaLink to (b) 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–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) <span class="title">Team as closed world</span><a class="img" href="s2.html#s2.3.3.c" |
| title="PermaLink to (c) 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) <span class="title">Selection regardless of abstractness</span><a class="img" href="s2.html#s2.3.3.d" |
| title="PermaLink to (d) 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="§2.5 Abstract Roles" class="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"> </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"> </td> |
| </tr> |
| <tr> |
| <td rowspan="1" colspan="1"> </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–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–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 «playedBy» |
| 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 «playedBy» 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">§2.3.4 Binding ambiguities<a class="img" href="s2.html#s2.3.4" |
| title="PermaLink to §2.3.4 Binding ambiguities"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#s2.3">↑ §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) <span class="title">Potential ambiguity</span><a class="img" href="s2.html#s2.3.4.a" |
| title="PermaLink to (a) 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="§2.1.(c) Covariant refinement" class="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) <span class="title">Definite ambiguity</span><a class="img" href="s2.html#s2.3.4.b" |
| title="PermaLink to (b) 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="§2.3.2 Declared lifting" class="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="§2.3.2.(e) Generic declared lifting" |
| class="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="§2.3.5 Consequences of lifting problems" |
| class="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) <span class="title">Actual ambiguity</span><a class="img" href="s2.html#s2.3.4.c" |
| title="PermaLink to (c) 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) <span class="title">Mismatching role</span><a class="img" href="s2.html#s2.3.4.d" |
| title="PermaLink to (d) 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="§2.3.4.(a) Potential ambiguity" |
| class="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">§2.3.5 Consequences of lifting problems<a class="img" href="s2.html#s2.3.5" |
| title="PermaLink to §2.3.5 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">↑ §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="§2.3.4.(a) Potential ambiguity" |
| class="sect">§2.3.4.(a)</a>) |
| </li> |
| <li>A role which might be relevant for lifting is abstract (<a href="#s2.5.b" title="§2.5.(b) Relevant roles" class="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="§6.2.(d) Exceptions" class="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) <span class="title">Problematic declared lifting</span><a class="img" href="s2.html#s2.3.5.a" |
| title="PermaLink to (a) 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="§2.3.2 Declared lifting" class="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) <span class="title">Problematic callout binding</span><a class="img" href="s2.html#s2.3.5.b" |
| title="PermaLink to (b) 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="§3.3.(c) Result translation" |
| class="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) <span class="title">Problematic callin binding</span><a class="img" href="s2.html#s2.3.5.c" |
| title="PermaLink to (c) 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="§4 Callin Binding" class="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="§4.1.(b) Prerequisite: Class binding" |
| class="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) <span class="title">Incompatible redefinition of a role hierarchy</span><a class="img" href="s2.html#s2.3.5.d" |
| title="PermaLink to (d) 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">§2.4 Explicit role creation<a class="img" href="s2.html#s2.4" |
| title="PermaLink to §2.4 Explicit role creation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#top">↑ §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">§2.4.1 Role creation via a lifting constructor<a class="img" href="s2.html#s2.4.1" |
| title="PermaLink to §2.4.1 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">↑ §2.4</a></span></h3> |
| <p>Lifting uses the default constructor for roles (see <a href="#s2.3.1" title="§2.3.1 Implicit role creation" class="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) <span class="title">Team context</span><a class="img" href="s2.html#s2.4.1.a" |
| title="PermaLink to (a) 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) <span class="title">Fresh base object</span><a class="img" href="s2.html#s2.4.1.b" |
| title="PermaLink to (b) 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) <span class="title">Duplicate role runtime check</span><a class="img" href="s2.html#s2.4.1.c" |
| title="PermaLink to (c) 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="§6.1 Reflection" class="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">§2.4.2 Role creation via a regular constructor<a class="img" href="s2.html#s2.4.2" |
| title="PermaLink to §2.4.2 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">↑ §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="§A.5.3 BaseCall" class="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="§2.1.2.(b) Cycles" class="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="§A.5.4 TSuperCall" class="sect">§A.5.4</a>(e)). Also see the constraint in <a href="s1.html#s1.3.2.c" |
| title="§1.3.2.(c) Constructors and overridden 'extends' " |
| class="sect">§1.3.2.(c)</a>. |
| </dd> |
| </dl> |
| <div class="subsect depth4" id="s2.4.2.a"> |
| <h4 class="subsect">(a) <span class="title">Unbound roles</span><a class="img" href="s2.html#s2.4.2.a" |
| title="PermaLink to (a) 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) <span class="title">Bound roles</span><a class="img" href="s2.html#s2.4.2.b" title="PermaLink to (b) 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="§2.3.1 Implicit role creation" class="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="§3.4 Overriding access restrictions" |
| class="sect">§3.4</a>, <a href="#s2.1.2.c" title="§2.1.2.(c) Base class decapsulation" |
| class="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) <span class="title">Super-call for bound roles</span><a class="img" href="s2.html#s2.4.2.c" |
| title="PermaLink to (c) 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="§2.1.(c) Covariant refinement" class="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><args></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">§2.4.3 Role creation in the presence of smart lifting<a class="img" href="s2.html#s2.4.3" |
| title="PermaLink to §2.4.3 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">↑ §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">// => <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="§2.4.1.(b) Fresh base object" |
| class="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">§2.5 Abstract Roles<a class="img" href="s2.html#s2.5" |
| title="PermaLink to §2.5 Abstract Roles"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#top">↑ §2</a></span></h2> |
| <p>Overriding of role classes and dynamic binding of role types (<a href="s1.html#s1.3.1.e" |
| title="§1.3.1.(e) Dynamic binding of types" |
| class="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) <span class="title">Using abstract classes for creation</span><a class="img" href="s2.html#s2.5.a" |
| title="PermaLink to (a) 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&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) <span class="title">Relevant roles</span><a class="img" href="s2.html#s2.5.b" |
| title="PermaLink to (b) 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">§2.6 Explicit base references<a class="img" href="s2.html#s2.6" |
| title="PermaLink to §2.6 Explicit base references"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#top">↑ §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="§3 Callout Binding" class="sect">callout bindings (§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) <span class="title">Externalized roles of a base team</span><a class="img" href="s2.html#s2.6.a" |
| title="PermaLink to (a) 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="§1.2.2 Externalized roles" |
| class="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<@base></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<@<strong>R1</strong>.base></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><@base.<span class="error">field</span>></code> |
| or <code><@<span class="error">field</span>.base></code>. |
| |
| </p> |
| </div> |
| <div class="subsect depth3" id="s2.6.b"> |
| <h4 class="subsect">(b) <span class="title">Explicit base object creation</span><a class="img" href="s2.html#s2.6.b" |
| title="PermaLink to (b) 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="§2.4.2 Role creation via a regular constructor" |
| class="sect">§2.4.2</a>). |
| |
| </p> |
| </div> |
| <div class="subsect depth3" id="s2.6.c"> |
| <h4 class="subsect">(c) <span class="title">Base call in callin method</span><a class="img" href="s2.html#s2.6.c" |
| title="PermaLink to (c) 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="§4.2.(d) Callin methods" |
| class="sect">callin method (§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="§4.3 Base calls" class="sect">§4.3</a>). |
| |
| </p> |
| </div> |
| <div class="subsect depth3" id="s2.6.d"> |
| <h4 class="subsect">(d) <span class="title">Base guard predicates</span><a class="img" href="s2.html#s2.6.d" |
| title="PermaLink to (d) 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="§5.4 Guard predicates" class="sect">Guard predicates (§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="§5.4.2.(a) Base object reference" |
| class="sect">§5.4.2.(a)</a>). |
| |
| </p> |
| </div> |
| <div class="subsect depth3" id="s2.6.e"> |
| <h4 class="subsect">(e) <span class="title">Parameter mappings</span><a class="img" href="s2.html#s2.6.e" |
| title="PermaLink to (e) 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="§4.4 Callin parameter mapping" |
| class="sect">§4.4</a>) or |
| result in a callout binding (<a href="s3.html#s3.2.c" title="§3.2.(c) Result mapping" |
| class="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) <span class="title">Inhibition of modification</span><a class="img" href="s2.html#s2.6.f" |
| title="PermaLink to (f) 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) <span class="title">Decapsulation via base reference</span><a class="img" href="s2.html#s2.6.g" |
| title="PermaLink to (g) 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="§2.6.(d) Base guard predicates" |
| class="sect">§2.6.(d)</a> and <a href="#s2.6.e" title="§2.6.(e) Parameter mappings" class="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="§3.4.(a) Callout to inaccessible base method" |
| class="sect">§3.4.(a)</a> and <a href="s3.html#s3.5.e" title="§3.5.(e) Access control" |
| class="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">§2.7 Advanced structures<a class="img" href="s2.html#s2.7" |
| title="PermaLink to §2.7 Advanced structures"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#top">↑ §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) <span class="title">Nesting</span><a class="img" href="s2.html#s2.7.a" title="PermaLink to (a) 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) <span class="title">Stacking</span><a class="img" href="s2.html#s2.7.b" title="PermaLink to (b) 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) <span class="title">Layering</span><a class="img" href="s2.html#s2.7.c" title="PermaLink to (c) 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="§2.6.(a) Externalized roles of a base team" |
| class="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="§2.7.(d) Implicit playedBy specialization" |
| class="sect">below (§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) <span class="title">Implicit playedBy specialization</span><a class="img" href="s2.html#s2.7.d" |
| title="PermaLink to (d) 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="§2.1.(d) No-variance" class="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<@T1.base></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"><< §1 Teams and Roles</a></td> |
| <td class="top"><a href="index.html" rel="contents">↑ Table of Contents ↑</a></td> |
| <td class="next"><a href="s3.html" rel="next">§3 Callout Binding >></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>© Stephan Herrmann, Christine Hundt, Marco Mosconi</address> |
| OT/J version 1.3.1 — last modified: 2015-06-09 |
| </div> |
| </body> |
| </html> |
