A before advice is executed before the joinpoint. The signature for a before advice must be of this form:

public void [advice name]([annotated parameter], [annotated parameter],...[annotated parameter])

Since an after advice is executed after a joinpoint, it can return a value to replace the joinpoint return value in the base system. So, they can follow one of these signatures:

public void [advice name]([annotated parameter], [annotated parameter],...[annotated parameter])

public [return type] [advice name]([annotated parameter], [annotated parameter],...[annotated parameter])

In the first signature, the after advice does not overwrite the joinpoint return value. On the other hand, when using the second signature, the after advice return value will replace the joinpoint return value. As with around advices, this return type must be assignable to the joinpoint return type.

The fourth type of advice provided by JBoss AOP is the after-throwing type. This advice is invoked only after the execution of a joinpoint that has thrown a java.lang.Throwable or one of its subtypes.

The signature of such an advice is the same as the one for before advices:

public void [advice name]([annotated parameter], [annotated parameter],...[annotated parameter])

Different from the other advice types, an after-throwing advice has a mandatory annotated parameter. This parameter is the exception thrown by the joinpoint execution, as we will see in the next subsection.

Lastly, JBoss AOP provides the finally advice type. It is invoked from inside a finally block, after the joinpoint execution.

This advice is the only one that is called after a joinpoint execution in a deterministic way. Calls to after and after-throwing advices take place depending on the joinpoint execution outcome. After advices are not called when the joinpoint execution terminates abruptly with an exception. After-throwing ones, on the other hand, are not called when the joinpoint execution returns normally, since no exception is thrown this time. So, if an advice needs to be run no matter what is the outcome of the joinpoint, it should be a finally advice.

Pretty much as after advices, finally advices can follow one of the signatures below:

public void [advice name]([annotated parameter], [annotated parameter],...[annotated parameter])

public [return type] [advice name]([annotated parameter], [annotated parameter],...[annotated parameter])

The last signature shows that finally advices can also overwrite the joinpoint execution return value by returning a value themselves. But notice that this return value will not be received by the base system if an exception has been thrown. However, it is easy to know whether this condition is met, by making use of annotated parameters.

As shown in Table 4.1, “Annotated Parameters Table”, the presence of a @Thrown annotated parameter can be mandatory depending on the advice type and its parameters.

This annotation is available only for after-throwing and finally advices. For after-throwing advices this parameter is always mandatory:

public class Aspect
{
   public void throwing1(@Thrown RuntimeException thrownException)
   {
      ...
   }

   public void throwing2()
   {
      ...
   }
}


<aop>
   <aspect class="Aspect"/>
   <bind pointcut="...">
      <throwing aspect="Aspect" name="throwing1"/>
      <throwing aspect="Aspect" name="throwing2"/>
   </bind>
</aop>

The advice throwing1 follows this rule; advice throwing2, on the other hand, is invalid, because it does not contain the mandatory @Thrown annotated parameter.

For finally advices, the @Thrown annotation is compulsory only if a @Return annotated parameter is present. This way, a finally advice can identify whether the return value is valid or not. If the @Thrown parameter is null, it means that the joinpoint returned normally and that the value contained in the @Return annotated-parameter is valid. Otherwise, the value contained in @Return annotated parameter must be ignored (it will be null if the return type is not primitive, 0 if it is a primitive number or false if it is boolean). If the finally advice does not receive the joinpoint return value, the use of the @Thrown annotated parameter is optional and, as expected, its value will be null if the joinpoint being intercepted did not throw an exception. Take a look at the next example:

public class Aspect
{
   public void finally1(@Thrown Throwable thrownException)
   {
      ...
   }

   public void finally2()
   {
      ...
   }

   public void finally3(@Return int returnedValue, @Thrown Throwable thrownException)
   {
      if (thrownException == null)

      {

         //We returned normally, the @Return parameter is valid

         int i = returnedValue;

      }

      else

      {

         //An exception happened while invoking the target joinpoint

         //The return value is invalid

      }

    }

   public void finally4(@Return int returnedValue)
   {
      ...
   }

}


