blob: ea88fb5efabfaa088ef385e97d3a4650e937037a [file] [log] [blame]
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "../xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<link rel="stylesheet" type="text/css" href="../css/ot.css" />
<link rel="stylesheet" type="text/css" href="../css/otjld.css" />
<title>OT/J Language Definition v1.3.1</title>
</head>
<body class="otdt">
<div id="content">
<table class="nav">
<tr>
<td class="back"><a id="top"></a><a href="s4.html" rel="prev">&lt;&lt;&nbsp;&sect;4&nbsp;Callin Binding</a></td>
<td class="top"><a href="index.html" rel="contents">&uarr;&nbsp;Table of Contents&nbsp;&uarr;</a></td>
<td class="next"><a href="s6.html" rel="next">&sect;6&nbsp;Object Teams API&nbsp;&gt;&gt;</a></td>
</tr>
</table>
<div class="chapter" id="s5">
<div class="headl">
<div class="headr">
<h1>&sect;5&nbsp;Team Activation</h1>
</div>
</div>
<div id="toc-box">
<ul class="toc-box">
<li><a href="s5.html">&sect;5&nbsp;Team Activation</a></li>
<li><a href="#s5.1">&sect;5.1&nbsp;Effect of team activation</a></li>
<li><a href="#s5.2">&sect;5.2&nbsp;Explicit team activation</a></li>
<li><a href="#s5.3">&sect;5.3&nbsp;Implicit team activation</a></li>
<li><a href="#s5.4">&sect;5.4&nbsp;Guard predicates</a></li>
<li><a href="#s5.5">&sect;5.5&nbsp;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">&sect;5.1&nbsp;Effect of team activation<a class="img" href="s5.html#s5.1"
title="PermaLink to &sect;5.1&nbsp;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">&uarr;&nbsp;&sect;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="&sect;4&nbsp;Callin Binding" class="sect">&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">&sect;5.1.1&nbsp;Global vs. thread local team activation<a class="img" href="s5.html#s5.1.1"
title="PermaLink to &sect;5.1.1&nbsp;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">&uarr;&nbsp;&sect;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">&sect;5.1.2&nbsp;Effect on garbage collection<a class="img" href="s5.html#s5.1.2"
title="PermaLink to &sect;5.1.2&nbsp;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">&uarr;&nbsp;&sect;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">&sect;5.2&nbsp;Explicit team activation<a class="img" href="s5.html#s5.2"
title="PermaLink to &sect;5.2&nbsp;Explicit team activation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#top">&uarr;&nbsp;&sect;5</a></span></h2>
<div class="subsect depth3" id="s5.2.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Activation block</span><a class="img" href="s5.html#s5.2.a"
title="PermaLink to (a)&nbsp;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)&nbsp;<span class="title">Imperative activation</span><a class="img" href="s5.html#s5.2.b"
title="PermaLink to (b)&nbsp;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)&nbsp;<span class="title">Multiple and mixed activations</span><a class="img" href="s5.html#s5.2.c"
title="PermaLink to (c)&nbsp;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="&sect;5.3.(a)&nbsp;Team level methods" class="sect">&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">&sect;5.3&nbsp;Implicit team activation<a class="img" href="s5.html#s5.3"
title="PermaLink to &sect;5.3&nbsp;Implicit team activation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#top">&uarr;&nbsp;&sect;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="&sect;5.3.(d)&nbsp;Configuring implicit activation"
class="sect">&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)&nbsp;<span class="title">Team level methods</span><a class="img" href="s5.html#s5.3.a"
title="PermaLink to (a)&nbsp;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)&nbsp;<span class="title">Methods of externalized roles</span><a class="img" href="s5.html#s5.3.b"
title="PermaLink to (b)&nbsp;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="&sect;1.2.2&nbsp;Externalized roles"
class="sect">&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="&sect;5.3.(a)&nbsp;Team level methods" class="sect">&sect;5.3.(a)</a> above applies accordingly.
</p>
</div>
<div class="subsect depth3" id="s5.3.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Nested teams</span><a class="img" href="s5.html#s5.3.c" title="PermaLink to (c)&nbsp;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="&sect;1.5&nbsp;Team and role nesting"
class="sect">&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)&nbsp;<span class="title">Configuring implicit activation</span><a class="img" href="s5.html#s5.3.d"
title="PermaLink to (d)&nbsp;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 &le;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">&sect;5.4&nbsp;Guard predicates<a class="img" href="s5.html#s5.4"
title="PermaLink to &sect;5.4&nbsp;Guard predicates"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#top">&uarr;&nbsp;&sect;5</a></span></h2>
<div class="syntaxlink"><a href="sA.html#sA.7" title="&sect;A.7&nbsp;Guard predicates" class="syntax">&rarr;&nbsp;Syntax&nbsp;&sect;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)&nbsp;<span class="title">General syntax for guards</span><a class="img" href="s5.html#s5.4.a"
title="PermaLink to (a)&nbsp;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)&nbsp;<span class="title">No side effects</span><a class="img" href="s5.html#s5.4.b"
title="PermaLink to (b)&nbsp;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)&nbsp;<span class="title">Exceptions</span><a class="img" href="s5.html#s5.4.c" title="PermaLink to (c)&nbsp;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">&sect;5.4.1&nbsp;Regular guards<a class="img" href="s5.html#s5.4.1"
title="PermaLink to &sect;5.4.1&nbsp;Regular guards"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#s5.4">&uarr;&nbsp;&sect;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)&nbsp;<span class="title">Method binding guards</span><a class="img" href="s5.html#s5.4.1.a"
title="PermaLink to (a)&nbsp;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>&lt;-</b> <b>after</b> <b>void</b> baseMethod(<b>int</b> ib)
<b>when</b> (ir &gt; 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)&nbsp;<span class="title">Method guards</span><a class="img" href="s5.html#s5.4.1.b"
title="PermaLink to (b)&nbsp;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 &gt; MyTeam.this.threshold) { <i>body statements</i> }</pre></div>
</div>
<div class="subsect depth4" id="s5.4.1.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Role level guards</span><a class="img" href="s5.html#s5.4.1.c"
title="PermaLink to (c)&nbsp;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 &gt; 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)&nbsp;<span class="title">Team level guards</span><a class="img" href="s5.html#s5.4.1.d"
title="PermaLink to (d)&nbsp;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">&sect;5.4.2&nbsp;Base guards<a class="img" href="s5.html#s5.4.2"
title="PermaLink to &sect;5.4.2&nbsp;Base guards"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#s5.4">&uarr;&nbsp;&sect;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="&sect;6.1&nbsp;Reflection" class="sect">hasRole (&sect;6.1)</a></code>)
</li>
<li>Role creation triggers execution of a role constructor
(see <a href="s2.html#s2.3.1.c"
title="&sect;2.3.1.(c)&nbsp;Custom lifting constructor"
class="sect">custom lifting constructor (&sect;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 &gt; 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)&nbsp;<span class="title">Base object reference</span><a class="img" href="s5.html#s5.4.2.a"
title="PermaLink to (a)&nbsp;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)&nbsp;<span class="title">Method binding guards</span><a class="img" href="s5.html#s5.4.2.b"
title="PermaLink to (b)&nbsp;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="&sect;4.4.(c)&nbsp;Mapping the result of a base method"
class="sect">&sect;4.4.(c)</a>).
</p>
</div>
</div>
<div class="subsect depth4" id="s5.4.2.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Method guards</span><a class="img" href="s5.html#s5.4.2.c"
title="PermaLink to (c)&nbsp;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)&nbsp;<span class="title">Role level guards</span><a class="img" href="s5.html#s5.4.2.d"
title="PermaLink to (d)&nbsp;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)&nbsp;<span class="title">Team level guards</span><a class="img" href="s5.html#s5.4.2.e"
title="PermaLink to (e)&nbsp;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)&nbsp;<span class="title">Unbound roles</span><a class="img" href="s5.html#s5.4.2.f"
title="PermaLink to (f)&nbsp;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">&sect;5.4.3&nbsp;Multiple guards<a class="img" href="s5.html#s5.4.3"
title="PermaLink to &sect;5.4.3&nbsp;Multiple guards"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#s5.4">&uarr;&nbsp;&sect;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 -&gt; method -&gt; role level -&gt; 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>&lt;-</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 &lt; 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">&sect;5.5&nbsp;Unanticipated team activation<a class="img" href="s5.html#s5.5"
title="PermaLink to &sect;5.5&nbsp;Unanticipated team activation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a><span class="toplink"><a href="#top">&uarr;&nbsp;&sect;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="&sect;5.1&nbsp;Effect of team activation" class="sect">&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=&lt;<em>config_file_name</em>&gt;'</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>&lt;-</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>&lt;-</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">&lt;&lt;&nbsp;&sect;4&nbsp;Callin Binding</a></td>
<td class="top"><a href="index.html" rel="contents">&uarr;&nbsp;Table of Contents&nbsp;&uarr;</a></td>
<td class="next"><a href="s6.html" rel="next">&sect;6&nbsp;Object Teams API&nbsp;&gt;&gt;</a></td>
</tr>
</table>
</div>
<div id="footer">
<hr /><a class="w3c img" href="http://jigsaw.w3.org/css-validator/check/referer"
shape="rect"><img src="../images/valid-css2-blue.png" alt="Valid CSS!" height="31" width="88" /></a><a class="w3c img" href="http://validator.w3.org/check?uri=referer" shape="rect"><img src="../images/valid-xhtml10-blue.png" alt="Valid XHTML 1.0 Strict" height="31"
width="88" /></a><address>&copy; Stephan Herrmann, Christine Hundt, Marco Mosconi</address>
OT/J version 1.3.1 &mdash; last modified: 2013-05-28
</div>
</body>
</html>