/usr/share/doc/aspectj-doc/adk15notebook/generics-inAspectJ5.html is in aspectj-doc 1.8.8-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Generics in AspectJ 5</title><link rel="stylesheet" type="text/css" href="aspectj-docs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="The AspectJTM 5 Development Kit Developer's Notebook"><link rel="up" href="generics.html" title="Chapter 3. Generics"><link rel="prev" href="generics.html" title="Chapter 3. Generics"><link rel="next" href="autoboxing.html" title="Chapter 4. Autoboxing and Unboxing"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Generics in AspectJ 5</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="generics.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Generics</th><td width="20%" align="right"> <a accesskey="n" href="autoboxing.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="generics-inAspectJ5"></a>Generics in AspectJ 5</h2></div></div></div><p>
AspectJ 5 provides full support for all of the Java 5 language features, including generics. Any legal Java 5 program is a
legal AspectJ 5 progam. In addition, AspectJ 5 provides support for generic and parameterized types in pointcuts, inter-type
declarations, and declare statements. Parameterized types may freely be used within aspect members, and support is
also provided for generic <span class="emphasis"><em>abstract</em></span> aspects.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="matching-generic-and-parameterized-types-in-pointcut-expressions"></a>Matching generic and parameterized types in pointcut expressions</h3></div></div></div><p>
The simplest way to work with generic and parameterized types in pointcut expressions and type patterns
is simply to use the raw type name. For example, the type pattern <code class="literal">List</code> will match
the generic type <code class="literal">List<E></code> and any parameterization of that type
(<code class="literal">List<String>, List<?>, List<? extends Number></code> and so on. This
ensures that pointcuts written in existing code that is not generics-aware will continue to work as
expected in AspectJ 5. It is also the recommended way to match against generic and parameterized types
in AspectJ 5 unless you explicitly wish to narrow matches to certain parameterizations of a generic type.
</p><p>Generic methods and constructors, and members defined in generic types, may use type variables
as part of their signature. For example:</p><pre class="programlisting">
public class Utils {
/** static generic method */
static <T> T first(List<T> ts) { ... }
/** instance generic method */
<T extends Number> T max(T t1, T t2) { ... }
}
public class G<T> {
// field with parameterized type
T myData;
// method with parameterized return type
public List<T> getAllDataItems() {...}
}
</pre><p>
AspectJ 5 does not allow the use of type variables in pointcut expressions and type patterns. Instead, members that
use type parameters as part of their signature are matched by their <span class="emphasis"><em>erasure</em></span>. Java 5 defines the
rules for determing the erasure of a type as follows.
</p><p>Let <code class="literal">|T|</code> represent the erasure of some type <code class="literal">T</code>. Then:</p><table border="0" summary="Simple list" class="simplelist"><tr><td>The erasure of a parameterized type <code class="literal">T<T1,...,Tn></code> is <code class="literal">|T|</code>.
For example, the erasure of <code class="literal">List<String></code> is <code class="literal">List</code>.</td></tr><tr><td>The erasure of a nested type <code class="literal">T.C</code> is <code class="literal">|T|.C</code>. For example,
the erasure of the nested type <code class="literal">Foo<T>.Bar</code> is <code class="literal">Foo.Bar</code>.</td></tr><tr><td>The erasure of an array type <code class="literal">T[]</code> is <code class="literal">|T|[]</code>. For example,
the erasure of <code class="literal">List<String>[]</code> is <code class="literal">List[]</code>.</td></tr><tr><td>The erasure of a type variable is its leftmost bound. For example, the erasure of a
type variable <code class="literal">P</code> is <code class="literal">Object</code>, and the erasure of a type
variable <code class="literal">N extends Number</code> is <code class="literal">Number</code>.</td></tr><tr><td>The erasure of every other type is the type itself</td></tr></table><p>Applying these rules to the earlier examples, we find that the methods defined in <code class="literal">Utils</code>
can be matched by a signature pattern matching <code class="literal">static Object Utils.first(List)</code> and
<code class="literal">Number Utils.max(Number, Number)</code> respectively. The members of the generic type
<code class="literal">G</code> can be matched by a signature pattern matching <code class="literal">Object G.myData</code> and
<code class="literal">public List G.getAllDataItems()</code> respectively.</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp49711328"></a>Restricting matching using parameterized types</h4></div></div></div><p>Pointcut matching can be further restricted to match only given parameterizations of parameter types (methods and constructors), return
types (methods) and field types (fields). This is achieved by specifying a parameterized type pattern at the appropriate point
in the signature pattern. For example, given the class <code class="literal">Foo</code>:</p><pre class="programlisting">
public class Foo {
List<String> myStrings;
List<Float> myFloats;
public List<String> getStrings() { return myStrings; }
public List<Float> getFloats() { return myFloats; }
public void addStrings(List<String> evenMoreStrings) {
myStrings.addAll(evenMoreStrings);
}
}
</pre><p>Then a <code class="literal">get</code> join point for the field <code class="literal">myStrings</code> can be matched by the
pointcut <code class="literal">get(List Foo.myStrings)</code> and by the pointcut <code class="literal">get(List<String> Foo.myStrings)</code>,
but <span class="emphasis"><em>not</em></span> by the pointcut <code class="literal">get(List<Number> *)</code>.</p><p>A <code class="literal">get</code> join point for the field <code class="literal">myFloats</code> can be matched by the
pointcut <code class="literal">get(List Foo.myFloats)</code>, the pointcut <code class="literal">get(List<Float> *)</code>,
and the pointcut <code class="literal">get(List<Number+> *)</code>. This last example shows how AspectJ type
patterns can be used to match type parameters types just like any other type. The pointcut
<code class="literal">get(List<Double> *)</code> does <span class="emphasis"><em>not</em></span> match.</p><p>The execution of the methods <code class="literal">getStrings</code> and <code class="literal">getFloats</code> can be
matched by the pointcut expression <code class="literal">execution(List get*(..))</code>, and the pointcut
expression <code class="literal">execution(List<*> get*(..))</code>, but only <code class="literal">getStrings</code>
is matched by <code class="literal">execution(List<String> get*(..))</code> and only <code class="literal">getFloats</code>
is matched by <code class="literal">execution(List<Number+> get*(..))</code></p><p>A call to the method <code class="literal">addStrings</code> can be matched by the pointcut expression
<code class="literal">call(* addStrings(List))</code> and by the expression <code class="literal">call(* addStrings(List<String>))</code>,
but <span class="emphasis"><em>not</em></span> by the expression <code class="literal">call(* addStrings(List<Number>))</code>.
</p><p>Remember that any type variable reference in a generic member is
<span class="emphasis"><em>always</em></span> matched by its erasure. Thus given the following
example:</p><pre class="programlisting">
class G<T> {
List<T> foo(List<String> ls) { return null; }
}
</pre><p>The execution of <code class="literal">foo</code> can be matched by
<code class="literal">execution(List foo(List))</code>,
<code class="literal">execution(List foo(List<String>>))</code>, and
<code class="literal">execution(* foo(List<String<))</code>but
<span class="emphasis"><em>not</em></span> by <code class="literal">execution(List<Object> foo(List<String>>)</code>
since the erasure of <code class="literal">List<T></code> is <code class="literal">List</code>
and not <code class="literal">List<Object></code>.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp49740176"></a>Generic wildcards and signature matching</h4></div></div></div><p>
When it comes to signature matching, a type parameterized using a generic wildcard is a distinct type.
For example, <code class="literal">List<?></code> is a very different type to <code class="literal">List<String></code>,
even though a variable of type <code class="literal">List<String></code> can be assigned to a variable of
type <code class="literal">List<?></code>. Given the methods:
</p><pre class="programlisting">
class C {
public void foo(List<? extends Number> listOfSomeNumberType) {}
public void bar(List<?> listOfSomeType) {}
public void goo(List<Double> listOfDoubles) {}
}
</pre><div class="variablelist"><dl class="variablelist"><dt><span class="term">execution(* C.*(List))</span></dt><dd><p>Matches an execution join point for any of the three methods.
</p></dd><dt><span class="term">execution(* C.*(List<? extends Number>))</span></dt><dd><p>matches only the
execution of <code class="literal">foo</code>, and <span class="emphasis"><em>not</em></span> the execution
of <code class="literal">goo</code> since <code class="literal">List<? extends Number></code> and
<code class="literal">List<Double></code> are distinct types.
</p></dd><dt><span class="term">execution(* C.*(List<?>))</span></dt><dd><p>matches only the execution of <code class="literal">bar</code>.
</p></dd><dt><span class="term">execution(* C.*(List<? extends Object+>))</span></dt><dd><p>matches both the execution of <code class="literal">foo</code> and the execution of <code class="literal">bar</code>
since the upper bound of <code class="literal">List<?></code> is implicitly <code class="literal">Object</code>.
</p></dd></dl></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp49757792"></a>Treatment of bridge methods</h4></div></div></div><p>Under certain circumstances a Java 5 compiler is required to create <span class="emphasis"><em>bridge
methods</em></span> that support the compilation of programs using raw types. Consider the types</p><pre class="programlisting">
class Generic<T> {
public T foo(T someObject) {
return someObject;
}
}
class SubGeneric<N extends Number> extends Generic<N> {
public N foo(N someNumber) {
return someNumber;
}
}
</pre><p>The class <code class="literal">SubGeneric</code> extends <code class="literal">Generic</code>
and overrides the method <code class="literal">foo</code>. Since the upper bound of the type variable
<code class="literal">N</code> in <code class="literal">SubGeneric</code> is different to the upper bound of
the type variable <code class="literal">T</code> in <code class="literal">Generic</code>, the method <code class="literal">foo</code>
in <code class="literal">SubGeneric</code> has a different erasure to the method <code class="literal">foo</code>
in <code class="literal">Generic</code>. This is an example of a case where a Java 5 compiler will create
a <span class="emphasis"><em>bridge method</em></span> in <code class="literal">SubGeneric</code>. Although you never see it,
the bridge method will look something like this:</p><pre class="programlisting">
public Object foo(Object arg) {
Number n = (Number) arg; // "bridge" to the signature defined in this type
return foo(n);
}
</pre><p>Bridge methods are synthetic artefacts generated as a result of a particular compilation strategy and
have no execution join points in AspectJ 5. So the pointcut <code class="literal">execution(Object SubGeneric.foo(Object))</code>
does not match anything. (The pointcut <code class="literal">execution(Object Generic.foo(Object))</code> matches the
execution of <code class="literal">foo</code> in both <code class="literal">Generic</code> and <code class="literal">SubGeneric</code> since
both are implementations of <code class="literal">Generic.foo</code>).
</p><p>It <span class="emphasis"><em>is</em></span> possible to <span class="emphasis"><em>call</em></span> a bridge method as the following short
code snippet demonstrates. Such a call <span class="emphasis"><em>does</em></span> result in a call join point for the call to
the method.
</p><pre class="programlisting">
SubGeneric rawType = new SubGeneric();
rawType.foo("hi"); // call to bridge method (will result in a runtime failure in this case)
Object n = new Integer(5);
rawType.foo(n); // call to bridge method that would succeed at runtime
</pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp49777168"></a>Runtime type matching with this(), target() and args()</h4></div></div></div><p>The <code class="literal">this()</code>, <code class="literal">target()</code>, and
<code class="literal">args()</code> pointcut expressions all match based on the runtime
type of their arguments. Because Java 5 implements generics using erasure, it is not
possible to ask at runtime whether an object is an instance of a given parameterization of a type
(only whether or not it is an instance of the erasure of that parameterized type). Therefore
AspectJ 5 does not support the use of parameterized types with the <code class="literal">this()</code> and
<code class="literal">target()</code> pointcuts. Parameterized types may however be used in conjunction with
<code class="literal">args()</code>. Consider the following class
</p><pre class="programlisting">
public class C {
public void foo(List<String> listOfStrings) {}
public void bar(List<Double> listOfDoubles) {}
public void goo(List<? extends Number> listOfSomeNumberType) {}
}
</pre><div class="variablelist"><dl class="variablelist"><dt><span class="term">args(List)</span></dt><dd><p>will match an execution or call join point for any of
these methods
</p></dd><dt><span class="term">args(List<String>)</span></dt><dd><p>will match an execution
or call join point for <code class="literal">foo</code>.
</p></dd><dt><span class="term">args(List<Double>)</span></dt><dd><p>matches an execution or call join point for <code class="literal">bar</code>, and <span class="emphasis"><em>may</em></span> match
at an execution or call join point for <code class="literal">goo</code> since it is legitimate to pass an
object of type <code class="literal">List<Double></code> to a method expecting a <code class="literal">List<? extends Number></code>.
</p><p>
In this situation a runtime test would normally be applied to ascertain whether or not the argument
was indeed an instance of the required type. However, in the case of parameterized types such a test is not
possible and therefore AspectJ 5 considers this a match, but issues an <span class="emphasis"><em>unchecked</em></span> warning.
For example, compiling the aspect <code class="literal">A</code> below with the class <code class="literal">C</code> produces the
compilation warning: "unchecked match of List<Double> with List<? extends Number> when argument is
an instance of List at join point method-execution(void C.goo(List<? extends Number>)) [Xlint:uncheckedArgument]";
</p></dd></dl></div><pre class="programlisting">
public aspect A {
before(List<Double> listOfDoubles) : execution(* C.*(..)) && args(listOfDoubles) {
for (Double d : listOfDoubles) {
// do something
}
}
}
</pre><p>Like all Lint messages, the <code class="literal">uncheckedArgument</code> warning can be
configured in severity from the default warning level to error or even ignore if preferred.
In addition, AspectJ 5 offers the annotation <code class="literal">@SuppressAjWarnings</code> which is
the AspectJ equivalent of Java's <code class="literal">@SuppressWarnings</code> annotation. If the
advice is annotated with <code class="literal">@SuppressWarnings</code> then <span class="emphasis"><em>all</em></span>
lint warnings issued during matching of pointcut associated with the advice will be
suppressed. To suppress just an <code class="literal">uncheckedArgument</code> warning, use the
annotation <code class="literal">@SuppressWarnings("uncheckedArgument")</code> as in the following
examples:
</p><pre class="programlisting">
import org.aspectj.lang.annotation.SuppressAjWarnings
public aspect A {
@SuppressAjWarnings // will not see *any* lint warnings for this advice
before(List<Double> listOfDoubles) : execution(* C.*(..)) && args(listOfDoubles) {
for (Double d : listOfDoubles) {
// do something
}
}
@SuppressAjWarnings("uncheckedArgument") // will not see *any* lint warnings for this advice
before(List<Double> listOfDoubles) : execution(* C.*(..)) && args(listOfDoubles) {
for (Double d : listOfDoubles) {
// do something
}
}
}
</pre><p>
The safest way to deal with <code class="literal">uncheckedArgument</code> warnings however is to restrict the pointcut
to match only at those join points where the argument is guaranteed to match. This is achieved by combining
<code class="literal">args</code> with a <code class="literal">call</code> or <code class="literal">execution</code> signature matching
pointcut. In the following example the advice will match the execution of <code class="literal">bar</code> but not
of <code class="literal">goo</code> since the signature of <code class="literal">goo</code> is not matched by the execution pointcut
expression.
</p><pre class="programlisting">
public aspect A {
before(List<Double> listOfDoubles) : execution(* C.*(List<Double>)) && args(listOfDoubles) {
for (Double d : listOfDoubles) {
// do something
}
}
}
</pre><p>Generic wildcards can be used in args type patterns, and matching follows regular Java 5 assignability rules. For
example, <code class="literal">args(List<?>)</code> will match a list argument of any type, and
<code class="literal">args(List<? extends Number>)</code> will match an argument of type
<code class="literal">List<Number>, List<Double>, List<Float></code> and so on. Where a match cannot be
fully statically determined, the compiler will once more issue an <code class="literal">uncheckedArgument</code> warning.
</p><p>Consider the following program:</p><pre class="programlisting">
public class C {
public static void main(String[] args) {
C c = new C();
List<String> ls = new ArrayList<String>();
List<Double> ld = new ArrayList<Double>();
c.foo("hi");
c.foo(ls);
c.foo(ld);
}
public void foo(Object anObject) {}
}
aspect A {
before(List<? extends Number> aListOfSomeNumberType)
: call(* foo(..)) && args(aListOfSomeNumberType) {
// process list...
}
}
</pre><p>From the signature of <code class="literal">foo</code> all we know is that the runtime argument will be an instance of
<code class="literal">Object</code>.Compiling this program gives the unchecked argument warning:
"unchecked match of List<? extends Number> with List when argument is
an instance of List at join point method-execution(void C.foo(Object)) [Xlint:uncheckedArgument]".
The advice will not execute at the call join point for <code class="literal">c.foo("hi")</code> since <code class="literal">String</code>
is not an instance of <code class="literal">List</code>. The advice <span class="emphasis"><em>will</em></span> execute at the call join points
for <code class="literal">c.foo(ls)</code> and <code class="literal">c.foo(ld)</code> since in both cases the argument is an instance of
<code class="literal">List</code>.
</p><p>Combine a wildcard argument type with a signature pattern to avoid unchecked argument matches. In the example
below we use the signature pattern <code class="literal">List<Number+></code> to match a call to any method taking
a <code class="literal">List<Number>, List<Double>, List<Float></code> and so on. In addition the
signature pattern <code class="literal">List<? extends Number+></code> can be used to match a call to a method
declared to take a <code class="literal">List<? extends Number></code>, <code class="literal">List<? extends Double></code>
and so on. Taken together, these restrict matching to only
those join points at which the argument is guaranteed to be an instance of <code class="literal">List<? extends Number></code>.</p><pre class="programlisting">
aspect A {
before(List<? extends Number> aListOfSomeNumberType)
: (call(* foo(List<Number+>)) || call(* foo(List<? extends Number+>)))
&& args(aListOfSomeNumberType) {
// process list...
}
}
</pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp49826384"></a>Binding return values in after returning advice</h4></div></div></div><p>
After returning advice can be used to bind the return value from a matched join point. AspectJ 5 supports the use of
a parameterized type in the returning clause, with matching following the same rules as described for args. For
example, the following aspect matches the execution of any method returning a <code class="literal">List</code>, and makes
the returned list available to the body of the advice.
</p><pre class="programlisting">
public aspect A {
pointcut executionOfAnyMethodReturningAList() : execution(List *(..));
after() returning(List<?> listOfSomeType) : executionOfAnyMethodReturningAList() {
for (Object element : listOfSomeType) {
// process element...
}
}
}
</pre><p>The pointcut uses the raw type pattern <code class="literal">List</code>, and hence it
matches methods returning any kind of list (<code class="literal">List<String>, List<Double></code>,
and so on). We've chosen to bind the returned list as the parameterized type
<code class="literal">List<?></code> in the advice since Java's type checking will now ensure
that we only perform safe operations on the list.</p><p>Given the class</p><pre class="programlisting">
public class C {
public List<String> foo(List<String> listOfStrings) {...}
public List<Double> bar(List<Double> listOfDoubles) {...}
public List<? extends Number> goo(List<? extends Number> listOfSomeNumberType) {...}
}
</pre><p>The advice in the aspect below will run after the execution of <code class="literal">bar</code>
and bind the return value. It will also run after the execution of <code class="literal">goo</code> and
bind the return value, but gives an <code class="literal">uncheckedArgument</code> warning during
compilation. It does <span class="emphasis"><em>not</em></span> run after the execution of <code class="literal">foo</code>.
</p><pre class="programlisting">
public aspect Returning {
after() returning(List<Double> listOfDoubles) : execution(* C.*(..)) {
for(Double d : listOfDoubles) {
// process double...
}
}
}
</pre><p>As with <code class="literal">args</code> you can guarantee that after returning advice only
executes on lists <span class="emphasis"><em>statically determinable</em></span> to be of the right
type by specifying a return type pattern in the associated pointcut. The
<code class="literal">@SuppressAjWarnings</code> annotation can also be used if desired.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp49840992"></a>Declaring pointcuts inside generic types</h4></div></div></div><p>Pointcuts can be declared in both classes and aspects. A pointcut declared in a generic
type may use the type variables of the type in which it is declared. All references to
a pointcut declared in a generic type from outside of that type must be via a parameterized type reference,
and not a raw type reference.</p><p>Consider the generic type <code class="literal">Generic</code> with a pointcut <code class="literal">foo</code>:
</p><pre class="programlisting">
public class Generic<T> {
/**
* matches the execution of any implementation of a method defined for T
*/
public pointcut foo() : execution(* T.*(..));
}
</pre><p>Such a pointcut must be refered to using a parameterized reference as shown
below.</p><pre class="programlisting">
public aspect A {
// runs before the execution of any implementation of a method defined for MyClass
before() : Generic<MyClass>.foo() {
// ...
}
// runs before the execution of any implementation of a method defined for YourClass
before() : Generic<YourClass>.foo() {
// ...
}
// results in a compilation error - raw type reference
before() : Generic.foo() { }
}
</pre></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="inter-type-declarations"></a>Inter-type Declarations</h3></div></div></div><p>
AspectJ 5 supports the inter-type declaration of generic methods, and of members on
generic types. For generic methods, the syntax is exactly as for a regular method
declaration, with the addition of the target type specification:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><T extends Number> T Utils.max(T first, T second) {...}</span></dt><dd><p>Declares a generic instance method <code class="literal">max</code> on the class <code class="literal">Util</code>.
The <code class="literal">max</code> method takes two arguments, <code class="literal">first</code> and <code class="literal">second</code> which must
both be of the same type (and that type must be Number or a subtype of Number) and returns an instance
of that type.
</p></dd><dt><span class="term">static <E> E Utils.first(List<E> elements) {...}</span></dt><dd><p>Declares a static generic method <code class="literal">first</code> on the class <code class="literal">Util</code>.
The <code class="literal">first</code> method takes a list of elements of some type, and returns an instance
of that type.
</p></dd><dt><span class="term"><T> Sorter.new(List<T> elements,Comparator<? super T> comparator) {...}</span></dt><dd><p>Declares a constructor on the class <code class="literal">Sorter</code>.
The constructor takes a list of elements of some type, and a comparator that can compare instances
of the element type.
</p></dd></dl></div><p>
A generic type may be the target of an inter-type declaration, used either in its raw form or with
type parameters specified. If type parameters are specified, then the number of type parameters given
must match the number of type parameters in
the generic type declaration. Type parameter <span class="emphasis"><em>names</em></span> do not have to match.
For example, given the generic type <code class="literal">Foo<T,S extends Number></code> then:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">String Foo.getName() {...}</span></dt><dd><p>Declares a <code class="literal">getName</code> method on behalf of the type <code class="literal">Foo</code>. It is
not possible to refer to the type parameters of Foo in such a declaration.
</p></dd><dt><span class="term">public R Foo<Q, R>.getMagnitude() {...}</span></dt><dd><p>Declares a method <code class="literal">getMagnitude</code> on the generic class <code class="literal">Foo</code>.
The method returns an instance of the type substituted for the second type parameter in an invocation
of <code class="literal">Foo</code> If <code class="literal">Foo</code> is declared as
<code class="literal">Foo<T,N extends Number> {...}</code> then this inter-type declaration is
equivalent to the declaration of a method <code class="literal">public N getMagnitude()</code>
within the body of <code class="literal">Foo</code>.
</p></dd><dt><span class="term">R Foo<Q, R extends Number>.getMagnitude() {...}</span></dt><dd><p>Results in a compilation error since a bounds specification is not allowed in this
form of an inter-type declaration (the bounds are determined from the declaration of the
target type).
</p></dd></dl></div><p>A parameterized type may not be the target of an inter-type declaration. This is because
there is only one type (the generic type) regardless of how many different invocations (parameterizations) of
that generic type are made in a program. Therefore it does not make sense to try and declare a member
on behalf of (say) <code class="literal">Bar<String></code>, you can only declare members on the generic
type <code class="literal">Bar<T></code>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="declare-parents"></a>Declare Parents</h3></div></div></div><p>Both generic and parameterized types can be used as the parent type in a <code class="literal">declare parents</code>
statement (as long as the resulting type hierarchy would be well-formed in accordance with Java's sub-typing
rules). Generic types may also be used as the target type of a <code class="literal">declare parents</code> statement.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">declare parents: Foo implements List<String></span></dt><dd><p>The <code class="literal">Foo</code> type implements the <code class="literal">List<String></code> interface. If
<code class="literal">Foo</code> already implements some other parameterization of the <code class="literal">List</code>
interface (for example, <code class="literal">List<Integer></code> then a compilation error will result since a
type cannot implement multiple parameterizations of the same generic interface type.
</p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="declare-soft"></a>Declare Soft</h3></div></div></div><p>It is an error to use a generic or parameterized type as the softened exception type in a declare soft statement. Java 5 does
not permit a generic class to be a direct or indirect subtype of <code class="literal">Throwable</code> (JLS 8.1.2).</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="generic-aspects"></a>Generic Aspects</h3></div></div></div><p>
AspectJ 5 allows an <span class="emphasis"><em>abstract</em></span> aspect to be declared as a generic type. Any concrete
aspect extending a generic abstract aspect must extend a parameterized version of the abstract aspect.
Wildcards are not permitted in this parameterization.
</p><p>Given the aspect declaration:</p><pre class="programlisting">
public abstract aspect ParentChildRelationship<P,C> {
...
}
</pre><p>then</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">public aspect FilesInFolders extends ParentChildRelationship<Folder,File> {...</span></dt><dd><p>declares a concrete sub-aspect, <code class="literal">FilesInFolders</code> which extends the
parameterized abstract aspect <code class="literal">ParentChildRelationship<Folder,File></code>.
</p></dd><dt><span class="term">public aspect FilesInFolders extends ParentChildRelationship {...</span></dt><dd><p>results in a compilation error since the <code class="literal">ParentChildRelationship</code> aspect must
be fully parameterized.
</p></dd><dt><span class="term">public aspect ThingsInFolders<T> extends ParentChildRelationship<Folder,T></span></dt><dd><p>results in a compilation error since concrete aspects may not have type parameters.
</p></dd><dt><span class="term">public abstract aspect ThingsInFolders<T> extends ParentChildRelationship<Folder,T></span></dt><dd><p>declares a sub-aspect of <code class="literal">ParentChildRelationship</code> in which <code class="literal">Folder</code>
plays the role of parent (is bound to the type variable <code class="literal">P</code>).
</p></dd></dl></div><p>The type parameter variables from a generic aspect declaration may be used in place of a type within any
member of the aspect, <span class="emphasis"><em>except for within inter-type declarations</em></span>.
For example, we can declare a <code class="literal">ParentChildRelationship</code> aspect to
manage the bi-directional relationship between parent and child nodes as follows:
</p><pre class="programlisting">
/**
* a generic aspect, we've used descriptive role names for the type variables
* (Parent and Child) but you could use anything of course
*/
public abstract aspect ParentChildRelationship<Parent,Child> {
/** generic interface implemented by parents */
interface ParentHasChildren<C extends ChildHasParent>{
List<C> getChildren();
void addChild(C child);
void removeChild(C child);
}
/** generic interface implemented by children */
interface ChildHasParent<P extends ParentHasChildren>{
P getParent();
void setParent(P parent);
}
/** ensure the parent type implements ParentHasChildren<child type> */
declare parents: Parent implements ParentHasChildren<Child>;
/** ensure the child type implements ChildHasParent<parent type> */
declare parents: Child implements ChildHasParent<Parent>;
// Inter-type declarations made on the *generic* interface types to provide
// default implementations.
/** list of children maintained by parent */
private List<C> ParentHasChildren<C>.children = new ArrayList<C>();
/** reference to parent maintained by child */
private P ChildHasParent<P>.parent;
/** Default implementation of getChildren for the generic type ParentHasChildren */
public List<C> ParentHasChildren<C>.getChildren() {
return Collections.unmodifiableList(children);
}
/** Default implementation of getParent for the generic type ChildHasParent */
public P ChildHasParent<P>.getParent() {
return parent;
}
/**
* Default implementation of addChild, ensures that parent of child is
* also updated.
*/
public void ParentHasChildren<C>.addChild(C child) {
if (child.parent != null) {
child.parent.removeChild(child);
}
children.add(child);
child.parent = this;
}
/**
* Default implementation of removeChild, ensures that parent of
* child is also updated.
*/
public void ParentHasChildren<C>.removeChild(C child) {
if (children.remove(child)) {
child.parent = null;
}
}
/**
* Default implementation of setParent for the generic type ChildHasParent.
* Ensures that this child is added to the children of the parent too.
*/
public void ChildHasParent<P>.setParent(P parent) {
parent.addChild(this);
}
/**
* Matches at an addChild join point for the parent type P and child type C
*/
public pointcut addingChild(Parent p, Child c) :
execution(* ParentHasChildren.addChild(ChildHasParent)) && this(p) && args(c);
/**
* Matches at a removeChild join point for the parent type P and child type C
*/
public pointcut removingChild(Parent p, Child c) :
execution(* ParentHasChildren.removeChild(ChildHasParent)) && this(p) && args(c);
}
</pre><p>
The example aspect captures the protocol for managing a bi-directional parent-child relationship between
any two types playing the role of parent and child. In a compiler implementation managing an abstract syntax
tree (AST) in which AST nodes may contain other AST nodes we could declare the concrete aspect:
</p><pre class="programlisting">
public aspect ASTNodeContainment extends ParentChildRelationship<ASTNode,ASTNode> {
before(ASTNode parent, ASTNode child) : addingChild(parent, child) {
...
}
}
</pre><p>
As a result of this declaration, <code class="literal">ASTNode</code> gains members:
</p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="literal">List<ASTNode> children</code></td></tr><tr><td><code class="literal">ASTNode parent</code></td></tr><tr><td><code class="literal">List<ASTNode>getChildren()</code></td></tr><tr><td><code class="literal">ASTNode getParent()</code></td></tr><tr><td><code class="literal">void addChild(ASTNode child)</code></td></tr><tr><td><code class="literal">void removeChild(ASTNode child)</code></td></tr><tr><td><code class="literal">void setParent(ASTNode parent)</code></td></tr></table><p>
In a system managing orders, we could declare the concrete aspect:
</p><pre class="programlisting">
public aspect OrderItemsInOrders extends ParentChildRelationship<Order,OrderItem> {
}
</pre><p>
As a result of this declaration, <code class="literal">Order</code> gains members:
</p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="literal">List<OrderItem> children</code></td></tr><tr><td><code class="literal">List<OrderItem> getChildren()</code></td></tr><tr><td><code class="literal">void addChild(OrderItem child)</code></td></tr><tr><td><code class="literal">void removeChild(OrderItem child)</code></td></tr></table><p>and <code class="literal">OrderItem</code> gains members:</p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="literal">Order parent</code></td></tr><tr><td><code class="literal">Order getParent()</code></td></tr><tr><td><code class="literal">void setParent(Order parent)</code></td></tr></table><p>A second example of an abstract aspect, this time for handling exceptions in a uniform
manner, is shown below:</p><pre class="programlisting">
abstract aspect ExceptionHandling<T extends Throwable> {
/**
* method to be implemented by sub-aspects to handle thrown exceptions
*/
protected abstract void onException(T anException);
/**
* to be defined by sub-aspects to specify the scope of exception handling
*/
protected abstract pointcut inExceptionHandlingScope();
/**
* soften T within the scope of the aspect
*/
declare soft: T : inExceptionHandlingScope();
/**
* bind an exception thrown in scope and pass it to the handler
*/
after() throwing (T anException) : inExceptionHandlingScope() {
onException(anException);
}
}
</pre><p>Notice how the type variable <code class="literal">T extends Throwable</code> allows the
components of the aspect to be designed to work together in a type-safe manner. The
following concrete sub-aspect shows how the abstract aspect might be extended to
handle <code class="literal">IOExceptions</code>.</p><pre class="programlisting">
public aspect IOExceptionHandling extends ExceptionHandling<IOException>{
protected pointcut inExceptionHandlingScope() :
call(* doIO*(..)) && within(org.xyz..*);
/**
* called whenever an IOException is thrown in scope.
*/
protected void onException(IOException ex) {
System.err.println("handled exception: " + ex.getMessage());
throw new MyDomainException(ex);
}
}
</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="generics.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="generics.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="autoboxing.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 3. Generics </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 4. Autoboxing and Unboxing</td></tr></table></div></body></html>
|