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. The method body should be empty and there should be no throws clause.

A simple example:

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

         is equivalent to...

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

An example with modifiers:

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

         is equivalent to...

         protected abstract pointcut anyCall();

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 to 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() {}

         }

The `value` attribute of the `Pointcut` declaration may contain any valid AspectJ pointcut declaration.

### 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), and the restriction that advice cannot be invoked explicitly (the weaver will issue an error if an advice method is explicitly invoked).

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

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

         is equivalent to...

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

Notice one slight difference between the two advice declarations: in the annotation style, the advice has a name, "callFromFoo". Even though advice cannot be invoked explicitly, this name is useful in join point matching when advising advice execution. For this reason, and to preserve exact semantic equivalence between the two styles, we also support the `org.aspectj.lang.annotation.AdviceName` annotation. The exact equivalent declarations are:

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

         is equivalent to...

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

If the advice body needs to know which particular `Foo` was doing the calling, just add a parameter to the advice declaration.

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

         is equivalent to...

         @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. In AspectJ 1.5.0 we require that these parameters be declared first in the parameter list, in later releases we may relax this requirement.

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

         is equivalent to...

         @Before("call(* org.aspectprogrammer..*(..)) && this(foo)")
         public void callFromFoo(JoinPoint thisJoinPoint, Foo 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:

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

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

          can be written as...

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

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

(Note the need for the "value=" 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:

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

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

         can be written as...

         @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(i*2);
           }

         }

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