Consider the following Java class:
class Point {
private int x, y;
Point(int x, int y) { this.x = x; this.y = y; }
void setX(int x) { this.x = x; }
void setY(int y) { this.y = y; }
int getX() { return x; }
int getY() { return y; }
}
In order to get an intuitive understanding of AspectJ's pointcuts, let's go back to some of the basic principles of Java. Consider the following a method declaration in class Point:
void setX(int x) { this.x = x; }
What this piece of program states is that when an object of type Point has a method called setX with an integer as the argument called on it, then the method body { this.x = x; } is executed. Similarly, the constructor given in that class states that when an object of type Point is instantiated through a constructor with two integers as arguments, then the constructor body { this.x = x; this.y = y; } is executed.
One pattern that emerges from these descriptions is when something happens, then something gets executed. In object-oriented programs, there are several kinds of "things that happen" that are determined by the language. We call these the join points of Java. Join points comprised method calls, method executions, instantiations, constructor executions, field references and handler executions. (See the quick reference for complete listing.)
Pointcuts pick out these join points. For example, the pointcut
pointcut setter(): target(Point) &&
(call(void setX(int)) ||
call(void setY(int)));
describes the calls to setX(int) or setY(int) methods of any instance of Point. Here's another example:
pointcut ioHandler(): within(MyClass) && handler(IOException);
This pointcut picks out the join points at which exceptions of type IOException are handled inside the code defined by class MyClass.
Pointcuts consist of a left-hand side and a right-hand side, separated by a colon. The left-hand side defines the pointcut name and the pointcut parameters (i.e. the data available when the events happen). The right-hand side defines the events in the pointcut.
Pointcuts can then be used to define aspect code in advice, as we will see later. But first let's see what types of events can be captured and how they are described in AspectJ.
Here are examples of designators of
execution(void Point.setX(int))
call(void Point.setX(int))
handler(ArrayOutOfBoundsException)
this(SomeType)
target(SomeType)
within(MyClass)
cflow(void Test.main())
Designators compose through the operations or ("||"), and ("&&") and not ("!").
You can select methods and constructors based on their modifiers and on negations of modifiers. For example, you can say:
which means (1) all invocation of public methods, (2) all executions of non-static methods, and (3) all signatures of the public, non-static methods.Designators can also deal with interfaces. For example, given the interface
interface MyInterface { ... }the designator call(* MyInterface.*(..)) picks out the call join points for methods defined by the interface MyInterface (or its superinterfaces).
When methods and constructors run, there are two interesting times associated with them. That is when they are called, and when they actually execute.
AspectJ exposes these times as call and execution join points, respectively, and allows them to be picked out specifically by call and execution pointcuts.
So what's the difference between these times? Well, there are a number of differences:
Firstly, the lexical pointcut declarations within and withincode match differently. At a call join point, the enclosing text is that of the call site. This means that This means that call(void m()) && within(void m()) will only capture recursive calls, for example. At an execution join point, however, the control is already executing the method.
Secondly, the call join point does not capture super calls to non-static methods. This is because such super calls are different in Java, since they don't behave via dynamic dispatch like other calls to non-static methods.
The rule of thumb is that if you want to pick a join point that runs when an actual piece of code runs, pick an execution, but if you want to pick one that runs when a particular signature is called, pick a call.
Pointcuts are put together with the operators and (spelled &&), or (spelled ||), and not (spelled !). This allows the creation of very powerful pointcuts from the simple building blocks of primitive pointcuts. This composition can be somewhat confusing when used with primitive pointcuts like cflow and cflowbelow. Here's an example:
cflow(P) picks out the join points in the control flow of the join points picked out by P. So, pictorially:
P ---------------------
\
\ cflow of P
\
What does cflow(P) && cflow(Q) pick out? Well, it picks out those join points that are in both the control flow of P and in the control flow of Q. So...
P ---------------------
\
\ cflow of P
\
\
\
Q -------------\-------
\ \
\ cflow of Q \ cflow(P) && cflow(Q)
\ \
Note that P and Q might not have any join points in common... but their control flows might have join points in common.
But what does cflow(P && Q) mean? Well, it means the control flow of those join points that are both picked out by P picked out by Q.
P && Q -------------------
\
\ cflow of (P && Q)
\
and if there are no join points that are both picked by P and picked out by Q, then there's no chance that there are any join points in the control flow of (P && Q).
Here's some code that expresses this.
public class Test {
public static void main(String[] args) {
foo();
}
static void foo() {
goo();
}
static void goo() {
System.out.println("hi");
}
}
aspect A {
pointcut fooPC(): execution(void Test.foo());
pointcut gooPC(): execution(void Test.goo());
pointcut printPC(): call(void java.io.PrintStream.println(String));
before(): cflow(fooPC()) && cflow(gooPC()) && printPC() {
System.out.println("should occur");
}
static before(): cflow(fooPC() && gooPC()) && printPC() {
System.out.println("should not occur");
}
}
Consider, for example, the first pointcut you've seen here,
pointcut setter(): target(Point) &&
(call(void setX(int)) ||
call(void setY(int)));
As we've seen before, the right-hand side of the pointcut picks out the calls to setX(int) or setY(int) methods where the target is any object of type Point. On the left-hand side, the pointcut is given the name "setters" and no parameters. An empty parameter list means that when those events happen no context is immediately available. But consider this other version of the same pointcut:
pointcut setter(Point p): target(p) &&
(call(void setX(int)) ||
call(void setY(int)));
This version picks out exactly the same calls. But in this version, the pointcut has one parameter of type Point. This means that when the events described on the right-hand side happen, a Point object, named by a parameter named "p", is available. According to the right-hand side of the pointcut, that Point object in the pointcut parameters is the object that receives the calls.
Here's another example that illustrates the flexible mechanism for defining pointcut parameters:
pointcut testEquality(Point p): target(Point) &&
args(p) &&
call(boolean equals(Object));
This pointcut also has a parameter of type Point. Similarly to the "setters" pointcut, this means that when the events described on the right-hand side happen, a Point object, named by a parameter named "p", is available. But in this case, looking at the right-hand side, we find that the object named in the parameters is not the target Point object that receives the call; it's the argument (of type Point) passed to the "equals" method on some other target Point object. If we wanted access to both objects, then the pointcut definition that would define target Point p1 and argument Point p2 would be
pointcut testEquality(Point p1, Point p2): target(p1) &&
args(p2) &&
call(boolean equals(Object));
Let's look at another variation of the "setters" pointcut:
pointcut setter(Point p, int newval): target(p) &&
args(newval) &&
(call(void setX(int)) ||
call(void setY(int)));
In this case, a Point object and an integer value are available when the calls happen. Looking at the events definition on the right-hand side, we find that the Point object is the object receiving the call, and the integer value is the argument of the method .
The definition of pointcut parameters is relatively flexible. The most important rule is that when each of those events defined in the right-hand side happen, all the pointcut parameters must be bound to some value. So, for example, the following pointcut definition will result in a compilation error:
pointcut xcut(Point p1, Point p2):
(target(p1) && call(void setX(int))) ||
(target(p2) && call(void setY(int)));
The right-hand side establishes that this pointcut picks out the call join points consisting of the setX(int) method called on a point object, or the setY(int) method called on a point object. This is fine. The problem is that the parameters definition tries to get access to two point objects. But when setX(int) is called on a point object, there is no other point object to grab! So in that case, the parameter p2 is unbound, and hence, the compilation error.
The example below consists of two object classes (plus an exception class) and one aspect. Handle objects delegate their public, non-static operations to their Partner objects. The aspect HandleLiveness ensures that, before the delegations, the partner exists and is alive, or else it throws an exception.
class Handle {
Partner partner = new Partner();
public void foo() { partner.foo(); }
public void bar(int x) { partner.bar(x); }
public static void main(String[] args) {
Handle h1 = new Handle();
h1.foo();
h1.bar(2);
}
}
class Partner {
boolean isAlive() { return true; }
void foo() { System.out.println("foo"); }
void bar(int x) { System.out.println("bar " + x); }
}
aspect HandleLiveness {
before(Handle handle): target(handle) && call(public * *(..)) {
if ( handle.partner == null || !handle.partner.isAlive() ) {
throw new DeadPartnerException();
}
}
}
class DeadPartnerException extends RuntimeException {}