<aop>
   <aspect class="Aspect"/>
   <bind pointcut="execution(public int *->*(..))">
      <finally aspect="Aspect" name="finally1"/>
      <finally aspect="Aspect" name="finally2"/>

      <finally aspect="Aspect" name="finally3"/>

      <finally aspect="Aspect" name="finally4"/>

   </bind>
</aop>

This example binds four finally advices to the execution of all public methods that return an int value. Take note on the type of the @Thrown-annotated parameters, which must be Throwable for this type of advice.

The presence of @Thrown is not mandatory in advices finally1() and finally2(), because they do not have a @Return annotated parameter. Hence, both advices are valid. Besides, finally1() will receive a non-null exception only when the joinpoint being intercepted throws an exception.

For advice method finally3() the presence of a @Thrown annotated parameter is mandatory because this advice also has a @Return annotated parameter. If an exception happens when invoking the target joinpoint, this advice will receive a non-null @Thrown parameter, meaning that the @Return annotated parameter is invalid. If the joinpoint completes normally, the @Thrown annotated parameter will be null and the @Return annotated parameter will contain the return value of the target joinpoint.

The finally4() advice is invalid, it contains a @Return parameter, but has no @Thrown annotated parameter. Finally advices require a @Thrown parameter if a @Return annotated parameter is present.

As we saw, an advice can receive the joinpoint arguments as annotated parameters. This can be achieved with the use of two different annotations: @Arg and @Args.

There is a great difference between these two approaches, though. With @Arg, each parameter is equivalent to a single joinpoint parameter. With @Args, one single parameter, of type Object[], receives an array containing all joinpoint arguments. This last possibility is more generic than the first one, since it can be used independently of the joinpoint argument types. Plus, it allows changes to the argument values. Any changes performed on the values of this array will be perpetuated to the joinpoint execution. However, the use of @Args parameters on a join point interception means the arguments array needs creation. The same happens with the use of getArguments() and setArguments() methods on Invocation classes. So the use of @Arg annotated parameters is more lightweight, and should be used whenever there is no need to changing the joinpoint arguments.

When using @Arg annotated parameters, the types of these parameters depend on the joinpoint being intercepted. Not all the target joinpoint arguments need to be included as parameters to the advice method. An advice can receive only the argument values that are relevant to its execution.

Given all the possibilities in the usage of @Arg, JBoss AOP will match the advice parameters with the joinpoint ones, to infer to which joinpoint argument each advice parameter refers to. This matching process consists of the following steps:

To illustrate this mechanism, consider the following scenario:

public class POJO
{
    void method(Collection arg0,  List arg1, int arg2, String arg3){}
}


<aop>
   <aspect class="MyAspect"/>
   <bind pointcut="execution(* POJO->method(..))">
      <before aspect="MyAspect" name="advice"/>
   </bind>
</aop>

The example above shows a xml-declared binding. We will use examples with those to illustrate signature concepts from now on. Detailed syntax of xml bindings is shown in Chapter 5, XML Bindings.

Class POJO is a plain java old object that contains only one method. When calling this method, we want to trigger MyAspet.advice() before this method is called. POJO.method() receives four distinct arguments, all of them can be available to an advice by using @Arg annotated parameters. If MyAspect.advice() has the following signature:

public class MyAspect
{
   public void advice(@Arg Collection param0, @Arg List param1, @Arg int param2, @Arg String param3)
   {
      ...
   }
}

MyAspect.advice() parameters will be trivially matched to POJO.method() arguments as follows:

param0 <- arg0
param1 <- arg1
param2 <- arg2
param3 <- arg3
         

The matching outcome will be the same if MyAspect.advice() signature changes slightly in the following manner, since Collection is assignable from List for param2:

public class MyAspect
{
   public void advice (@Arg Collection param0, @Arg Collection param1, @Arg int param2, @Arg String param3)
   {
      ...
   }
}

If MyAspect.advice() receives only one parameter, of type java.lang.Object:

public class MyAspect
{
   public void advice(@Arg Object param0)
   {
      ...
   }
}

The parameter matching outcome will be:

param0 <- arg0
         

Since there is no joinpoint argument of type Object, we proceed to the additional matching step in this case. Because arg0 is the first unmatched argument that is assignable to Object, we assign this argument to param0.

