Join Points and Pointcuts

Join Points and Pointcuts
Prev	Chapter 2. The AspectJ Language	Next

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.

Designators

Here are examples of designators of

when a particular method body executes: execution(void Point.setX(int))
when a method is called: call(void Point.setX(int))
when an exception handler executes: handler(ArrayOutOfBoundsException)
when the object currently executing (i.e. this) is of type SomeType: this(SomeType)
when the target object is of type SomeType: target(SomeType)
when the executing code belongs to class MyClass: within(MyClass)

Designators compose through the operations or ("||"), and ("&&") and not ("!").

It is possible to use wildcards. So
1. execution(* *(..))
2. call(* set(..))
means (1) all the executions of methods with any return and parameter types and (2) method calls of set methods with any return and parameter types -- in case of overloading there may be more than one; this designator picks out all of them.
You can select elements based on types. For example,
1. execution(int *())
2. call(* setY(long))
3. call(* Point.setY(int))
4. call(*.new(int, int))
means (1) all executions of methods with no parameters, returning an int (2) the calls of setY methods that take a long as an argument, regardless of their return type or defining type, (3) the calls of class Point's setY methods that take an int as an argument, regardless of the return type, and (4) the calls of all classes' constructors that take two ints as arguments.
You can compose designators. For example,
1. target(Point) && call(int *())
2. call(* *(..)) && (within(Line) || within(Point))
3. within(*) && execution(*.new(int))
4. this(*) && !this(Point) && call(int *(..))
means (1) all calls to methods received by instances of class Point, with no parameters, returning an int, (2) all calls to all methods where the call is being made from the code defined in Point and Line, (3) executions of constructors of all classes, that take an int as an argument, and (4) all method calls of any method returning an int, from all objects except Point objects to any other objects.
You can select methods and constructors based on their modifiers and on negations of modifiers. For example, you can say:
1. call(public * *(..))
2. execution(!static * *(..))
3. execution(public !static * *(..))
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).

Pointcut Parameters

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(Point));

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 point in the parameters is not the Point object that receives the call; it's the argument of the "equals" method on some other Point object. If we wanted access to both objects, then the pointcut definition should be

  pointcut testEquality(Point p1, Point p2): target(p1) &&
                                             args(p2) &&
                                             call(boolean equals(Point));

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.

Example: `HandleLiveness`

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 {}

Prev	Home	Next
The Anatomy of an Aspect	Up	Advice