Pointcuts and Advice
Prev | Chapter 9. An Annotation Based Development Style | Next

## Pointcuts and Advice

Pointcut and advice declarations can be made using the `Pointcut, Before, After, AfterReturning, AfterThrowing,` and `Around` annotations.

### Pointcuts

Pointcuts are specified using the `org.aspectj.lang.annotation.Pointcut` annotation on a method declaration. The method should have a `void` return type. The parameters of the method correspond to the parameters of the pointcut. The modifiers of the method correspond to the modifiers of the pointcut.

As a general rule, the `@Pointcut` annotated method must have an empty method body and must not have any `throws` clause. If formal are bound (using `args(), target(), this(), @args(), @target(), @this(), @annotation())` in the pointcut, then they must appear in the method signature.

The `if()` pointcut is treated specially and is discussed in a later section.

Here is a simple example of a pointcut declaration in both code and @AspectJ styles:

         @Pointcut("call(* *.*(..))")
         void anyCall() {}

is equivalent to...

         pointcut anyCall() : call(* *.*(..));

When binding arguments, simply declare the arguments as normal in the annotated method:

         @Pointcut("call(* *.*(int)) && args(i) && target(callee)")
         void anyCall(int i, Foo callee) {}

is equivalent to...

         pointcut anyCall(int i, Foo callee) : call(* *.*(int)) && args(i) && target(callee);

An example with modifiers (Remember that Java 5 annotations are not inherited, so the `@Pointcut` annotation must be present on the extending aspect's pointcut declaration too):

         @Pointcut("")
         protected abstract void anyCall();

is equivalent to...

         protected abstract pointcut anyCall();

#### Type references inside @AspectJ annotations

Using the code style, types referenced in pointcut expressions are resolved with respect to the imported types in the compilation unit. When using the annotation style, types referenced in pointcut expressions are resolved in the absence of any imports and so have to be fully qualified if they are not by default visible to the declaring type (outside of the declaring package and `java.lang` ). This does not apply to type patterns with wildcards, which are always resolved in a global scope.

Consider the following compilation unit:

         package org.aspectprogrammer.examples;

         import java.util.List;

         public aspect Foo {

           pointcut listOperation() : call(* List.*(..));

           pointcut anyUtilityCall() : call(* java.util..*(..));

         }

Using the annotation style this would be written as:

         package org.aspectprogrammer.examples;

         import java.util.List; // redundant but harmless

         @Aspect
         public class Foo {

           @Pointcut("call(* java.util.List.*(..))") // must qualify
           void listOperation() {}

           @Pointcut("call(* java.util..*(..))")
           void anyUtilityCall() {}

         }

#### if() pointcut expressions

In code style, it is possible to use the `if(...)` poincut to define a conditional pointcut expression which will be evaluated at runtime for each candidate join point. The `if(...)` body can be any valid Java boolean expression, and can use any exposed formal, as well as the join point forms `thisJoinPoint, thisJoinPointStaticPart and thisJoinPointEnclosingStaticPart` .

When using the annotation style, it is not possible to write a full Java expression within the annotation value so the syntax differs slightly, whilst providing the very same semantics and runtime behaviour. An `if()` pointcut expression can be declared in an `@Pointcut` , but must have either an empty body (`if()`, or be one of the expression forms `if(true)` or `if(false)` . The annotated method must be public, static, and return a boolean. The body of the method contains the condition to be evaluated. For example:

         @Pointcut("call(* *.*(int)) && args(i) && if()")
         public static boolean someCallWithIfTest(int i) {
            return i > 0;
         }

is equivalent to...

         pointcut someCallWithIfTest(int i) : call(* *.*(int)) && args(i) && if(i > 0);

and the following is also a valid form:

         static int COUNT = 0;

         @Pointcut("call(* *.*(int)) && args(i) && if()")
         public static boolean someCallWithIfTest(int i, JoinPoint jp, JoinPoint.EnclosingStaticPart esjp) {
            // any legal Java expression...
            return i > 0
                   && jp.getSignature().getName.startsWith("doo")
                   && esjp.getSignature().getName().startsWith("test")
                   && COUNT++ < 10;
         }

         @Before("someCallWithIfTest(anInt, jp, enc)")
         public void beforeAdviceWithRuntimeTest(int anInt, JoinPoint jp, JoinPoint.EnclosingStaticPart enc) {
            //...
         }

         // Note that the following is NOT valid
         /*
         @Before("call(* *.*(int)) && args(i) && if()")
         public void advice(int i) {
            // so you were writing an advice or an if body ?
         }
         */

It is thus possible with the annotation style to use the `if()` pointcut only within an `@Pointcut` expression. The `if()` must not contain any body. The annotated `@Pointcut` method must then be of the form `public static boolean` and can use formal bindings as usual. Extra implicit arguments of type JoinPoint, JoinPoint.StaticPart and JoinPoint.EnclosingStaticPart can also be used (this is not permitted for regular annotated pointcuts not using the `if()` form).

The special forms `if(true)` and `if(false)` can be used in a more general way and don't imply that the pointcut method must have a body. You can thus write `@Before("somePoincut() && if(false)")` .

### Advice

In this section we first discuss the use of annotations for simple advice declarations. Then we show how `thisJoinPoint` and its siblings are handled in the body of advice and discuss the treatment of `proceed` in around advice.

Using the annotation style, an advice declaration is written as a regular Java method with one of the `Before, After, AfterReturning, AfterThrowing,` or `Around` annotations. Except in the case of around advice, the method should return void. The method should be declared public.

A method that has an advice annotation is treated exactly as an advice declaration by AspectJ's weaver. This includes the join points that arise when the advice is executed (an adviceexecution join point, not a method execution join point).

The following example shows a simple before advice declaration in both styles:

         @Before("call(* org.aspectprogrammer..*(..)) && this(Foo)")
         public void callFromFoo() {
           System.out.println("Call from Foo");
         }

is equivalent to...

         before() : call(* org.aspectprogrammer..*(..)) && this(Foo) {
           System.out.println("Call from Foo");
         }

If the advice body needs to know which particular `Foo` instance is making the call, just add a parameter to the advice declaration.

         before(Foo foo) : call(* org.aspectprogrammer..*(..)) && this(foo) {
           System.out.println("Call from Foo: " + foo);
         }

can be written as:

         @Before("call(* org.aspectprogrammer..*(..)) && this(foo)")
         public void callFromFoo(Foo foo) {
           System.out.println("Call from Foo: " + foo);
         }

If the advice body needs access to `thisJoinPoint` , `thisJoinPointStaticPart` , `thisEnclosingJoinPointStaticPart` then these need to be declared as additional method parameters when using the annotation style.

         @Before("call(* org.aspectprogrammer..*(..)) && this(foo)")
         public void callFromFoo(JoinPoint thisJoinPoint, Foo foo) {
           System.out.println("Call from Foo: " + foo + " at "
                              + thisJoinPoint);
         }

is equivalent to...

         before(Foo foo) : call(* org.aspectprogrammer..*(..)) && this(foo) {
           System.out.println("Call from Foo: " + foo + " at "
                              + thisJoinPoint);
         }

Advice that needs all three variables would be declared:

         @Before("call(* org.aspectprogrammer..*(..)) && this(Foo)")
         public void callFromFoo(JoinPoint thisJoinPoint,
                                 JoinPoint.StaticPart thisJoinPointStaticPart,
                                 JoinPoint.EnclosingStaticPart thisEnclosingJoinPointStaticPart) {
             // ...
         }

`JoinPoint.EnclosingStaticPart` is a new (empty) sub-interface of `JoinPoint.StaticPart` which allows the AspectJ weaver to distinguish based on type which of `thisJoinPointStaticPart` and `thisEnclosingJoinPointStaticPart` should be passed in a given parameter position.

`After` advice declarations take exactly the same form as `Before` , as do the forms of `AfterReturning` and `AfterThrowing` that do not expose the return type or thrown exception respectively.

To expose a return value with after returning advice simply declare the returning parameter as a parameter in the method body and bind it with the "returning" attribute:

          @AfterReturning("criticalOperation()")
          public void phew() {
            System.out.println("phew");
          }

          @AfterReturning(pointcut="call(Foo+.new(..))",returning="f")
          public void itsAFoo(Foo f) {
            System.out.println("It's a Foo: " + f);
          }

is equivalent to...

          after() returning : criticalOperation() {
            System.out.println("phew");
          }

          after() returning(Foo f) : call(Foo+.new(..)) {
            System.out.println("It's a Foo: " + f);
          }

(Note the use of the "pointcut=" prefix in front of the pointcut expression in the returning case).

After throwing advice works in a similar fashion, using the `throwing` attribute when needing to expose a thrown exception.

For around advice, we have to tackle the problem of `proceed` . One of the design goals for the annotation style is that a large class of AspectJ applications should be compilable with a standard Java 5 compiler. A straight call to `proceed` inside a method body:

         @Around("call(* org.aspectprogrammer..*(..))")
         public Object doNothing() {
           return proceed(); // CE on this line
         }

will result in a "No such method" compilation error. For this reason AspectJ 5 defines a new sub-interface of `JoinPoint` , `ProceedingJoinPoint` .

         public interface ProceedingJoinPoint extends JoinPoint {
           public Object proceed(Object[] args);
         }

The around advice given above can now be written as:

         @Around("call(* org.aspectprogrammer..*(..))")
         public Object doNothing(ProceedingJoinPoint thisJoinPoint) {
           return thisJoinPoint.proceed();
         }

Here's an example that uses parameters for the proceed call:

         @Aspect
         public class ProceedAspect {

           @Pointcut("call(* setAge(..)) && args(i)")
           void setAge(int i) {}

           @Around("setAge(i)")
           public Object twiceAsOld(ProceedingJoinPoint thisJoinPoint, int i) {
             return thisJoinPoint.proceed(new Object[]{i*2}); //using Java 5 autoboxing
           }

         }

is equivalent to:

         public aspect ProceedAspect {
           pointcut setAge(int i): call(* setAge(..)) && args(i);

           Object around(int i): setAge(i) {
             return proceed(i*2);
           }
         }

Note that the ProceedingJoinPoint does not need to be passed to the proceed(..) arguments.

In code style, the proceed method has the same signature as the advice, any reordering of actual arguments to the joinpoint that is done in the advice signature must be respected. Annotation style is different. The proceed(..) call takes, in this order:

- If 'this()' was used in the pointcut for binding, it must be passed first in proceed(..).
- If 'target()' was used in the pointcut for binding, it must be passed next in proceed(..) - it will be the first argument to proceed(..) if this() was not used for binding.
- Finally come all the arguments expected at the join point, in the order they are supplied at the join point. Effectively the advice signature is ignored - it doesn't matter if a subset of arguments were bound or the ordering was changed in the advice signature, the proceed(..) calls takes all of them in the right order for the join point.

Since proceed(..) in this case takes an Object array, AspectJ cannot do as much compile time checking as it can for code style. If the rules above aren't obeyed then it will unfortunately manifest as a runtime error.

Prev | Up | Next
Aspect Declarations | Home | Inter-type Declarations