Notice that JBoss AOP will match all parameters correctly if we invert the order of parameters:

public class MyAspect
{
   public void advice(@Arg int param2, @Arg Collection param0, @Arg String param3, @Arg List param1)
   {
      ...
   }
}

If one writes an advice whose unique parameter is a Collection, and we want to refer to the second joinpoint argument:

public class MyAspect
{
   public void advice (@Arg Collection param1)
   {
      ...
   }
}

It will not work as desired. JBoss AOP will assign arg0 to param1:

param1 <- arg0
         

In cases like this, it is possible to enforce the correct matching of joinpoint arguments and advice parameters. The annotation @Arg has an attribute, index, whose purpose is to define the index of the argument to which that parameter refers.

So, in this case, the MyAspect.advice() parameter list below:

public class MyAspect
{
   public void advice (@Arg(index=1) Collection param1)
   {
      ...
   }
}

Will have the desired matching, which is:

param1 <- arg1
         

In the example just shown in this section, MyAspect.advice() was a before advice, but the same rules are used for all advices using @Arg annotated parameters.

Let's start with the selection of advices when all of them use the annotated-parameter signature. As we will see later, very similar rules are used for selecting advices with the default signature.

The process of selection of advices that follow the annotated-parameter signature depends on the priority of each kind of parameter:

This priority is used in two different criteria:

public class POJO
{
   String someMethod(String s){}
}

<aop>
   <aspect class="OneAspect"/>
   <bind pointcut="execution(* POJO->someMethod(..))">
      <after aspect="OneAspect" name="after"/>
   </bind>
</aop>


public class OneAspect
{
   public void after(@JoinPoint MethodJoinPoint mjp){} //1
   public String after(@Target POJO pojo, @Return String ret, @Arg String arg0){} //2
}

public class POJO
{
   String someMethod(String s){}
}

<aop>
   <aspect class="OneAspect"/>
   <bind pointcut="execution(* POJO->someMethod(..))">
      <after aspect="OneAspect" name="after"/>
   </bind>
</aop>


public class OneAspect
{
   public void after(@Target POJO pojo){} //1
   public String after(@Return String ret, @Arg String arg0){} //2
}

public class POJO
{
   String someMethod(String s){}
}

<aop>
   <aspect class="OneAspect"/>
   <bind pointcut="execution(* POJO->someMethod(..))">
      <after aspect="OneAspect" name="after"/>
   </bind>
</aop>


public class OneAspect
{
   public void after(@JoinPoint MethodJoinPoint mjp, @Target POJO pojo){} //1
   public String after(@JoinPoint MethodJoinPoint mjp, @Return String ret){} //2
}

public class POJO
{
   String someMethod(String s, int i){}
}

<aop>
   <aspect class="OneAspect"/>
   <bind pointcut="execution(* POJO->someMethod(..))">
      <before aspect="OneAspect" name="before"/>
   </bind>
</aop>


public class OneAspect
{
   public void before(@Arg String s, @Arg int i){} //1
   public String before(@Arg String s){} //2
}

public interface POJOInterface{}

public class POJOSuperClass extends java.lang.Object{}

public class POJO extends POJOSuperClass implements POJOInterface
{
   void method(){}
}

<aop>
   <aspect class="OneAspect"/>
   <bind pointcut="execution(* POJO->method(..))">
      <before aspect="OneAspect" name="before"/>
   </bind>
</aop>

public class OneAspect
{
   public void before(@Target POJO target){} //1
   public void before(@Target POJOInterface target){} //2
   public void before(@Target POJOSuperClass target){} //3
   public void before(@Target Object target){} //4
}

public class POJO
{
   public void method(POJO argument0, String argument1, int argument2)
}


<aop>
   <aspect class="OneAspect"/>
   <bind pointcut="execution(* POJO->method(..))">
      <before aspect="OneAspect" name="before"/>
   </bind>
</aop>


public class OneAspect
{
   public void before(@Arg POJO p, @Arg String s, @Arg int i){} //1
   public void before(@Arg POJOSuperClass p, @Arg String s, @Arg int i){} //2
   public void before(@Arg POJO p, @Arg Object s, @Arg int i){} //3
   public void before(@Arg Object p, @Arg Object s, @Arg int i){} //4
}

