| <!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="s4.html" rel="prev"><< §4 Callin Binding</a></td> |
| <td class="top"><a href="index.html" rel="contents">↑ Table of Contents ↑</a></td> |
| <td class="next"><a href="s6.html" rel="next">§6 Object Teams API >></a></td> |
| </tr> |
| </table> |
| <div class="chapter" id="s5"> |
| <div class="headl"> |
| <div class="headr"> |
| <h1>§5 Team Activation</h1> |
| </div> |
| </div> |
| <div id="toc-box"> |
| <ul class="toc-box"> |
| <li><a href="s5.html">§5 Team Activation</a></li> |
| <li><a href="#s5.1">§5.1 Effect of team activation</a></li> |
| <li><a href="#s5.2">§5.2 Explicit team activation</a></li> |
| <li><a href="#s5.3">§5.3 Implicit team activation</a></li> |
| <li><a href="#s5.4">§5.4 Guard predicates</a></li> |
| <li><a href="#s5.5">§5.5 Unanticipated team activation</a></li> |
| </ul> |
| </div> |
| <div class="intro"> |
| <h3>The concept of Activation</h3> |
| <div class="line"></div> |
| <div class="term">Binding activation</div> |
| <div class="termdesc">All <strong>callin</strong> bindings of a team only have effect if |
| the team is <strong>active</strong>. Activation may be caused by explicit |
| statements and also happens implicitly at certain points |
| during program execution. |
| </div> |
| <div class="line"></div> |
| <div class="term">Guard predicates</div> |
| <div class="termdesc">Callin bindings can further be controlled using guard predicates, |
| which can be attached to roles and teams at different levels. If a guard |
| predicate evaluates to <code>false</code>, all affected callin bindings |
| are disabled. |
| </div> |
| <div class="line"></div> |
| </div> |
| <div class="sect depth2" id="s5.1"> |
| <h2 class="sect">§5.1 Effect of team activation<a class="img" href="s5.html#s5.1" |
| title="PermaLink to §5.1 Effect of team activation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#top">↑ §5</a></span></h2> |
| <p>Activating a team instance has the effect of enabling all its callin bindings. |
| All effects defined in <a href="s4.html" title="§4 Callin Binding" class="sect">§4</a> apply only if a corresponding |
| team instance is active.<br /> |
| The <strong>order</strong> of team activation controls the order of callin executions. |
| If more than one team intercepts calls to the same base method, the most recently activated |
| team has highest priority in that its before or replace callins are executed first while its after |
| callins are executed last. |
| |
| </p> |
| <div class="sect depth3" id="s5.1.1"> |
| <h3 class="sect">§5.1.1 Global vs. thread local team activation<a class="img" href="s5.html#s5.1.1" |
| title="PermaLink to §5.1.1 Global vs. thread local team activation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#s5.1">↑ §5.1</a></span></h3> |
| <p>While <strong>thread local</strong> activation only enables the callin bindings of |
| a team instance for a certain thread, <strong>global</strong> activation activates the |
| team instance for all threads of the application. |
| |
| </p> |
| </div> |
| <div class="sect depth3" id="s5.1.2"> |
| <h3 class="sect">§5.1.2 Effect on garbage collection<a class="img" href="s5.html#s5.1.2" |
| title="PermaLink to §5.1.2 Effect on garbage collection"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#s5.1">↑ §5.1</a></span></h3> |
| <p>Any active team is referenced by internal infrastructure. |
| Thus, a team cannot be reclaimed by the garbage collector while it is active. |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect depth2" id="s5.2"> |
| <h2 class="sect">§5.2 Explicit team activation<a class="img" href="s5.html#s5.2" |
| title="PermaLink to §5.2 Explicit team activation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#top">↑ §5</a></span></h2> |
| <div class="subsect depth3" id="s5.2.a"> |
| <h4 class="subsect">(a) <span class="title">Activation block</span><a class="img" href="s5.html#s5.2.a" |
| title="PermaLink to (a) Activation block"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>A team can be activated thread local by the block construct</p> |
| <div class="listing plain"><pre><b>within</b> (myTeam) { <i>stmts</i> }</pre></div> |
| <p>If <em>stmts</em> has only one statement this can be abbreviated to |
| </p> |
| <div class="listing plain"><pre><b>within</b> (myTeam) <i>stmt</i></pre></div> |
| <p>In these statements, <code>myTeam</code> must denote a team instance. |
| For the time of executing this block, this team instance is activated for the current thread, |
| which has entered the within block. |
| |
| </p> |
| <p>The <code>within</code> block statement guarantees that it leaves |
| the team in exactly the same activation state as it was in when |
| entering this block. This includes the cases of exceptions, meaning |
| that deactivation will also occur if the execution of the block |
| terminates abnormally. |
| |
| </p> |
| </div> |
| <div class="subsect depth3" id="s5.2.b"> |
| <h4 class="subsect">(b) <span class="title">Imperative activation</span><a class="img" href="s5.html#s5.2.b" |
| title="PermaLink to (b) Imperative activation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>Each team class implicitly provides methods from the predefined interface |
| <code>org.objectteams.ITeam</code> (super interface of all team classes) to control team |
| activation disregarding the block structure of the program. The methods <code>activate()</code> |
| and <code>deactivate()</code> are used to activate and deactivate a team instance for |
| the current thread.<br /> |
| If a team should be de-/activated for another thread this can be done by the methods |
| <code>activate(Thread aThread)</code> and <code>deactivate(Thread aThread)</code>. |
| In order to achieve global activation for all threads the predefined constant |
| <code>org.objectteams.Team.ALL_THREADS</code> is passed to these methods (e.g. |
| <code>activate(Team.ALL_THREADS)</code>).<br /> |
| Note, that this methods make no guarantees with respect to exceptions. |
| |
| </p> |
| </div> |
| <div class="subsect depth3" id="s5.2.c"> |
| <h4 class="subsect">(c) <span class="title">Multiple and mixed activations</span><a class="img" href="s5.html#s5.2.c" |
| title="PermaLink to (c) Multiple and mixed activations"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <ul> |
| <li>If <code>activate()</code> is invoked on a team instance |
| that has been explicitly activated before, this statement has |
| no effect at all (note the difference in <a href="#s5.3.a" title="§5.3.(a) Team level methods" class="sect">§5.3.(a)</a> below). |
| <br /> |
| The same applies to deactivating an inactive team. |
| </li> |
| <li>If a team was already active when entering a <code>within</code> |
| block, it will remain active after leaving the block. |
| </li> |
| <li>If the team was active on entry of a <code>within</code> block |
| and if <code>deactivate()</code> is invoked on the same team |
| instance from within the <code>within</code> block, |
| leaving the block will re-activate the team. |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect depth2" id="s5.3"> |
| <h2 class="sect">§5.3 Implicit team activation<a class="img" href="s5.html#s5.3" |
| title="PermaLink to §5.3 Implicit team activation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#top">↑ §5</a></span></h2> |
| <p>Implicit team activation is intended to ensure that |
| whenever the control flow is passed to a team or one of its roles, |
| the team is implicitly activated for the current thread. |
| Implicit activation can be configured at different levels (see <a href="#s5.3.d" title="§5.3.(d) Configuring implicit activation" |
| class="sect">§5.3.(d)</a>). |
| |
| </p> |
| <p>When implicit activation is enabled a programmer may assume, |
| that whenever a role forwards calls to its base object via callout, |
| the callin bindings of the same role will be active at that time. |
| Exceptions to this rule have to be programmed explicitly. |
| |
| </p> |
| <div class="subsect depth3" id="s5.3.a"> |
| <h4 class="subsect">(a) <span class="title">Team level methods</span><a class="img" href="s5.html#s5.3.a" |
| title="PermaLink to (a) Team level methods"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>While executing a <strong>team level method</strong>, the target team |
| is always active. Activation is reset to the previous state |
| when leaving the team method, unless the team has been explicitly activated during |
| execution of the team method by a call to <code>activate()</code>. |
| Explicit activation is stronger than implicit activation and thus persists after the |
| team level method terminates. Ie., leaving a team level method will never reset |
| an explicit activation. |
| |
| </p> |
| </div> |
| <div class="subsect depth3" id="s5.3.b"> |
| <h4 class="subsect">(b) <span class="title">Methods of externalized roles</span><a class="img" href="s5.html#s5.3.b" |
| title="PermaLink to (b) Methods of externalized roles"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>Invoking a method on an <strong>externalized role</strong> |
| (see <a href="s1.html#s1.2.2" title="§1.2.2 Externalized roles" |
| class="sect">§1.2.2</a>) also has the |
| effect of temporary activation of the team containing the role for the current thread. |
| Regarding deactivation the rule of <a href="#s5.3.a" title="§5.3.(a) Team level methods" class="sect">§5.3.(a)</a> above applies accordingly. |
| |
| </p> |
| </div> |
| <div class="subsect depth3" id="s5.3.c"> |
| <h4 class="subsect">(c) <span class="title">Nested teams</span><a class="img" href="s5.html#s5.3.c" title="PermaLink to (c) Nested teams"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>Implicit activation has additional consequences for nested teams |
| (see <a href="s1.html#s1.5" title="§1.5 Team and role nesting" |
| class="sect">§1.5</a>): |
| |
| </p> |
| <ul> |
| <li>Implicit activation of a team causes the activation of its outer teams.</li> |
| <li>Implicit deactivation of a team causes the deactivation of its inner teams.</li> |
| </ul> |
| </div> |
| <div class="subsect depth3" id="s5.3.d"> |
| <h4 class="subsect">(d) <span class="title">Configuring implicit activation</span><a class="img" href="s5.html#s5.3.d" |
| title="PermaLink to (d) Configuring implicit activation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>Implicit activation is disabled by default and can be enabled by adding the annotation |
| <code>@org.objectteams.ImplicitTeamActivation</code>, which can be applied to a type or a method. |
| When applied to a method it is ensured that invoking this method will trigger implicit activation. |
| When the annotation is applied to a type this has the same effect as applying it to all externally |
| visible methods of the type. Member types are not affected and have to be annotated separately. |
| </p> |
| <p>The runtime environment can be configured globally by defining the system property |
| <code>ot.implicit.team.activation</code> to one of these values: |
| </p> |
| <dl> |
| <dt>NEVER</dt> |
| <dd>Implicit activation is completely disabled.</dd> |
| <dt>ANNOTATED</dt> |
| <dd>This is the default: implicit activation applies only where declared by <code>@ImplicitTeamActivation</code>. |
| </dd> |
| <dt>ALWAYS</dt> |
| <dd>Implicit activation applies to all externally visible methods (this was the default in OTJLD versions ≤1.2)</dd> |
| </dl> |
| </div> |
| <p>Note that among the different mechanisms for activation, <code>within</code> is strongest, |
| followed by <code>(de)activate()</code>, weakest is implicit activation. In this sense, |
| explicit imperative (de)activation may override the block structure of implicit activation |
| (by explicit activation within a team level method), but not that of a <code>within</code> |
| block (by deactivation from a within block). |
| |
| </p> |
| </div> |
| <div class="sect depth2" id="s5.4"> |
| <h2 class="sect">§5.4 Guard predicates<a class="img" href="s5.html#s5.4" |
| title="PermaLink to §5.4 Guard predicates"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#top">↑ §5</a></span></h2> |
| <div class="syntaxlink"><a href="sA.html#sA.7" title="§A.7 Guard predicates" class="syntax">→ Syntax §A.7</a></div> |
| <p>The effect of callins can further be controlled using so called guard predicates. |
| Guards appear at four different levels: |
| |
| </p> |
| <ul> |
| <li>callin method binding</li> |
| <li>role method</li> |
| <li>role class</li> |
| <li>team class</li> |
| </ul> |
| <p>Guards can be specified as <em>regular</em> guards or <code>base</code> guards, |
| which affects the exact point in the control flow, where the guard will be evaluated. |
| |
| </p> |
| <div class="subsect depth3" id="s5.4.a"> |
| <h4 class="subsect">(a) <span class="title">General syntax for guards</span><a class="img" href="s5.html#s5.4.a" |
| title="PermaLink to (a) General syntax for guards"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>A guard is declared using the keyword <code>when</code> followed by a |
| boolean expression in parentheses: |
| |
| </p> |
| <div class="listing plain"><pre><em><b>when</b> (</em><i>predicateExpression</i><em>)</em></pre></div> |
| <p>Depending on the kind of guard different objects are in scope using |
| special identifiers like <code>this</code>, <code>base</code>.<br /> |
| Any predicate expression that evaluates to <code>true</code> enables |
| the callin binding(s) to which it applies. |
| Evaluation to <code>false</code> disables the callin binding(s). |
| |
| </p> |
| </div> |
| <div class="subsect depth3" id="s5.4.b"> |
| <h4 class="subsect">(b) <span class="title">No side effects</span><a class="img" href="s5.html#s5.4.b" |
| title="PermaLink to (b) No side effects"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>A guard predicate should have no side effects. |
| A compiler should optionally check this condition, but inter-procedural analysis |
| actually depends on the availability of appropriate means to mark any method as side-effect free. |
| |
| </p> |
| </div> |
| <div class="subsect depth3" id="s5.4.c"> |
| <h4 class="subsect">(c) <span class="title">Exceptions</span><a class="img" href="s5.html#s5.4.c" title="PermaLink to (c) Exceptions"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>A guard predicate should not throw any exceptions. |
| Yet, any exception thrown within a guard predicate cause the guard to evaluate to <code>false</code> |
| rather than propagating the exception, meaning that the evaluation of a guard predicate will never |
| interrupt the current base behaviour.<br /> |
| A compiler should flag any checked exception that is thrown within a guard. |
| Such diagnosis should by default be treated as an error, with the option of configuring |
| its severity to warning or ignore. |
| |
| </p> |
| </div> |
| <div class="sect depth3" id="s5.4.1"> |
| <h3 class="sect">§5.4.1 Regular guards<a class="img" href="s5.html#s5.4.1" |
| title="PermaLink to §5.4.1 Regular guards"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#s5.4">↑ §5.4</a></span></h3> |
| <p>This group of guards evaluates within the context of a given role. |
| These guards are evaluated <em>after</em> a callin target is lifted and |
| <em>before</em> a callin bound role method is invoked. |
| |
| </p> |
| <div class="subsect depth4" id="s5.4.1.a"> |
| <h4 class="subsect">(a) <span class="title">Method binding guards</span><a class="img" href="s5.html#s5.4.1.a" |
| title="PermaLink to (a) Method binding guards"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>A guard may be attached to a callin method binding as in: |
| |
| </p> |
| <div class="listing plain"><pre><b>void</b> roleMethod(<b>int</b> ir) <b><-</b> <b>after</b> <b>void</b> baseMethod(<b>int</b> ib) |
| <b>when</b> (ir > MyTeam.this.threshold);</pre></div> |
| <p>Such a guard only affects the callin binding to which it is attached, |
| i.e., this specific callin binding is only effective, |
| if the predicate evaluates to <code>true</code>. |
| <br /> |
| The following values are within the scope of the predicate expression, |
| and thus can be used to express the condition: |
| |
| </p> |
| <ul> |
| <li>The role instance denoted by <code>this</code>.<br /> |
| Features of the role instance can also be accessed relative to |
| <code>this</code> with or without explicit qualifying <code>this</code>. |
| |
| </li> |
| <li>The team instance denoted by a qualified this reference as in |
| <code>MyTeam.this</code>. |
| |
| </li> |
| <li>If the callin binding includes signatures (as in the example above): |
| Parameters of the role method.<br /> |
| If parameter mappings are involved, they will be evaluated before evaluating the guard. |
| |
| </li> |
| </ul> |
| </div> |
| <div class="subsect depth4" id="s5.4.1.b"> |
| <h4 class="subsect">(b) <span class="title">Method guards</span><a class="img" href="s5.html#s5.4.1.b" |
| title="PermaLink to (b) Method guards"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>A method guard is similar to a method binding guard, but it applies |
| to all callin method bindings of this method.<br /> |
| A method guard is declared between the method signature and the method body: |
| |
| </p> |
| <div class="listing plain"><pre><b>void</b> roleMethod(<b>int</b> ir) |
| <b>when</b> (ir > MyTeam.this.threshold) { <i>body statements</i> }</pre></div> |
| </div> |
| <div class="subsect depth4" id="s5.4.1.c"> |
| <h4 class="subsect">(c) <span class="title">Role level guards</span><a class="img" href="s5.html#s5.4.1.c" |
| title="PermaLink to (c) Role level guards"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>When a guard is specified at the role level, i.e., directly before the |
| class body of a role class, it applies to all callin method bindings of |
| the role class: |
| |
| </p> |
| <div class="listing plain"><pre><b>protected</b> <b>class</b> MyRole |
| <b>when</b> (value > MyTeam.this.threshold) |
| { |
| <b>int</b> value; |
| <i>other <b>class</b> body declarations</i> |
| }</pre></div> |
| <p>The following values are within the scope of the predicate expression: |
| |
| </p> |
| <ul> |
| <li>The role instance denoted by <code>this</code> (explicit or implicit, see above). |
| Thus, in the example <code>value</code> will be interpreted as a field of the enclosing role. |
| |
| </li> |
| <li>The team instance denoted by a qualified this reference as in <code>MyTeam.this</code></li> |
| </ul> |
| </div> |
| <div class="subsect depth4" id="s5.4.1.d"> |
| <h4 class="subsect">(d) <span class="title">Team level guards</span><a class="img" href="s5.html#s5.4.1.d" |
| title="PermaLink to (d) Team level guards"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>A guard specified in the header of a team class may disable the callin |
| bindings of all contained role classes. The syntax corresponds to the syntax |
| of role level guards.<br /> |
| The only value directly available within team level guard is the |
| team instance (denoted by <code>this</code>) and its features. |
| |
| </p> |
| </div> |
| <p>Of course all guards can also access any visible static feature of a visible class. |
| |
| </p> |
| <p>Even if a guard has no direct effect, because, e.g., a role class has no callin |
| bindings (maybe not even a role-base binding), predicates at such abstract |
| levels are useful, because all predicates are inherited by all sub classes |
| (explicit and implicit). |
| |
| </p> |
| </div> |
| <div class="sect depth3" id="s5.4.2"> |
| <h3 class="sect">§5.4.2 Base guards<a class="img" href="s5.html#s5.4.2" |
| title="PermaLink to §5.4.2 Base guards"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#s5.4">↑ §5.4</a></span></h3> |
| <p>The intention behind base guards is to prevent lifting of a callin-target |
| if a guard evaluates to <code>false</code> and thus refuses to invoke the |
| callin bound role method. Using base guards it is easier to prevent any |
| side-effects caused by a callin binding, because lifting could cause side-effects |
| at two levels: |
| |
| </p> |
| <ul> |
| <li>Creating a role on-demand already is a side-effect (observable e.g. |
| by the reflective function <code><a href="s6.html#s6.1" title="§6.1 Reflection" class="sect">hasRole (§6.1)</a></code>) |
| |
| </li> |
| <li>Role creation triggers execution of a role constructor |
| (see <a href="s2.html#s2.3.1.c" |
| title="§2.3.1.(c) Custom lifting constructor" |
| class="sect">custom lifting constructor (§2.3.1.(c))</a>) |
| which could produce arbitrary side-effects. |
| |
| </li> |
| </ul> |
| <p>Both kinds of side-effects can be avoided using a base guard which prevents |
| unnecessary lifting. |
| |
| </p> |
| <p>Any guard (5.4.1 (b)-(e)) can be turned into a base guard by adding |
| the modifier <code>base</code> as in: |
| |
| </p> |
| <div class="listing plain"><pre><b>protected</b> <b>class</b> MyRole <b>playedBy</b> MyBase |
| <em><b>base</b> when</em> (base.value > MyTeam.this.threshold) |
| { |
| <i><b>class</b> body declarations</i> |
| }</pre></div> |
| <p>However, different scoping rules apply for the identifiers |
| that can be used in a base guard: |
| |
| </p> |
| <div class="subsect depth4" id="s5.4.2.a"> |
| <h4 class="subsect">(a) <span class="title">Base object reference</span><a class="img" href="s5.html#s5.4.2.a" |
| title="PermaLink to (a) Base object reference"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>In all base guard predicates the special identifier <code>base</code> |
| can be used to denote the base object that is about to be lifted. |
| |
| </p> |
| </div> |
| <div class="subsect depth4" id="s5.4.2.b"> |
| <h4 class="subsect">(b) <span class="title">Method binding guards</span><a class="img" href="s5.html#s5.4.2.b" |
| title="PermaLink to (b) Method binding guards"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>A base method binding guard may access parameters as passed to the |
| base method. Parameter mappings are not considered.<br /> |
| Additionally, for <code>after</code> callin bindings, the identifier <code>result</code> |
| may be used to refer to the result of the base method (if any). |
| |
| </p> |
| <div class="note"> |
| <h5>Note:</h5> |
| <p>In order to achieve the same effect of accessing |
| the base method's result, a regular binding guard (not a base guard) |
| must use a suitable parameter mapping (see <a href="s4.html#s4.4.c" |
| title="§4.4.(c) Mapping the result of a base method" |
| class="sect">§4.4.(c)</a>). |
| |
| </p> |
| </div> |
| </div> |
| <div class="subsect depth4" id="s5.4.2.c"> |
| <h4 class="subsect">(c) <span class="title">Method guards</span><a class="img" href="s5.html#s5.4.2.c" |
| title="PermaLink to (c) Method guards"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>In contrast to regular method guards, a <em>base</em> guard attached to a role method |
| cannot access any method parameters. See the next item (d) for values that are actually in scope. |
| |
| </p> |
| </div> |
| <div class="subsect depth4" id="s5.4.2.d"> |
| <h4 class="subsect">(d) <span class="title">Role level guards</span><a class="img" href="s5.html#s5.4.2.d" |
| title="PermaLink to (d) Role level guards"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>Role level base guards may use these values: |
| |
| </p> |
| <ul> |
| <li>The base instance using the special identifier <code>base</code>. |
| </li> |
| <li>The team instance using a qualified this references (<code>MyTeam.this</code>). |
| </li> |
| </ul> |
| </div> |
| <div class="subsect depth4" id="s5.4.2.e"> |
| <h4 class="subsect">(e) <span class="title">Team level guards</span><a class="img" href="s5.html#s5.4.2.e" |
| title="PermaLink to (e) Team level guards"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>Team level base guards have the same scope as role level base guards (d). |
| However, the type of the role instance is not known here, i.e., here <code>base</code> |
| has the static type <code>java.lang.Object</code>. |
| |
| </p> |
| </div> |
| <div class="subsect depth4" id="s5.4.2.f"> |
| <h4 class="subsect">(f) <span class="title">Unbound roles</span><a class="img" href="s5.html#s5.4.2.f" |
| title="PermaLink to (f) Unbound roles"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a></h4> |
| <p>In contrast to regular guards, base guards cannot be attached to |
| unbound role classes nor to their methods.<br /> |
| Only team level base guards are independent of role binding. |
| |
| </p> |
| </div><img src="../images/guards.png" alt="Overview: Guard predicates" /></div> |
| <div class="sect depth3" id="s5.4.3"> |
| <h3 class="sect">§5.4.3 Multiple guards<a class="img" href="s5.html#s5.4.3" |
| title="PermaLink to §5.4.3 Multiple guards"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#s5.4">↑ §5.4</a></span></h3> |
| <p>Due to the different ranges of applicability different guards may affect the same method binding. |
| In that case all applicable guards are conjoined using a logical <code>and</code>.<br /> |
| Any guard is interpreted as the conjunction of these predicates (if present): |
| |
| </p> |
| <ul> |
| <li>The direct predicate expression of the guard.</li> |
| <li>The next outer guard along the chain |
| <em>method binding -> method -> role level -> team level</em></li> |
| <li>The guard at the same level that is inherited from the <em>implicit</em> super role. |
| </li> |
| <li>The guard at the same level that is inherited from the <em>explicit</em> super role. |
| </li> |
| </ul> |
| <h5 class="listing">Example code (Guard Predicates):</h5> |
| <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> ATM {</pre></td> |
| </tr> |
| <tr class="line even"> |
| <td class="ln">2</td> |
| <td><pre> <b>private</b> Bank myBank;</pre></td> |
| </tr> |
| <tr class="line odd"> |
| <td class="ln">3</td> |
| <td><pre> <b>public</b> <b>class</b> ForeignAccount <b>playedBy</b> Account</pre></td> |
| </tr> |
| <tr class="line even"> |
| <td class="ln">4</td> |
| <td><pre> <em><b>base</b> when</em> (!ATM.this.myBank.equals(<em>base</em>.getBank()))</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>callin</b> <b>void</b> debitWithFee(<b>int</b> amount) {</pre></td> |
| </tr> |
| <tr class="line odd"> |
| <td class="ln">7</td> |
| <td><pre> base.debitWithFee(fee+amount);</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> <b>void</b> debitWithFee(<b>int</b> i) <b><-</b> <b>replace</b> <b>void</b> debit(<b>int</b> amount)</pre></td> |
| </tr> |
| <tr class="line even"> |
| <td class="ln">10</td> |
| <td><pre> <em><b>base</b> when</em> (amount < 1000);</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>}</pre></td> |
| </tr> |
| </table> |
| </div> |
| <div class="codecomment"> |
| <h5>Effects:</h5> |
| The team in this example causes that an additional fee has to be payed while debiting |
| less than 1000 Euros from a "foreign" account. |
| |
| <ul> |
| <li>The base guard in line 4 ensures that <code>Account</code> objects only get |
| <code>ForeignAccount</code> roles, if they belong to a different bank than the |
| surrounding <code>ATM</code> team.<br /> |
| It accesses the bank of the base via the <code>base</code> identifier. |
| |
| </li> |
| <li>The method binding guard in line 10 restricts the callin to |
| <code>debitWithFee</code> to calls where the base method argument |
| <code>amount</code> is lower than 1000. |
| |
| </li> |
| <li>A call to <code>Account.debit</code> causes a replace callin to |
| <code>debitWithFee</code><em> only</em> if <em>both</em> predicates evaluate to true. |
| |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="sect depth2" id="s5.5"> |
| <h2 class="sect">§5.5 Unanticipated team activation<a class="img" href="s5.html#s5.5" |
| title="PermaLink to §5.5 Unanticipated team activation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png" |
| alt="" /></a><span class="toplink"><a href="#top">↑ §5</a></span></h2> |
| <p>If an application should be adapted unanticipatedly by one or more teams, |
| this can be achieved without explicitly changing the program code of this application. |
| |
| </p> |
| <p><span class="underline">General activation via config file:</span><br /> |
| Instead of adding the team initialization |
| and activation code to the main program, it is possible to add the respective teams via a config file. |
| Every line of this text file contains the fully qualified name of a compiled team, which has to be available |
| on the classpath. |
| For the instantiation of these teams the default constructor is used, which means adding a team to |
| an application this way requires the team to provide a default constructor. |
| The activation order (see <a href="#s5.1" title="§5.1 Effect of team activation" class="sect">§5.1</a>) for these teams corresponds to the order |
| in which they are listed in the config file.<br /> |
| Lines starting with a '#' denote comment lines. |
| |
| </p> |
| <h5 class="listing">Example config file:</h5> |
| <div class="listing config frame"><pre><span class="comment"># Config file for an ObjectTeams application:</span> |
| <em>mypackage1.MyTeam1</em> |
| <span class="comment"># ...</span> |
| <em>mypackageM.MyTeamN</em></pre></div> |
| <p>To get this config file recognized by the application the VM argument<br /><strong>'-Dot.teamconfig=<<em>config_file_name</em>>'</strong><br /> |
| has to be used when starting the application. |
| |
| </p> |
| <div class="note"> |
| <h5>Note:</h5> |
| In the ObjectTeams Development Tooling (OTDT) teams are activated unanticipatedly |
| via a special tab in the "Run-Configuration" (see <a href="http://www.objectteams.org/distrib/features.html#execution" class="ext">OTDT features</a>), instead. |
| |
| </div> |
| <p><span class="underline">Activation adjustment example:</span><br /> |
| Teams added via the config file mechanism are activated by default. Because no reference to them is |
| stored anywhere, it is not possible to deactivate them later. |
| If deactivation of unanticipated added teams is required, this can be achieved by adding a manager team |
| via config file and encapsulate the actual functionality in another team managed by the manager team. |
| This way a functional team can be activated and deactivated as needed. |
| |
| </p> |
| <h5 class="listing">Example code (Activation Adjustment):</h5> |
| <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> MyManagerTeam {</pre></td> |
| </tr> |
| <tr class="line even"> |
| <td class="ln">2</td> |
| <td><pre> <b>private</b> FunctionalTeam myFunctionalTeam = <b>new</b> FunctionalTeam();</pre></td> |
| </tr> |
| <tr class="line odd"> |
| <td class="ln">3</td> |
| <td><pre> <b>protected</b> <b>class</b> MyRole <b>playedBy</b> MyApplication {</pre></td> |
| </tr> |
| <tr class="line even"> |
| <td class="ln">4</td> |
| <td><pre> <b>void</b> startAdaption() { myFunctionalTeam.activate(); }</pre></td> |
| </tr> |
| <tr class="line odd"> |
| <td class="ln">5</td> |
| <td><pre> startAdaption <b><-</b> <b>before</b> startMethod;</pre></td> |
| </tr> |
| <tr class="line even"> |
| <td class="ln">6</td> |
| <td><pre> <b>void</b> stopAdaption() { myFunctionalTeam.deactivate(); }</pre></td> |
| </tr> |
| <tr class="line odd"> |
| <td class="ln">7</td> |
| <td><pre> stopAdaption <b><-</b> <b>after</b> stopMethod;</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>}</pre></td> |
| </tr> |
| </table> |
| </div> |
| <div class="listing config frame"><pre><span class="comment"># Config file for the manager team example:</span> |
| <em>MyManagerTeam</em></pre></div> |
| <div class="codecomment"> |
| <h5>Effects:</h5> |
| <ul> |
| <li><code>startMethod</code> and <code>stopMethod</code> are methods which demand |
| the activation and deactivation respectively. |
| |
| </li> |
| <li>If the activation/deactivation depends on other conditions these can be checked in addition. |
| |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <table class="nav"> |
| <tr> |
| <td class="back"><a href="s4.html" rel="prev"><< §4 Callin Binding</a></td> |
| <td class="top"><a href="index.html" rel="contents">↑ Table of Contents ↑</a></td> |
| <td class="next"><a href="s6.html" rel="next">§6 Object Teams API >></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: 2013-05-28 |
| </div> |
| </body> |
| </html> |
