/usr/share/doc/aspectj-doc/pdguide/pointcuts-debugging.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 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Debugging pointcuts</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 Problem Diagnosis Guide"><link rel="up" href="pointcuts.html" title="Chapter 2. Debugging Pointcuts"><link rel="prev" href="pointcuts.html" title="Chapter 2. Debugging Pointcuts"><link rel="next" href="ajcore.html" title="Chapter 3. AspectJ Core Files"></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">Debugging pointcuts</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="pointcuts.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Debugging Pointcuts</th><td width="20%" align="right"> <a accesskey="n" href="ajcore.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="pointcuts-debugging"></a>Debugging pointcuts</h2></div></div></div><p>
Go at it top-down and then bottom-up. Top-down, draft significant
aspects by first writing the comments to specify responsibilities.
Advice responsibility usually takes the form, "When X, do Y."
Pointcut responsibility for "When X" often takes the form,
"When [join points] [in locations] [are ...]". These []'s often
translate to named pointcuts (like `libraryCalls() && within(Client)
&& args(Context)`) which form a semantic bridge to the plain-text
meaning in a comment (e.g., `// when the client passes only context into
the library`).
This gets you to a point where you can debug the parts of the
pointcut independently.
</p><p>
Bottom up (to build each part), consider each primitive pointcut
designator (PCD), then the composition, and then any implicit
constraints:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
What kinds of join points should it match? (constructor-call?
field-get?)? This translates to using the kinded pointcuts
(`call(..)`, `get(..)`, etc.).
</p></li><li class="listitem"><p>
Are these restricted to being lexically within something? This
translates to using `within{code}(..)`. If this is true, it should
always be used, to speed up weaving.
</p></li><li class="listitem"><p>
What runtime constraints and context should be true and available at
each join point? This translates to `this()`, `target()`, `args()`,
`cflow{below}()` and `if(..)`.
</p></li><li class="listitem"><p>
Are there any advice or implementation limitations at issue? This
involves knowing the few constraints on AspectJ imposed by Java bytecode
as listed in the AspectJ Programming Guide section on
<a class="ulink" href="../progguide/implementation.html" target="_top">Implementation Notes</a>.
</p></li></ol></div><p>
</p><p>
It's much faster to iterate a pointcut at compile-time
using declare warning (even better, some errors are identified
at parse-time in the latest versions of AJDT).
Start with the parts of the pointcut
that are staticly-determinable (i.e., they do not involve
the runtime PCD's listed above). If compiles themselves
take too long because of all the AspectJ weaving, then
try to only include the debugging aspect with the prototype
pointcut, and limit the scope using <code class="literal">within(..)</code>.
</p><p>
Some mistakes in primitive pointcuts:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
`this(Foo) && execution(static * *(..))`: There is no `this` in a static
context, so `this()` or `target()` should not be used in a static
context or when targetting a static context (respectively). This
happens most often when you want to say things like "all calls to Foo from Bar"
and you only pick out calls to instance methods of Foo
or you try to pick out calls from static methods of Bar.
</p></li><li class="listitem"><p>
`target(Foo) && call(new(..)`: This will never match. In
constructor-call join points, there is no target because the object
has not been created yet.
</p></li><li class="listitem"><p>
`call(* Foo.*(..))`: `Foo` refers to the compile-time type of the
invoking reference, not the implementing class. In Java before 1.4,
the compile-time type was rendered as the defining type, not the
reference type; this was corrected in 1.4 (as shown when using ajc
with the -1.4 flag) Most people should use `target(Foo) && call(...)`.
</p></li><li class="listitem"><p>
`execution(* Foo.bar(..))`: An execution join point for Foo is
always within Foo, so this won't pick out any overrides of bar(..).
Use `target(Foo) && execution(* bar(..))` for instance methods.
</p></li><li class="listitem"><p>
`within(Foo)`: anonymous types are not known at weave-time to be
within the lexically-enclosing type (a limitation of Java bytecode).
</p></li></ul></div><p>
</p><p>
Some mistakes in composition:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
`call(* foo(Bar, Foo)) && args(Foo)`: This will never match.
The parameters in `args(..)` are position-dependent, so `args(Foo)` only picks
out join points where there is only one argument possible, of type Foo.
Use the indeterminate-arguments operator '..' as needed, e.g., `args(Foo, ..)`.
</p></li><li class="listitem"><p>
`call(* foo()) && execution(* foo())`: This will never match. Each
pointcut must be true at each join point matched. For a union of different
kinds of join points (here, call or execution), use '||'.
E.g., to match both method-call and field-get join points, use
`call(* ...) || get(...)`.
</p></li></ul></div><p>
</p><p>
Some mistakes in implicit advice constraints:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
`after () returning (Foo foo) : ...`: after advice can bind the
returned object or exception thrown. That effectively acts like
`target()`, `this()`, or `args()` in restricting when the advice
runs based on the runtime type of the bound object, even though it is
not explicitly part of the pointcut.
</p></li></ul></div><p>
</p><p>
Some mistakes in implementation requirements:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
`ajc` has to control the code for a join point in order to implement
the join point. This translates to an implicit `within({code under
the control of the compiler})` for all join points, with additional
caveat for some join points. Take exception handlers, for example:
there is no way to be sure from the bytecode where the original handler
ends, so `ajc` can't implement after advice on handler join points.
(Since these are on a per-join-point basis, they should be considered
for each corresponding primitive pointcut designator.) Unlike the
mistakes with the primitive PCDs above, the compiler will emit an
error for these caveats.
</p></li><li class="listitem"><p>
`call(@SuperAnnotation Subclass.meth()`: Annotations are not inherited
by default, so e.g., if the pointcut specifies an annotation, then
subclass implementations of that method will not be matched.
</p></li></ul></div><p>
</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pointcuts.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pointcuts.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ajcore.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. Debugging Pointcuts </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 3. AspectJ Core Files</td></tr></table></div></body></html>
|