JBoss.org Community Documentation

4.1. Around Advices

An around advice can follow this template:

public Object [advice name]([Invocation] invocation) throws Throwable
{
   try{
      // do something before joinpoint execution
      ...
      // execute the joinpoint and get its return value
      Object returnValue = invocation.invokeNext();
      // do something after joinpoint has executed successfully ...
      // return a value
      return returnValue;
   }
   catch(Exception e)
   {
      //handle any exceptions arising from calling the joinpoint
      throw e;
   }
   finally
   {
      //Take some action once the joinpoint has completed successfully or not
   }
}

In the template above, Invocation refers to one of the Invocation beans, and can be the class org.jboss.aop.joinpoint.Invocation or one of its subtypes.

Since an around advice wraps a joinpoint, it must proceed execution to the joinpoint itself during its execution. This can be done by calling the method invokeNext() on invocation. This method will proceed execution to the next around advice of that joinpoint. At the end of this chain this invokeNext() will proceed to the joinpoint itself. The value returned by the around advice will replace the joinpoint return value in the base system.

For example, in the case where there are two around advices bound to a joinpoint, the first around advice will trigger the second around advice by calling invokeNext(). The second advice will trigger the joinpoint execution by calling the same method. As a result of the invokeNext() execution, the second advice will receive the joinpoint return value. The value returned by this second advice will be received as a result by the first around advice. Finally, the value returned by this advice will replace the joinpoint return value in the base system execution. Normally though, around advices will simply return whatever value the joinpoint returned! This is shown in the preceding template example.

If an around advice wants to completely replace the joinpoint execution, it can skip the call to invokeNext(). This will also skip execution of any subsequent around advices in the chain. As a third alternative, the around advice can call the method invokeTarget() instead of invokeNext(). This method will invoke the target joinpoint directly, skipping any subsequent advices.

The presence of the Invocation parameter is optional. If an around advice does not have this parameter, it can replace the call to invokeNext() with a call to org.jboss.aop.joinpoint.CurrentInvocation.proceed().

The signature described before is the default around advice signature rule. In addition to it, the around advice signature can also be of this form (only in generated advisor mode):

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

This signature is joinpoint dependent. The return type of the advice must be a type assignable to the the return type of the joinpoint to be intercepted (i.e. be the same type; a subclass, if the return type is class; or a subinterface or an implementing class, if the return type is an interface). In case the joinpoint being intercepted does not have a return type, this advice return type must be void.

An around advice can have zero or more annotated parameters. The annotated parameters will be covered in detail in Section 4.3, “Annotated Advice Parameters”.

Finally, JBoss AOP also features a special type of around advice: Interceptor. An interceptor class implements org.jboss.aop.Interceptor, and is described in Section 2.4, “Interceptors”.