Monday, March 24, 2008

Typed Advices Tutorial - Part 1

As we get closer and closer to our 2.0.0.GA release, I found it would be interesting to post a tutorial on typed advices, one of the new features of the next GA release.

The tutorial, targeted to users already familiar with the basics of JBoss AOP, will be split into parts. The plan is to post a new part every Monday. Enjoy!

Typed Advices Tutorial - Part 1

In this part, we will see what are the new types of advices and how to declare a binding using typed advices.

5 Different Types

JBoss AOP now supports 5 types of advices:

  • before: advices of this type are executed before the joinpoint.
  • around: this is equivalent to the single advice type previously supported by JBoss AOP. Around advices work like the interceptors, wrapping the joinpoint execution. They are invoked by JBoss AOP as if they were the original joinpoint, and it is up to them to proceed execution to the joinpoint itself, through the method invokeNext() of the class Invocation.
  • after: advices of the type after are executed after the joinpoint returns normally.
  • throwing: advices of this type are invoked only after the joinpoint throws an exception. If the joinpoint returns normally, these advices will not be called.
  • finally: these advices are invoked after the joinpoint execution, regardless of the way it returns.

The before, after, throwing and finally advices are more lightweight when compared with around advices. Hence, they must be chosen whenever possible over around advices.

Binding Typed Advices

In the previous versions of JBoss AOP, the XML tag advice was the only choice to declare an advice. This tag must be inside a bind tag, like the example below:

<bind pointcut="execution(* *->(..))">
   <advice aspect="Aspect" name="myAdvice"/>

Notice that "Aspect" must have been declared before the bind tag, in an aspect tag.

To declare a typed advice, the XML would be similar to the above, except for the fact that the tag advice will be replaced by a tag with the name of the type of the advice you want to bind.

The example below binds five advices, one of each type. As you can see, the tags before, after, around, throwing, and finally have the same attributes as the tag advice.

<bind pointcut="execution(* *->(..))">
   <before aspect="Aspect" name="myBeforeAdvice"/>
   <around aspect="Aspect" name="myAdvice"/>
   <after aspect="Aspect" name="myAfterAdvice"/>
   <throwing aspect="Aspect" name="myThrowingAdvice"/>
   <finally aspect="Aspect" name="myFinallyAdvice"/>

Notice that the tag advice is also supported in the new JBoss AOP version. As this tag does not indicate the type of the advice being declared, the default type, around, will be used. This keeps compatibility with previous versions, garanteeing that no AOP code will be broken when upgrading to the new release.

To allow declaration of typed advice bindings through annotations, a new attribute has been added to the annotation @Bind:

@Bind(pointcut="execution(* *->(..))", type=AdviceType.BEFORE)

The example above shows an advice annotation that binds the annotated advice (hidden in the example) to the same pointcut we saw in the previous examples. It also specifies the type of the advice as being before. Similarly, we can declare advices of all the other four types. The annotation parameter type is optional and its default value is AdviceType.AROUND.

Notice that the class that contains the advice must be annotated with @Aspect in order to be recognized as an aspect by JBoss AOP.

An Example of Typed Advice

The following Java method is a simple example of typed advice:

public void myAdvice()
   System.out.println("Hello world!");

The signature of typed advices is pretty flexible, allowing even void advices with no parameters at all. The only type of advice that cannot have the above signature is the throwing advice. As we will see, this advice has a mandatory parameter. This means that the method above could be a before, around, after, or finally advice.

In the next part of this tutorial we will see more about the signature rules, showing how an advice can receive pretty much any joinpoint information as a parameter.

See you next week!

No comments: