Blame - plugins/org.eclipse.objectteams.otdt.ui.help/guide/otjld/xdef/s3.html - objectteams/org.eclipse.objectteams

<h4 class="subsect">(b) <span class="title">Definition</span><a class="img" href="s3.1.b.html" title="PermaLink to (b) Definition"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

80

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

Stephan Herrmann

0166441

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

[diff] [blame]

81

<p>A callout binding maps an abstract role method ("expected method")

82

to a concrete base method ("provided method").

83

It may appear within the role class at any place where feature

84

declarations are allowed. It is denoted by

85

86

</p>

87

<div class="listing plain"><pre><i>expected_method_designator</i> <b>-></b> <i>provided_method_designator;</i></pre></div>

88

<p>The effect is that any call to the role method will be forwarded to the

89

associated base object using the provided base method.

90

91

</p>

92

<h5 class="listing">Example code (Callout):</h5>

<td><pre><b>team</b> <b>class</b> Company {</pre></td>

</tr>

<td><pre> <b>public</b> <b>class</b> Employee <b>playedBy</b> Person {</pre></td>

</tr>

<td><pre> <b>abstract</b> String getIdentification();</pre></td>

</tr>

<td><pre> <span class="comment">// callout binding see below...</span></pre></td>

</tr>

</tr>

</tr>

</table>

</div>

</div>

Stephan Herrmann

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

[diff] [blame]

123

<h4 class="subsect">(c) <span class="title">Kinds of method designators</span><a class="img" href="s3.1.c.html"

124

title="PermaLink to (c) Kinds of method designators"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

125

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

Stephan Herrmann

0166441

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

[diff] [blame]

126

<p>A method designator may either be a method name

</p>

<td><pre>getIdentification <em>-></em> getName;</pre></td>

</tr>

</table>

</div>

a complete method signature including parameter declarations and

139

return type declaration, but excluding any modifiers and declared exceptions.

</p>

<td><pre>String getIdentification() <em>-></em> String getName();</pre></td>

</tr>

</table>

</div>

<h5>Effects:</h5>

<ul>

<li> Line 4 declares a callout binding for the role method <code>getIdentification()</code>,

154

providing an implementation for the abstract method defined in line 3.

155

</li>

156

<li> In combination with the role binding in line 2 this has the following effect:</li>

157

<li> Any call to <code>Employee.getIdentification</code>

158

is forwarded to the method <code>Person.getName</code>.

</li>

</ul>

</div>

<p>Both sides of a callout binding must use the same kind of

163

designators, i.e., designators with and without signature may not be mixed.

164

<br />

165

Each method designator must uniquely select one method.

166

If a method designator contains a signature this signature must match exactly with the signature

167

of an existing method, i.e., no implicit conversions are applied for this matching.

168

If overloading is involved, signatures <em>must</em> be used to disambiguate.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

173

<h4 class="subsect">(d) <span class="title">Inheritance of role method declarations</span><a class="img" href="s3.1.d.html"

174

title="PermaLink to (d) Inheritance of role method declarations"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

175

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

Stephan Herrmann

0166441

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

[diff] [blame]

176

<p>The role method being bound by a callout may be declared in the same

177

class as the binding or it may be inherited from a super class or

super interface.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

183

<h4 class="subsect">(e) <span class="title">Callout override</span><a class="img" href="s3.1.e.html" title="PermaLink to (e) Callout override"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

184

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

Stephan Herrmann

0166441

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

[diff] [blame]

185

<p>If an inherited role method is concrete, callout binding regarding this

186

method must use the token "<code>=></code>" instead of "<code>-></code>"

187

in order to declare that this binding overrides an existing implementation.

188

<br />

189

190

Using the "<code>=></code>" operator for an abstract method is an error.

191

<br />

192

It is also an error (and not useful anyway) to callout-bind a method that is

193

implemented in the same class as the binding.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

198

<h4 class="subsect">(f) <span class="title">Inheritance of callout bindings</span><a class="img" href="s3.1.f.html"

199

title="PermaLink to (f) Inheritance of callout bindings"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

200

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

Stephan Herrmann

0166441

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

[diff] [blame]

201

<p> Callout bindings are inherited along explicit and implicit inheritance.

202

Inherited callout bindings can be overridden using "<code>=></code>".

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

207

<h4 class="subsect">(g) <span class="title">Duplicate bindings</span><a class="img" href="s3.1.g.html"

208

title="PermaLink to (g) Duplicate bindings"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

209

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

Stephan Herrmann

0166441

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

[diff] [blame]

210

<p>It is an error if a role class has multiple callout bindings for the

same role method.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

216

<h4 class="subsect">(h) <span class="title">Declared exceptions</span><a class="img" href="s3.1.h.html"

217

title="PermaLink to (h) Declared exceptions"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

218

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

Stephan Herrmann

0166441

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

[diff] [blame]

219

<p>It is an error if a base method to be bound by <strong>callout</strong>

220

declares in its <code>throws</code> clause any exceptions that

221

are not declared by the corresponding role method.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

226

<h4 class="subsect">(i) <span class="title">Shorthand definition</span><a class="img" href="s3.1.i.html"

227

title="PermaLink to (i) Shorthand definition"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

228

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

Stephan Herrmann

0166441

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

[diff] [blame]

229

<p> A callout binding whose method designators specify

230

full method signatures does not require an existing role method.

231

If no role method is found matching the expected method of

232

such a callout binding, a new method is implicitly generated.

233

The new method is static iff the bound base method is static,

234

and it declares the same exceptions as the bound base method.

</p>

<p>

A shorthand callout may optionally declare a <strong>visibility modifier</strong>,

239

otherwise the generated method inherits the visibility modifier of the bound base method.

240

No further modifiers are set.

241

If a callout overrides an inherited method or callout,

242

it must not reduce the visibility of the inherited method/callout.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

247

<h4 class="subsect">(j) <span class="title">Inferred callout</span><a class="img" href="s3.1.j.html" title="PermaLink to (j) Inferred callout"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

248

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

Stephan Herrmann

0166441

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

[diff] [blame]

249

<p> If a non-abstract role class inherits an abstract method the compiler

250

tries to infer a callout binding for implementing the abstract method.

251

Similarly, if a self-call in a role class cannot be resolved, the compiler

252

tries to infer a callout to resolve the self-call.<br />

253

Inference searches for a method in the bound base class such that

</p>

<ol>

<li>both methods have the same name</li>

258

<li>both methods have the same number of arguments</li>

259

<li>each argument of the abstract role method is compatible to the

260

corresponding argument of the base method directly, or using

261

boxing/unboxing or lowering.

</li>

</ol>

<p>

Callouts inferred from an interface have <code>public</code> visibility,

266

callouts inferred from a self-call have <code>private</code> visibility.

</p>

<p>

Per default inferred callout bindings are disabled, i.e., a compiler

271

must report these as an error. However, a compiler should allow to

272

configure reporting to produce a warning only (which can be suppressed

273

using a <code>@SuppressWarnings("inferredcallout")</code> annotation),

274

or to completely ignore the diagnostic.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

279

<h4 class="subsect">(k) <span class="title">Callout to generic method</span><a class="img" href="s3.1.k.html"

280

title="PermaLink to (k) Callout to generic method"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

281

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

Stephan Herrmann

0166441

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

[diff] [blame]

282

<p>When referring to a generic base method</p>

</tr>

</table>

</div>

<p>a callout binding may either propagate the method's genericity as in</p>

</tr>

</table>

</div>

<p>or it may supply a valid substitution for the type parameter as in</p>

<td><pre>String rm(String a) <b>-></b> String bm(String a);</pre></td>

</tr>

</table>

</div>

</div>

<p>A callout binding either attaches an implementation to a previously declared method

311

or adds (<a href="#s3.1.i" title="§3.1.(i) Shorthand definition" class="sect">§3.1.(i)</a> above) a forwarding method to a role class.

312

Apart from this implementation, callout-bound methods do not differ from regular methods.

313

314

</p>

315

<p>When we say, a callout binding defines <strong>forwarding</strong> this means that

316

control is passed to the base object. In contrast, by a <strong>delegation</strong>

317

semantics control <em>would</em> remain at the role object, such that self-calls

318

would again be dispatched starting at the role. Callout bindings on

319

their own do not support delegation. However, in conjunction with method

320

overriding by means of callin bindings (see <a href="s4.html" title="§4 Callin Binding" class="sect">§4</a>)

321

the effect of delegation can easily be achieved.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

326

<h2 class="sect">§3.2 Callout parameter mapping<a class="img" href="s3.2.html"

327

title="PermaLink to §3.2 Callout parameter mapping"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

328

alt="" /></a><span class="toplink"><a href="#top">↑ §3</a></span></h2>

Stephan Herrmann

0166441

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

[diff] [blame]

329

<div class="syntaxlink"><a href="sA.html#sA.4.1" title="§A.4.1 CalloutParameterMappings"

330

class="syntax">→ Syntax §A.4.1</a></div>

331

Stephan Herrmann

109893e

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

[diff] [blame]

332

<h4 class="subsect">(a) <span class="title">with clause</span><a class="img" href="s3.2.a.html" title="PermaLink to (a) with clause"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

333

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

Stephan Herrmann

0166441

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

[diff] [blame]

334

<p> If the method designators in a callout binding are signatures

335

(not just method names), parameters and return value may

336

be mapped by a <code>with{...}</code> sub-clause. Parameter mappings may only occur if the enclosing role is a class, not an interface.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

341

<h4 class="subsect">(b) <span class="title">Mapping one parameter</span><a class="img" href="s3.2.b.html"

342

title="PermaLink to (b) Mapping one parameter"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

343

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

Stephan Herrmann

0166441

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

[diff] [blame]

344

<p> For each parameter of the provided base method, exactly one parameter

345

mapping defines, which value will actually be passed to

346

the base method. Callout parameter mappings have this form:

347

348

</p>

349

<div class="listing plain"><pre><i>expression</i> <b>-></b> <i>base_method_parameter_name</i></pre></div>

350

</div>

351

Stephan Herrmann

109893e

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

[diff] [blame]

352

<h4 class="subsect">(c) <span class="title">Result mapping</span><a class="img" href="s3.2.c.html" title="PermaLink to (c) Result mapping"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

353

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

Stephan Herrmann

0166441

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

[diff] [blame]

354

<p>The return value of a callout method may be provided by a result mapping:

355

356

</p>

357

<div class="listing plain"><pre>result <b><-</b> <i>expression</i></pre></div>

358

<p>The right hand side expression of a result mapping may use the special identifier

359

<code>result</code> to refer to the value returned by the base method.

360

<br />

361

In a method binding with parameter mappings, it is an error to use

362

<code>result</code> as the name of a regular method argument.

363

364

</p>

365

<h5 class="listing">Example code (Callout Parameter Mapping):</h5>

<td><pre>Integer absoluteValue(Integer integer) <b>-></b> <b>int</b> abs(<b>int</b> i) <em><b>with</b> {</em></pre></td>

</tr>

<td><pre> integer.intValue() <b>-></b> i,</pre></td>

</tr>

<td><pre> <em>result</em> <b><-</b> <b>new</b> Integer(<em>result</em>)</pre></td>

</tr>

</tr>

</table>

</div>

</div>

Stephan Herrmann

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

[diff] [blame]

388

<h4 class="subsect">(d) <span class="title">Visible names</span><a class="img" href="s3.2.d.html" title="PermaLink to (d) Visible names"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

389

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

Stephan Herrmann

0166441

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

[diff] [blame]

390

<p>Each identifier that appears within the expressions of a parameter

391

mapping must be either:

</p>

<ul>

<li>a feature visible in the scope of the role instance.</li>

396

<li>a parameter of the role method (for parameter mappings).</li>

397

<li>the special name <code>result</code> (for result mappings).

398

</li>

399

<li>in a result mapping also the special name <code>base</code> can be used

400

in order to refer to the bound base instance (provided the method being

401

bound is not static).

402

</li>

403

</ul>

404

<p>The names of base method arguments (i.e., names after mapping) are only

405

legal in the position given in <a href="#s3.2.b" title="§3.2.(b) Mapping one parameter"

406

class="sect">§3.2.(b)</a>.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

411

<h4 class="subsect">(e) <span class="title">Implicit parameter mappings</span><a class="img" href="s3.2.e.html"

412

title="PermaLink to (e) Implicit parameter mappings"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

413

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

Stephan Herrmann

0166441

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

[diff] [blame]

414

<p>If parameter mappings should be omitted the following conditions must hold:

</p>

<ol>

<li>each method parameter of the role method must conform to the

419

corresponding parameter of the base method, <em>and</em></li>

420

<li>the result type of the base method must conform to the result type

of the role method.

</li>

</ol>

<p>Here conformance includes translation polymorphism (cf. <a href="#s3.3.d" title="§3.3.(d) Typing rules" class="sect">§3.3.(d)</a>).

425

<br />

426

Parameter correspondence without parameter mapping is determined by declaration order not by names.

427

<br />

428

Two adjustments can, however, be performed implicitly:

</p>

<ul>

<li>If the role method has more parameters than the base method,

433

unused trailing parameters may be silently ignored.

434

</li>

435

<li>If the role method returns <code>void</code>, any result from

436

the base method may be silently ignored.

</li>

</ul>

</div>

<h5 class="listing">Example code (Callout with Parameter Mapping):</h5>

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

</tr>

<td><pre> <b>public</b> <b>abstract</b> <b>class</b> Role1 {</pre></td>

</tr>

<td><pre> <b>abstract</b> <b>void</b> payEuro(float euro);</pre></td>

</tr>

<td><pre> <b>abstract</b> float earnEuro();</pre></td>

</tr>

<td><pre> <b>void</b> idle(<b>int</b> seconds) { <span class="comment">/* do nothing */</span> };</pre></td>

</tr>

</tr>

<td><pre> Role1 boss, worker = <span class="comment">// initialization omitted</span></pre></td>

</tr>

<td><pre> <b>public</b> <b>void</b> transaction () {</pre></td>

</tr>

<td><pre> boss.payEuro(worker.earnEuro());</pre></td>

</tr>

</tr>

</tr>

</tr>

<td><pre><b>public</b> <b>class</b> Staff { <span class="comment">// a base class </span></pre></td>

</tr>

<td><pre> <b>public</b> <b>void</b> payDM (float dm) { … };</pre></td>

</tr>

<td><pre> <b>public</b> float earnDM () { … };</pre></td>

</tr>

<td><pre> <b>public</b> <b>int</b> doze() { … };</pre></td>

</tr>

<td><pre> <span class="comment">// other methods omitted</span></pre></td>

</tr>

</tr>

<td><pre><b>public</b> <b>team</b> <b>class</b> MySubTeam <b>extends</b> MyTeamA {</pre></td>

</tr>

<td><pre> <b>public</b> <b>class</b> Role1 <b>playedBy</b> Staff {</pre></td>

</tr>

<td><pre> <b>void</b> payEuro(float euro) <b>-></b> <b>void</b> payDM(float dm) <b>with</b> {</pre></td>

</tr>

</tr>

</tr>

<td><pre> float earnEuro() <b>-></b> float earnDM () <b>with</b> {</pre></td>

</tr>

<td><pre> result <b><-</b> result / 1.95583f</pre></td>

</tr>

</tr>

<td><pre> idle <b>=></b> doze; <span class="comment">// override existing implementation of idle()</span></pre></td>

</tr>

</tr>

</tr>

<td><pre> transaction();</pre></td>

</tr>

</tr>

</tr>

</table>

</div>

<h5>Effects:</h5>

<ul>

<li>Class <code>MyTeamA</code> is declaratively complete and can be

577

type checked because it only uses methods that are visible or declared within this

578

context. <code>MyTeamA.Role1</code> can, however, not be instantiated, because it is

579

abstract.

580

</li>

581

<li>Line 30 has the normal effect of invoking <code>transaction</code>.

582

</li>

583

<li>When executing <code>transaction</code>, the call of <code>worker.earnEuro()</code>

584

is forwarded to the corresponding base object using method <code>earnDM()</code>

585

(binding declaration in line 24).

586

The result is converted by "<code>result / 1.95583f</code>" (line 25).

587

</li>

588

<li>Within the same execution of <code>transaction</code>, the call of

589

<code>boss.payEuro()</code>

590

is forwarded to the corresponding base object using method <code>payDM()</code>

591

(binding declaration in line 21).

592

The parameter <code>euro</code> is converted by "<code>euro * 1.95583f</code>"

593

(line 22).

594

</li>

595

<li>Method <code>idle</code> is forwarded to <code>doze</code> without any

596

parameter mapping. This requires <code>doze</code> to have a signature

597

that is conformable to the signature of <code>idle</code>.

598

In this case a role parameter and a base result are ignored.<br />

599

Using the <code>=></code> operator, this binding overrides the existing

600

implementation of <code>idle</code>.

</li>

</ul>

</div>

</div>

Stephan Herrmann

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

[diff] [blame]

606

<h2 class="sect">§3.3 Lifting and lowering<a class="img" href="s3.3.html"

607

title="PermaLink to §3.3 Lifting and lowering"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

608

alt="" /></a><span class="toplink"><a href="#top">↑ §3</a></span></h2>

Stephan Herrmann

0166441

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

[diff] [blame]

609

<p> (For basic definitions see <a href="s2.2.html" title="§2.2 Lowering" class="sect">§2.2</a> and <a href="s2.3.html" title="§2.3 Lifting" class="sect">§2.3</a>)

</p>

Stephan Herrmann

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

[diff] [blame]

613

<h4 class="subsect">(a) <span class="title">Call target translation</span><a class="img" href="s3.3.a.html"

614

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

615

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

Stephan Herrmann

0166441

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

[diff] [blame]

616

<p>Invoking a base method due to a callout binding first

617

<strong>lowers</strong> the role object in order to obtain the effective call target.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

622

<h4 class="subsect">(b) <span class="title">Parameter translation</span><a class="img" href="s3.3.b.html"

623

title="PermaLink to (b) Parameter translation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

624

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

Stephan Herrmann

0166441

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

[diff] [blame]

625

<p>Passing a role object as parameter to a callout method implicitly <strong>lowers</strong>

626

this parameter, if the base method declares a corresponding base type parameter.

627

<br />

628

Lifting of callout parameters is not possible.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

633

<h4 class="subsect">(c) <span class="title">Result translation</span><a class="img" href="s3.3.c.html"

634

title="PermaLink to (c) Result translation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

635

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

Stephan Herrmann

0166441

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

[diff] [blame]

636

<p> When returning a base object from a callout method where the role

637

method declares the result to be of a role class,

638

this object is implicitly <strong>lifted</strong> to the appropriate role.

639

<br />

640

Lowering the result of a callout binding is not possible.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

645

<h4 class="subsect">(d) <span class="title">Typing rules</span><a class="img" href="s3.3.d.html" title="PermaLink to (d) Typing rules"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

646

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

Stephan Herrmann

0166441

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

[diff] [blame]

647

<p>A parameter mapping (implicit by parameter position or explicit

648

by a <code>with</code> clause) is <strong>well typed</strong> if

649

the left hand side conforms to the right hand side, either by

</p>

<ul>

<li>type equality</li>

654

<li>implicit primitive type conversion</li>

655

<li>subtype polymorphism</li>

656

<li>translation polymorphism, here: <em>lowering</em>,

657

</li>

658

<li><em>or</em> by a combination of the above.

659

</li>

660

</ul>

661

<p>A result mapping (implicit or explicit by a <code>with</code> clause)

662

is well typed, if the value at the right hand side conforms to the

663

left hand side according to the rules given above, except that

664

translation polymorphism here applies <em>lifting</em> instead of

lowering.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

670

<h4 class="subsect">(e) <span class="title">Role arrays</span><a class="img" href="s3.3.e.html" title="PermaLink to (e) Role arrays"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

671

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

Stephan Herrmann

0166441

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

[diff] [blame]

672

<p>For arrays of roles as parameters <a href="s2.2.e.html" title="§2.2.(e) Lowering of arrays"

673

class="sect">§2.2.(e)</a> applies accordingly.

674

For arrays as a return value <a href="s2.3.d.html" title="§2.3.(d) Lifting of arrays"

675

class="sect">§2.3.(d)</a> applies.

</p>

</div>

</div>

Stephan Herrmann

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

[diff] [blame]

681

<h2 class="sect">§3.4 Overriding access restrictions<a class="img" href="s3.4.html"

682

title="PermaLink to §3.4 Overriding access restrictions"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

683

alt="" /></a><span class="toplink"><a href="#top">↑ §3</a></span></h2>

Stephan Herrmann

0166441

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

[diff] [blame]

684

<p>In contrast to normal access restrictions, method bindings

685

may refer to hidden base methods.

686

This concept is the inverse of encapsulation, hence it is called

687

<strong>decapsulation</strong>.

688

<br />

689

Decapsulation may occur in these positions:

</p>

<ul>

<li><code>playedBy</code> declaration (see <a href="s2.1.2.c.html" title="§2.1.2.(c) Base class decapsulation"

694

class="sect">§2.1.2.(c)</a>)

695

</li>

696

<li>base constructor call (see <a href="s2.4.2.b.html" title="§2.4.2.(b) Bound roles" class="sect">§2.4.2.(b)</a>).

697

</li>

698

<li>callout bindings (see next)</li>

699

<li>callout to field (see <a href="#s3.5.e" title="§3.5.(e) Access control" class="sect">§3.5.(e)</a>)

700

</li>

701

<li>base call within a callin method (see <a href="s4.6.html" title="§4.6 Overriding access restrictions"

702

class="sect">§4.6</a>)

</li>

</ul>

Stephan Herrmann

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

[diff] [blame]

706

<h4 class="subsect">(a) <span class="title">Callout to inaccessible base method</span><a class="img" href="s3.4.a.html"

707

title="PermaLink to (a) Callout to inaccessible base method"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

708

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

Stephan Herrmann

0166441

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

[diff] [blame]

709

<p>By means of <strong>callout</strong> bindings it is possible to access

710

methods of a base class regardless of their access modifiers.

711

Method bindings are the only place in a program which may mention otherwise

712

inaccessible methods.

713

Access to the callout method at the role side is controlled by regular mechanisms,

714

based on the declaration of the role method.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

719

<h4 class="subsect">(b) <span class="title">Sealing against decapsulation</span><a class="img" href="s3.4.b.html"

720

title="PermaLink to (b) Sealing against decapsulation"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

721

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

Stephan Herrmann

0166441

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

[diff] [blame]

722

<p>A base package may be "sealed" which re-establishes the standard Java visibility rules.

723

<br />

724

Sealing is achieved by the corresponding capability of Jar files.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

729

<h4 class="subsect">(c) <span class="title">Warning levels</span><a class="img" href="s3.4.c.html" title="PermaLink to (c) Warning levels"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

730

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

Stephan Herrmann

0166441

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

[diff] [blame]

731

<p>A compiler should signal any occurrence of decapsulation.

732

If a compiler supports to configure warnings this may be used to let the user choose to

733

(a) ignore base class decapsulation, (b) treat it as a warning or even

734

(c) treat it as an error (cf. <a href="s2.1.2.c.html" title="§2.1.2.(c) Base class decapsulation"

735

class="sect">§2.1.2.(c)</a>).

736

<br />

737

Optionally, a batch compiler may support three levels of verbosity with respect to decapsulation:

</p>

<tr>

<td rowspan="1" colspan="1"><tt>-nodecapsulation</tt></td>

743

<td rowspan="1" colspan="1">No warnings.</td>

744

</tr>

745

<tr>

746

<td rowspan="1" colspan="1"><em>default</em></td>

747

<td rowspan="1" colspan="1">Warn only if/that access restrictions are overridden.</td>

748

</tr>

749

<tr>

750

<td rowspan="1" colspan="1"><tt>-decapsulation</tt></td>

751

<td rowspan="1" colspan="1">Detailed messages containing the binding and the hidden base method.</td>

</tr>

</table>

</div>

Stephan Herrmann

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

[diff] [blame]

756

<h4 class="subsect">(d) <span class="title">Private methods from super classes</span><a class="img" href="s3.4.d.html"

757

title="PermaLink to (d) Private methods from super classes"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

758

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

Stephan Herrmann

0166441

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

[diff] [blame]

759

<p>If a callout binding shall bind to a private base method, that method

760

must be defined in the exact base class to which the current role

761

class is bound using <code>playedBy</code>. I.e., for private methods

762

<a href="#s3.1.d"

763

title="§3.1.(d) Inheritance of role method declarations"

764

class="sect">§3.1.(d)</a> does not hold.

765

<br />

766

The same holds for private base fields (see below).

767

<br />

768

If a private base feature must indeed be callout-bound, a role class

769

must be defined that is played by the exact base class defining the

770

private feature. Another role bound to a sub-base-class can then

771

be defined as a sub class of the first role. It will inherit the

772

callout binding and through this it can access the desired feature.

</p>

<td><pre><b>public</b> <b>class</b> SuperBase {</pre></td>

</tr>

<td><pre> <em><b>private</b> <b>int</b> secret;</em></pre></td>

</tr>

</tr>

<td><pre><b>public</b> <b>class</b> SubBase <b>extends</b> SuperBase { <span class="comment">/* details omitted */</span> }</pre></td>

</tr>

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

</tr>

<td><pre> <b>protected</b> <b>class</b> SuperRole <b>playedBy</b> SuperBase {</pre></td>

</tr>

<td><pre> <b>int</b> steal() <b>-></b> <b>get</b> <b>int</b> <em>secret</em>; <span class="comment">// <span class="green"><strong>OK</strong></span></span></pre></td>

</tr>

</tr>

<td><pre> <b>protected</b> <b>class</b> SubRole <b>extends</b> SuperRole <b>playedBy</b> SubBase {</pre></td>

</tr>

<td><pre> <b>int</b> steal() <b>-></b> <b>get</b> <b>int</b> <em>secret</em>; <span class="comment">// <span class="error"><strong>illegal!</strong></span></span></pre></td>

</tr>

</tr>

</tr>

</table>

</div>

</div>

</div>

Stephan Herrmann

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

[diff] [blame]

830

<h2 class="sect">§3.5 Callout to field<a class="img" href="s3.5.html"

831

title="PermaLink to §3.5 Callout to field"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

832

alt="" /></a><span class="toplink"><a href="#top">↑ §3</a></span></h2>

Stephan Herrmann

0166441

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

[diff] [blame]

833

<p>Also fields of a base class can be made accessible using a callout binding.

</p>

Stephan Herrmann

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

[diff] [blame]

837

<h4 class="subsect">(a) <span class="title">Syntax</span><a class="img" href="s3.5.a.html" title="PermaLink to (a) Syntax"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

838

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

Stephan Herrmann

0166441

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

[diff] [blame]

839

<p>Using one of the callout modifiers <code>get</code> or <code>set</code> a role method

840

can be bound to a field of the role's base class:

</p>

<td><pre>getValue <b>-></b> <em>get</em> value;</pre></td>

</tr>

<td><pre>setValue <b>-></b> <em>set</em> value;</pre></td>

</tr>

<td><pre><b>int</b> getValue() <b>-></b> <em>get</em> <b>int</b> value;</pre></td>

</tr>

</table>

</div>

<p>where <code>getValue</code>, <code>setValue</code> are abstract role methods of

860

appropriate signatures and <code>value</code> is a field of the bound base class.

861

<br />

862

A longer syntax is available, too (see line 3 above), which uses complete signatures.

863

For the left hand side <a href="#s3.1.c" title="§3.1.(c) Kinds of method designators"

864

class="sect">§3.1.(c)</a> applies, for the

865

right hand side, this longer version prepends the field type to the field name.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

870

<h4 class="subsect">(b) <span class="title">Compatibility</span><a class="img" href="s3.5.b.html" title="PermaLink to (b) Compatibility"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

871

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

Stephan Herrmann

0166441

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

[diff] [blame]

872

<p>A role method bound with the modifier <code>get</code>

873

should have no arguments

874

(it <em>may</em> have arbitrary arguments, which are silently ignored)

875

and should have a return type to which the base field is compatible.

876

A role method returning void will ignore the given value and thus has

877

no effect at all, which will be signaled by a compiler warning.

878

<br />

879

A role method bound with the modifier <code>set</code> must have a first argument

880

that is compatible to the base field's type (additional arguments - if present -

881

are silently ignored) and must not declare a return type.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

886

<h4 class="subsect">(c) <span class="title">Value mapping</span><a class="img" href="s3.5.c.html" title="PermaLink to (c) Value mapping"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

887

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

Stephan Herrmann

0166441

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

[diff] [blame]

888

<p>Values can be mapped similar to parameter mappings in pure method bindings

889

(<a href="#s3.2" title="§3.2 Callout parameter mapping" class="sect">§3.2</a>). Such mappings can be used to establish compatibility as required above.

890

<br />

891

In both <code>get</code> and <code>set</code> bindings, the base side value is denoted

892

by the field's name (lines 2 and 4 below).

</p>

<td><pre>Integer getValue() -> <em>get</em> <b>int</b> val</pre></td>

</tr>

<td><pre> <em>with</em> { result <- <b>new</b> Integer(val) }</pre></td>

</tr>

<td><pre><b>void</b> setValue(Integer i) -> <em>set</em> <b>int</b> val</pre></td>

</tr>

<td><pre> <em>with</em> { i.intValue() -> val }</pre></td>

</tr>

</table>

</div>

</div>

Stephan Herrmann

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

[diff] [blame]

917

<h4 class="subsect">(d) <span class="title">Effect</span><a class="img" href="s3.5.d.html" title="PermaLink to (d) Effect"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

918

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

Stephan Herrmann

0166441

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

[diff] [blame]

919

<p>Callout-binding a role method to a base field generates an implementation for

920

this role method, by which it acts as a getter or setter for the given

921

field of the associated base object.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

926

<h4 class="subsect">(e) <span class="title">Access control</span><a class="img" href="s3.5.e.html" title="PermaLink to (e) Access control"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

927

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

Stephan Herrmann

0166441

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

[diff] [blame]

928

<p>For accessing an otherwise invisible field, the rules for

929

<a href="#s3.4" title="§3.4 Overriding access restrictions"

930

class="sect">decapsulation (§3.4)</a> apply accordingly.

931

<br />

932

Recall, that according to

933

<a href="http://java.sun.com/docs/books/jls/second_edition/html/classes.doc.html#40898"

934

class="ext">JLS §8.3</a>

935

fields may be hidden in sub-classes of a given base class. Therefore, it is relevant to know that a callout to

936

a field will always access the field that is visible in the exact base

937

class of the role class defining the callout. This is especially relevant

938

for accessing private fields.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

943

<h4 class="subsect">(f) <span class="title">Shorthand definition</span><a class="img" href="s3.5.f.html"

944

title="PermaLink to (f) Shorthand definition"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

945

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

Stephan Herrmann

0166441

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

[diff] [blame]

946

<p>Just as in <a href="#s3.1.i" title="§3.1.(i) Shorthand definition" class="sect">§3.1.(i)</a> a shorthand definition allows to introduce

947

a callout field access method without prior abstract declaration.

948

This requires the callout field binding to specify types as in line 3 of <a href="#s3.5.a" title="§3.5.(a) Syntax" class="sect">§3.5.(a)</a> above.

949

The generated access method is static iff the bound base field is static.

</p>

<p>

A shorthand callout to field may optionally declare a <strong>visibility modifier</strong>,

954

otherwise the generated method inherits the visibility modifier of the bound base field.

955

No further modifiers are set.

956

If a callout to field overrides an inherited method or callout,

957

it must not reduce the visibility of the inherited method/callout.

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

962

<h4 class="subsect">(g) <span class="title">Callout override</span><a class="img" href="s3.5.g.html" title="PermaLink to (g) Callout override"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

963

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

Stephan Herrmann

0166441

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

[diff] [blame]

964

<p>Similar to method callouts a callout to field may override an existing role

965

method if and only if the token <code>=></code> is used instead of <code>-></code>

966

(see <a href="#s3.1.e" title="§3.1.(e) Callout override" class="sect">§3.1.(e)</a> and <a href="#s3.1.f" title="§3.1.(f) Inheritance of callout bindings"

967

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

</p>

</div>

Stephan Herrmann

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

[diff] [blame]

972

<h4 class="subsect">(h) <span class="title">Inferred callout</span><a class="img" href="s3.5.h.html" title="PermaLink to (h) Inferred callout"><img style="vertical-align:text-top;margin-left:5px;" src="../images/permalink.png"

973

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

Stephan Herrmann

0166441

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

[diff] [blame]

974

<p> If a statement or expression within the body of a bound role class

975

uses a simple name or a name qualified by <code>this</code>

976

which can not be resolved using normal rules,

977

the compiler may infer to use a callout to field instead,

978

given that a field of the required name can be found in the role's declared baseclass.

979

980

</p>

981

<p> If a callout to field has explicitly been declared it is used for the otherwise

982

unresolved name, if and only if:

</p>

<ul>

<li>the callout declares a role method name the is constructed from the token "set" for

987

a setter or "get" for a getter plus the field name with capital first letter,

988

</li>

989

<li>the base field referenced by the callout has exactly the required name, and</li>

990

<li>the callout kind (set/get) matches the application of the unresolved name as either

991

the left-hand side of an assignment (set) or as an expression (get).

</li>

</ul>

<p>

If a matching callout to field is not found, the compiler generates one automatically,

996

which has <code>private</code> visibility.

</p>

<p>

If a callout to field has been inferred it is an error to directly invoke the

1001

implicitly generated callout accessor that is formed according to the above rules.

</p>

<p>

Per default inferred callout bindings are disabled, i.e., a compiler

1006

must report these as an error. However, a compiler should allow to

1007

configure reporting to produce a warning only (which can be suppressed

1008

using a <code>@SuppressWarnings("inferredcallout")</code> annotation),

1009

or to completely ignore the diagnostic. See also <a href="#s3.1.j" title="§3.1.(j) Inferred callout" class="sect">§3.1.(j)</a>.

</p>

</div>

</div>

</div>

<tr>

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

1019

<td class="next"><a href="s4.html" rel="next">§4 Callin Binding >></a></td>

</tr>

</table>

</div>

Stephan Herrmann

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

[diff] [blame]

1025

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

1026

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"

1027

Stephan Herrmann

8f0fa31

2010-06-08 18:24:55 +0000

[diff] [blame^]

1028

OT/J version 1.3 — last modified: 2010-06-08

Stephan Herrmann

0166441

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

[diff] [blame]

1029

</div>

1030

</body>

1031

</html>