public class POJO
{
   public Collection method(int arg0, boolean arg1, short arg2) {…}
}


<aop>
   <aspect class="OneAspect"/>
   <bind pointcut="execution(* POJO->method(..))">
      <advice aspect="OneAspect" name="around"/>
   </bind>
</aop>


public class OneAspect
{
   public Collection around(@JoinPoint Invocation inv, @Arg int param0) throws Throwable
   {...} //1

   public List around(@JoinPoint Invocation inv, @Arg boolean param1) throws Throwable
   {...} //2

}

<aop>
   <aspect class="OneAspect"/>
   <bind pointcut="execution(* POJO->method(..))">
      <after aspect="OneAspect" name="around"/>
   </bind>
</aop>


public class OneAspect
{
   public Collection after(@Arg int param0) {...} //1
   public List after(@Arg boolean param1) { ... } //2
   public void after(@Arg short param2) { ... }   //3
}

public class POJO
{
   public void method(int arg0, long arg1) {…}
}


<aop>
   <aspect class="OneAspect"/>
   <bind pointcut="execution(* POJO->method(..))">
      <before aspect="OneAspect" name="before"/>
   </bind>
</aop>


public class OneAspect
{
   public void advice(@Arg int arg0) {}
   public void advice(@Arg long arg1) {}
}

For the default around advice signature (i.e., without annotated parameters), there is only one parameter to analyze, the invocation. So, the priority rules are very simple:

Lets revisit the example given in the beginning of this section, in augmented version:

class POJO
{
   public int field;
   public POJO(){}
   public someMethod(){}
}


public class OneAspect
{
   public Object trace(MethodInvocation invocation) throws Throwable {...} //1
   public Object trace(ConstructorInvocation invocation) throws Throwable {...} //2
   public Object trace(Invocation invocation) throws Throwable {...} //3
   public Object trace() throws Throwable {...} //4
}


<aop>
   <aspect class="OneAspect"/>
   <bind pointcut="all(POJO)">
      <advice aspect="OneAspect" name="trace"/>
   </bind>
</aop>

The fourth advice above will never be called, considering the presence rule. It is the only one that lacks the Invocation parameter, and would be called only if all others were considered invalid in a scenario, which won’t happen in this example. By ruling out this advice with the presence rule, all other advices are equivalent: the invocation parameter is present in all of them. So, we need to move on to the assignability degree rule to select one of them. However, the assignability degree needs to be calculated accordingly to the joinpoint being intercepted. JBoss AOP needs to evaluate each joinpoint type to be intercepted to do the correct selection for each case.

Consider the interception of the constructor of POJO. In that case, the first advice is considered invalid, becase a MethodInvocation is not assignable from the invocation type that JBoss AOP will provide, ConstrucorInvocation. We are now left with the second and third advices. The second one has assignability degree of 0 on the invocation type. The third one, assignability degree of 1 (it takes one step in the hierarchy to go fom ConstructorInvocation to Invocation). So, in this case, JBoss AOP will select the second advice, because it is the valid advice with the lower assignability degree on the invocation.

Similary, to intercept the execution of POJO.someMethod(), JBoss AOP will consider the second advice invalid, because it is supposed to receive an invocation whose type is assignable from MethodInvocation. Since the first advice has an assignability degree of 0 on the invocation, and the third one, assignability degree of 1, JBoss AOP will select the first one.

Given that Invocation will always be the super class of the expected invocation type, JBoss AOP will select this advice, whose assignability degree will always be 1, only when the other two advices are invalid. That would be the case of a field read, where the invocation type is FieldReadInvocation.

Finally, when we mix default signature methods with annotated parameter ones, an advice in one of the forms:

public Object [advice name]([Invocation] invocation) throws Throwable

public Object [advice name]([Invocation] invocation) throws Throwable

public Object [advice name]() throws Throable

Has the highest priority over all annotated-parameter advices. If there is more than one with the default signature, the criteria described in the previous section will be used to select one of them..

Notice that mixing different signatures is possible only with around advices, since only these ones can follow the default signature.