Blame - plugins/org.eclipse.objectteams.otdt.ui.help/guide/otjld/xdef/s6.1.a.html - objectteams/org.eclipse.objectteams

<div class="breadcrumb"><a class="nav" href="s6.html" rel="section">§6 Object Teams API</a> > <a class="nav" href="s6.1.html" rel="section">§6.1 Reflection</a></div>

20

Stephan Herrmann

109893e

2010-05-18 22:02:53 +0000

[diff] [blame]

21

<h4 class="subsect">§6.1.(a) <span class="title">Interface to the role registry</span><a class="img" href="s6.1.a.html"

22

title="PermaLink to (a) Interface to the role registry"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

23

alt="" /></a></h4>

Stephan Herrmann

0166441

2010-04-01 20:28:43 +0000

[diff] [blame]

24

<p>Each team instance internally has a registry of known role objects indexed by their base object.

25

Programmers may make use of this registry using the following reflective methods defined in

26

<code>org.objectteams.ITeam</code>:

</p>

<dl>

<dt><code>boolean hasRole ( Object aBase ) ;</code></dt>

31

<dd>This method checks whether a role for the passed base object already exists in the target team.

32

33

</dd>

Stephan Herrmann

109893e

2010-05-18 22:02:53 +0000

[diff] [blame]

34

<dt><code>boolean hasRole ( Object aBase, Class roleType ) ;</code></dt>

35

<dd>This method checks whether a instance of type <code>roleType</code> as a role for the passed base object

Stephan Herrmann

0166441

2010-04-01 20:28:43 +0000

[diff] [blame]

36

<code>aBase</code> already exists in the target team.

Stephan Herrmann

109893e

2010-05-18 22:02:53 +0000

[diff] [blame]

37

The role may also be of any subtype of the specified role type.<br />

38

If <code>roleType</code> is not a member type of the current team an <code>IllegalArgumentException</code> is thrown.

Stephan Herrmann

0166441

2010-04-01 20:28:43 +0000

[diff] [blame]

39

40

</dd>

41

<dt><code>Object getRole ( Object aBase ) ;</code></dt>

42

<dd>If the passed base object <code>aBase</code> already has a role in the target team, this role is returned.

43

Otherwise <code>null</code> is returned.

44

45

</dd>

Stephan Herrmann

109893e

2010-05-18 22:02:53 +0000

[diff] [blame]

46

<dt><code><T> T getRole ( Object aBase, Class<T> roleType ) ;</code></dt>

47

<dd>If the passed base object <code>aBase</code> already has a role in the target team that is assignable to the type represented by <code>roleType</code>,

48

this role is returned. Otherwise <code>null</code> is returned.<br />

49

If <code>roleType</code> is not a member type of the current team an <code>IllegalArgumentException</code> is thrown.

Stephan Herrmann

0166441

2010-04-01 20:28:43 +0000

[diff] [blame]

50

51

</dd>

52

<dt><code>Object[] getAllRoles () ;</code></dt>

53

<dd>Retrieves all existing (registered) <a href="s2.1.a.html" title="§2.1.(a) Role-base binding"

54

class="sect">bound roles (§2.1.(a))</a> in the target team.

55

<br />

56

This method uses internal structures of weak references. For that reason it may return role instances which were about

57

to be reclaimed by the garbage collector. If performance permits, it is thus advisable to always call <code>System.gc()</code>

58

prior to calling <code>getAllRoles()</code> in order to achieve deterministic results (see also <a href="s2.1.f.html" title="§2.1.(f) Effect on garbage collection"

59

class="sect">§2.1.(f)</a>).

60

61

</dd>

Stephan Herrmann

109893e

2010-05-18 22:02:53 +0000

[diff] [blame]

62

<dt><code><T> T[] getAllRoles ( Class<T> roleType ) ;</code></dt>

Stephan Herrmann

0166441

2010-04-01 20:28:43 +0000

[diff] [blame]

63

<dd>Retrieves all existing (registered) <a href="s2.1.a.html" title="§2.1.(a) Role-base binding"

Stephan Herrmann

109893e

2010-05-18 22:02:53 +0000

[diff] [blame]

64

class="sect">bound roles (§2.1.(a))</a> in the target team that are assignable to the type represented by <code>roleType</code>.

65

<br />

66

If <code>roleType</code> is not a member type of the current team an <code>IllegalArgumentException</code> is thrown.

Stephan Herrmann

0166441

2010-04-01 20:28:43 +0000

[diff] [blame]

67

<br />

68

See the note about garbage collection above.

69

70

</dd>

71

<dt><code>void unregisterRole ( Object aRole ) ;</code></dt>

72

<dd>This method unregisters the passed role object from the target team. Thus the corresponding base looses this role.

73

