blob: c1af5ed30e8be9f4bde2088daca83209e692424f [file] [log] [blame]
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "../xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<link rel="stylesheet" type="text/css" href="../css/ot.css" />
<link rel="stylesheet" type="text/css" href="../css/otjld.css" />
<title>OT/J Language Definition v1.3</title>
</head>
<body class="otdt">
<div id="content">
<table class="nav">
<tr>
<td class="back"><a id="top"></a><a href="s6.1.html" rel="prev">&lt;&lt;&nbsp;&sect;6.1&nbsp;Reflection</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.3.html" rel="next">&sect;6.3&nbsp;Annotations&nbsp;&gt;&gt;</a></td>
</tr>
</table>
<div class="breadcrumb"><a class="nav" href="s6.html" rel="section">&sect;6&nbsp;Object Teams API</a></div>
<div class="sect depth2" id="s6.2">
<h2 class="sect">&sect;6.2&nbsp;Other API Elements<a class="img" href="s6.2.html"
title="PermaLink to &sect;6.2&nbsp;Other API Elements"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h2>
<div class="subsect depth3" id="s6.2.a">
<h4 class="subsect">(a)&nbsp;<span class="title">Interfaces for role encapsulation</span><a class="img" href="s6.2.a.html"
title="PermaLink to (a)&nbsp;Interfaces for role encapsulation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>A set of pre-defined types exist that do <span class="underline">not</span> extend <code>java.lang.Object</code>
and have <span class="underline">no</span> features except the operators <code>==</code> and <code>!=</code>.
</p>
<div class="note">
<h5>Note:</h5>
The JLS defines that each interface declares all methods defined in <code>java.lang.Object</code>
(<a href="http://java.sun.com/docs/books/jls/second_edition/html/interfaces.doc.html#32392"
class="ext">JLS &sect;9.2</a>)
and also each object referenced by an interface type can be widened to <code>java.lang.Object</code>.
Compilers commonly implement this by declaring <code>java.lang.Object</code> the super-type of all interfaces.
Such implementation has no visible difference with respect to the more complex definition in the JLS.
</div>
<p>These predefined types are
</p>
<dl>
<dt><code>org.objectteams.IConfined</code></dt>
<dd>regular interface</dd>
<dt><code>org.objectteams.ITeam.IConfined</code></dt>
<dd>role interface</dd>
<dt><code>org.objectteams.Team.Confined</code></dt>
<dd>role class</dd>
</dl>
<p>These types provide no new functionality but inheriting from these types influences the semantics with respect to encapsulation.
The purpose and usage of these types is described in <a href="s7.html" title="&sect;7&nbsp;Role Encapsulation" class="sect">&sect;7</a>.
</p>
</div>
<div class="subsect depth3" id="s6.2.b">
<h4 class="subsect">(b)&nbsp;<span class="title">Interface for explicit lowering</span><a class="img" href="s6.2.b.html"
title="PermaLink to (b)&nbsp;Interface for explicit lowering"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>The following role interface exists for the purpose of allowing explicit lowering:
</p>
<dl>
<dt><code>org.objectteams.ITeam.ILowerable</code></dt>
<dd>role interface</dd>
</dl>
<p>This interface was introduced in detail in <a href="s2.2.d.html" title="&sect;2.2.(d)&nbsp;Explicit lowering"
class="sect">&sect;2.2.(d)</a>.
</p>
</div>
<div class="subsect depth3" id="s6.2.c">
<h4 class="subsect">(c)&nbsp;<span class="title">Team activation methods</span><a class="img" href="s6.2.c.html"
title="PermaLink to (c)&nbsp;Team activation methods"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>Every team can be activated and deactivated by predefined methods of the interface <code>org.objectteams.ITeam</code>.
</p>
<dl>
<dt><code>activate()</code> and <code>activate(Thread th)</code></dt>
<dd>Methods for activation of a team</dd>
<dt><code>deactivate()</code> and <code>deactivate(Thread th)</code></dt>
<dd>Methods for deactivation of a team</dd>
</dl>
<p>The usage of these Methods is described in <a href="s5.2.b.html" title="&sect;5.2.(b)&nbsp;Imperative activation"
class="sect">&sect;5.2.(b)</a>.
</p>
</div>
<div class="subsect depth3" id="s6.2.d">
<h4 class="subsect">(d)&nbsp;<span class="title">Exceptions</span><a class="img" href="s6.2.d.html" title="PermaLink to (d)&nbsp;Exceptions"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>The following <code>Exceptions</code> can be thrown during the execution of an ObjectTeam/Java program:
</p>
<dl>
<dt><code>ResultNotProvidedException</code></dt>
<dd>Thrown if a replace callin without a base call does not provide the necessary (primitive type) base result
(see <a href="s4.3.e.html" title="&sect;4.3.(e)&nbsp;Fragile callin binding"
class="sect">&sect;4.3.(e)</a>).
</dd>
<dt><code>LiftingFailedException</code></dt>
<dd>Thrown if an actual ambiguity occurs during lifting (see <a href="s2.3.4.c.html" title="&sect;2.3.4.(c)&nbsp;Actual ambiguity"
class="sect">&sect;2.3.4.(c)</a>)
or if lifting would need to instantiate an abstract role class (see <a href="s2.5.b.html" title="&sect;2.5.(b)&nbsp;Relevant roles" class="sect">&sect;2.5.(b)</a>).
This is a checked exception.
See <a href="s2.3.5.html"
title="&sect;2.3.5&nbsp;Consequences of lifting problems"
class="sect">&sect;2.3.5</a> for more information.
</dd>
<dt><code>WrongRoleException</code></dt>
<dd>Thrown during lifting if the base object has, with respect to the same team instance, previously been lifted
to a role type that is not conform to the currently requested type
(see <a href="s2.3.4.d.html" title="&sect;2.3.4.(d)&nbsp;Mismatching role"
class="sect">&sect;2.3.4.(d)</a> and <a href="s2.4.3.html"
title="&sect;2.4.3&nbsp;Role creation in the presence of smart lifting"
class="sect">&sect;2.4.3</a>).
</dd>
<dt><code>DuplicateRoleException</code></dt>
<dd>Thrown during explicit role creation, if a new role is created for a base object, which already has a role
of the required type in the given team (see <a href="s2.4.1.c.html"
title="&sect;2.4.1.(c)&nbsp;Duplicate role runtime check"
class="sect">&sect;2.4.1.(c)</a>).
</dd>
<dt><code>RoleCastException</code></dt>
<dd>Thrown during cast of an externalized role, if the casted expression is anchored to a different team instance
than the cast type (see <a href="s1.2.4.b.html" title="&sect;1.2.4.(b)&nbsp;Casting" class="sect">&sect;1.2.4.(b)</a>).
</dd>
<dt><code>LiftingVetoException</code></dt>
<dd>This exception is used internally to abort the process of lifting when a relevant guard predicate (<a href="s5.4.html" title="&sect;5.4&nbsp;Guard predicates" class="sect">&sect;5.4</a>) evaluated to false.
Such exceptions thrown from generated code will never appear in client code, so there is usually no need to catch a <code>LiftingVetoException</code>.
However, in some situations it is useful to explicitly <em>throw</em> a <code>LiftingVetoException</code> from a lifting constructor (<a href="s2.3.1.b.html"
title="&sect;2.3.1.(b)&nbsp;Default lifting constructor"
class="sect">&sect;2.3.1.(b)</a>) of a role.
This style allows to abort lifting even after the lifting constructor has started to work and also for method parameters
requiring lifting.
If lifting was triggered due to a callin method binding, this binding will simply not trigger if a <code>LiftingVetoException</code> is thrown
while preparing the call to the role method.
</dd>
</dl>
</div>
<div class="subsect depth3" id="s6.2.e">
<h4 class="subsect">(e)&nbsp;<span class="title">Role migration</span><a class="img" href="s6.2.e.html" title="PermaLink to (e)&nbsp;Role migration"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"
alt="" /></a></h4>
<p>The following interfaces can be used to enable role migration:</p>
<dl>
<dt><code>IBaseMigratable</code></dt>
<dd>This interface declares a method
<div class="listing plain"><pre>
<code>&lt;B&gt; <b>void</b> migrateToBase(B otherBase)</code> </pre></div>
and instructs the compiler to generate an implementation of this method
for any bound role declaring <code>IBaseMigratable</code> as its super-interface.<br />
The effect of calling <code>migrateToBase</code> on a role instance is to re-bind this role to a new base instance.
The base instance must be compatible to the role's base class (in order to avoid problems during lifting the
compiler may require the base to be of the exact type of the role's base class).
Passing <code>null</code> to this method causes an <code>NullPointerException</code> to be thrown.
</dd>
<dt><code>ITeamMigratable</code></dt>
<dd>This interface declares a method
<div class="listing plain"><pre>
<code>&lt;R&gt; R&lt;@otherTeam&gt; migrateToTeam(<b>final</b> ITeam otherTeam)</code></pre></div>
and instructs the compiler to
generate an implementation of this method for any role declaring <code>ITeamMigratable</code> as its super-interface.<br />
The effect of calling <code>migrateToTeam</code> on a role instance is to re-bind this role to become a contained part of a new team instance.
The team instance must be of the exact type of the role's enclosing team.
Passing <code>null</code> to this method causes a <code>NullPointerException</code> to be thrown.<br /><div class="note">
<h5>Caveat:</h5>
This method intentionally breaks the rules of family polymorphism: any reference <code>R&lt;@previousTeam&gt; r</code>
which was established before migration will incorrectly imply that the role's enclosing team still is <code>previousTeam</code>,
which is no longer true after migration.
While this does not effect any method lookup (which is still safe), further assumptions based on a role's dependent type
are invalidated by team migration. The same holds for references from the migrating role to any sibling role instances.<br />
If the rules of family polymorphism should be maintained one should just refrain from declaring <code>ITeamMigratable</code>
as a role's super-interface.
</div>
</dd>
</dl>
<p>For both methods the signature declared in the interface is over-generalized, yet the compiler performs the necessary checks
to
ensure that role, base and team instances are indeed compatible and additionally the return type of <code>migrateToTeam</code>
is checked as a self-type, i.e., it reflects the exact type of the call target.
</p>
</div>
</div>
<table class="nav">
<tr>
<td class="back"><a href="s6.1.html" rel="prev">&lt;&lt;&nbsp;&sect;6.1&nbsp;Reflection</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.3.html" rel="next">&sect;6.3&nbsp;Annotations&nbsp;&gt;&gt;</a></td>
</tr>
</table>
<div class="breadcrumb"><a class="nav" href="s6.html" rel="section">&sect;6&nbsp;Object Teams API</a></div>
</div>
<div id="footer">
<hr /><a class="w3c img" href="http://jigsaw.w3.org/css-validator/check/referer"
shape="rect"><img src="../images/valid-css2-blue.png" alt="Valid CSS!" height="31" width="88" /></a><a class="w3c img" href="http://validator.w3.org/check?uri=referer" shape="rect"><img src="../images/valid-xhtml10-blue.png" alt="Valid XHTML 1.0 Strict" height="31"
width="88" /></a><address>&copy; Stephan Herrmann, Christine Hundt, Marco Mosconi</address>
OT/J version 1.3 &mdash; last modified: 2011-05-15
</div>
</body>
</html>