After calling this method the role should no longer be used.

74

75

</dd>

Stephan Herrmann

109893e

2010-05-18 22:02:53 +0000

[diff] [blame]

76

<dt><code>void unregisterRole ( Object aRole, Class roleType ) ;</code></dt>

77

<dd>This method unregisters the passed role object from the target team. Thus the corresponding base loses this role.

Stephan Herrmann

0166441

2010-04-01 20:28:43 +0000

[diff] [blame]

78

After calling this method the role should no longer be used.

79

The only difference to the previous method is improved speed because no search for the corresponding registry

80

has to be performed.

Stephan Herrmann

109893e

2010-05-18 22:02:53 +0000

[diff] [blame]

81

<br />

82

If <code>roleType</code> is not a member type of the current team an <code>IllegalArgumentException</code> is thrown.

Stephan Herrmann

0166441

2010-04-01 20:28:43 +0000

[diff] [blame]

</dd>

</dl>

<p>It is desirable and possible to use these methods within guards (see <a href="s5.4.html" title="§5.4 Guard predicates" class="sect">§5.4</a>).

87

These methods allow to write the specification of guards in a more concise and more expressive way. Determined by the signature,

88

89

the first four methods can only be used in a base-level guard (<a href="s5.4.2.html" title="§5.4.2 Base guards" class="sect">§5.4.2</a>) because they require a reference to a base object.

90

91

</p>

92

<h5 class="listing">Example code (Guards and Reflection):</h5>

<td><pre><b>public</b> <b>team</b> <b>class</b> SpecialConditions {</pre></td>

</tr>

<td><pre> <b>public</b> <b>void</b> participate(Account <b>as</b> BonusAccount ba) {}</pre></td>

</tr>

<td><pre> <b>public</b> <b>class</b> BonusAccount <b>playedBy</b> Account</pre></td>

</tr>

<td><pre> <b>base</b> when(SpecialConditions.this.<em>hasRole</em>(base, BonusAccount.class))</pre></td>

</tr>

</tr>

<td><pre> <b>callin</b> <b>void</b> creditBonus(<b>int</b> amount) {</pre></td>

</tr>

<td><pre> base.creditBonus(amount + bonus);</pre></td>

</tr>

</tr>

<td><pre> <b>void</b> creditBonus(<b>int</b> amount) <b><-</b> <b>replace</b> <b>void</b> credit(<b>int</b> i)</pre></td>

</tr>

</tr>

</tr>

</tr>

</table>

</div>

<h5>Effects:</h5>

This teams provides a bonus system for registered <code>Account</code>s. Every time an amount of more than 1000 is

148

deposited to a registered account, additional 1% of the amount is credited.

149

150

<ul>

151

<li>The team level method <code>participate</code> in line 2 uses declared lifting (see <a href="s2.3.2.html" title="§2.3.2 Declared lifting" class="sect">§2.3.2</a>)

152

to allow the passed <code>Account</code> object to participate the bonus system provided by the

153

<code>SpecialConditions</code> team.

154

155

</li>

156

<li>The base guard in line 4 uses the reflective method <code>hasRole</code> to check whether the base object already has a role

157

of type <code>BonusAccount</code> in the surrounding team. The expression <code>BonusAccount.class</code> returns

158

the <code>java.lang.Class</code> object representing the role <code>BonusAccount</code>

159

(see <a href="http://java.sun.com/docs/books/jls/second_edition/html/expressions.doc.html#251530"

160

class="ext">JLS §15.8.2</a>).

161

This guard ensures, that only accounts explicitly registered via <code>participate</code> are ever decorated with a role of type <code>BonusAccount</code>.

162

163

</li>

164

<li>The method binding guard in line 10 restricts the callin to <code>creditBonus</code> to calls where

165

the base method argument <code>amount</code> is greater than 1000.

</li>

</ul>

</div>

</div>

<tr>

<td class="top"><a href="index.html" rel="contents">↑ Table of Contents ↑</a></td>

175

<td class="next"><a href="s6.1.b.html" rel="next">§6.1.(b) Behavioral reflection >></a></td>

176

</tr>

177

</table>

178

<div class="breadcrumb"><a class="nav" href="s6.html" rel="section">§6 Object Teams API</a> > <a class="nav" href="s6.1.html" rel="section">§6.1 Reflection</a></div>

179

</div>

180

Stephan Herrmann

109893e

2010-05-18 22:02:53 +0000

[diff] [blame]

181

<hr /><a class="w3c img" href="http://jigsaw.w3.org/css-validator/check/referer"

182

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"

183

184

OT/J version 1.3 — last modified: 2010-05-18

Stephan Herrmann

0166441

2010-04-01 20:28:43 +0000

[diff] [blame]

185

</div>

186

</body>

187

</html>