JBoss AOP 2.0.0.GA Released

JBoss AOP 2.0.0.GA has been released. It can be downloaded from here, the full release notes can be found here, and the updated documentation can be found here.

A lot of bugs have been fixed. Amongst all the new features, a few deserving special mention follow. A new weaving mode which allows before/after/throwing/finally lightweight advices has been introduced. The new weaving mode also allows more granular dynamic aop. It also integrates with the JBoss MicroContainer, which is in the core of JBoss 5, meaning that aspects are now being used in the core of JBoss 5! There is also some support for interception of access to array elements.

As usual the whole team has worked hard towards this release, but thanks to Flavia Rainone for working round the clock in the run-up to the release and to Ståle W. Pedersen for helping out a lot despite being on paternity leave. Finally, thanks to Paul Gier for helping move our build over to use Maven.

Upcoming features in the short term are a nicer way to add dynamic aop constructs, and an understanding of the OSGi classloaders in JBoss 5.

Debugging JBoss AOP Apps Tutorial - Part1

Now and then I run into users complaining they don't know how to debug JBoss AOP applications. Targetting those users, I decided to write this tutorial, that will explain you the basics on debugging JBoss AOP application to have you started right away. As we will see, it is extremely easy to debug a JBoss AOP application using an IDE as Eclipse. The tricky part is how to set up your environment and to get familiar with the JBoss AOP classes that will trigger your advices.


Debugging JBoss AOP Apps Tutorial - Part 1

In this tutorial we are going to show you how you can debug an application that uses JBoss AOP using Eclipse.

For this, you need to have your project set up in Eclipse without compilation errors.

Now, follow in these steps:

1. Open the debug drop-down menu and click on Debug... as shown in the image below:
   
   
2. On the Debug window, click the New launch configuration button:




3. Configure your test as you would if your application didn't use JBoss AOP.
   
4. On the Arguments tab, add the javaagent argument and define the system property “jboss.aop.path” as in the example:
   
-javaagent:/home/fla/Development/workspace/jboss-aop/aop/output/lib/jboss-aop-jdk50.jar
-Djboss.aop.path=/home/fla/Development/workspace/MyApp/src/resources/jboss-aop.xml

   
   
   Notice you have to fill those values with the path of the jboss-aop-jdk50.jar and the jboss-aop.xml in your system.
   

Now you are ready to go. Just add the breakpoints to the points you want to debug and start the debugging.

In the next part of this tutorial, we are going to explain the JBoss AOP classes you will run into when debugging and what you need to know about them in order to debug your application and your aspects successfully. Stay tuned!

JustJava and JBoss Brasil

Hello everyone!

I have great news from Brazil. First, I'm going to do two talks at JustJava, the largest Brazilian Java event.
The title of the first talk is "Dynamic Aspect-Oriented Programing and Adaptable Systems", and it will be held tomorrow at 16:00h. The second one will take place on Friday, 12th and has the title "Designing a JavaEE Server with IoC and AOP - A Study Case".
If you are attending to JustJava this year, go check out my presentations and let me know what you think of those subjects.

The second news is that Edgar Silva has founded a Brazilian JBUG, the JBoss Brasil. I've added an internal group dedicated to JBoss AOP project exclusively. I you are Brazilian or at least speaks Portuguese, feel free to join our group. For those that don't speak Portuguese, you are always welcome to join our forums and feel free to contact us in case you want to get involved in JBoss AOP project.

See you around!

DZone Introduction to AOP article

I have written an introductory article to JBoss AOP on DZone. It can be found here.

TDC 2008

The Developers Conference or TDC is a Brazilian conference about Java and Agile Development Methods that will take place in Sao Paulo. The event lasts two days and will start tomorrow.
If you are going to attend to this conference, it would be great to chat about the JBoss technologies. I will be there on Saturday, and will do a mini-presentation about JBoss AS 5 at the Red Hat stand (the time of the presentation is to be defined and will be informed at the RH stand).
See you there!

Dynamic AOP Tutorial - Part 2

In this second part of the dynamic AOP tutorial, we will show how you can perform dynamic AOP through our API. This is currently the only available way of using dynamic AOP in standalone applications.

The JBoss AOP API


Aspects, Interceptors and Advices

All aspects, advices, and interceptors are represented by factories. Notice that, internally, JBoss AOP does not differentiate advices from interceptors. They are both represented as interceptor instances, which results in uniform, transparent handling of interceptors and advices. This way, an interceptor chain is used for intercepting a joinpoint every time it is executed, and may contain even typed advices.
For that, JBoss AOP provides a factory capable of transforming advices into interceptors, the AdviceFactory.
Take a look at the main classes used to represent those elements, all located in the org.jboss.aop.advice package:

• AspectFactory: responsible for creating an instance of an aspect. While you can provide your own implementation of this interface, the most commonly used implementation is the GenericAspectFactory, that creates aspect instances given the class of the aspect to be created.
• AspectDefinition: this is how aspect factories are managed internally. Whenever you declare an aspect, JBoss AOP creates an AspectDefinition. This definition contains the aspect factory, the aspect scope, and the aspect name.
• InterceptorFactory: responsible for creating instances of interceptors. To represent a simple interceptor, the GenericInterceptorFactory is used; the AdviceFactory represents advices.

The next example illustrates how you use those classes to represent an advice:
// aspect class
public class MyAspect
{
  public void helloWorld()
  {
    System.out.println(“Hello world!”);
  }

  public Object helloWorld2(Invocation invocation) throws Throwable
  {
    System.out.println(“Hello world!”);
    return invocation.invokeNext();
  }
}
-----
  public static void main(String [] args)
  {
    AspectFactory aspectFactory = new GenericAspectFactory(MyAspect.class, null);
    AspectDefinition aspectDefinition = new AspectDefinition(“myAspect”, Scope.PER_INSTANCE, aspectFactory);
    AdviceFactory adviceFactory = new AdviceFactory(aspectDefinition, “helloWorld”, AdviceType.BEFORE);
    ...
  }

In the first part of the example, we declare the MyAspect class, with two advices: helloWorld and helloWorld2. In the second part, we represent the aspect MyAspect and the advice helloWorld using the classes we have just learned. First, an aspect factory is created. The constructor of GenericAspectFactory must receive the class of the aspect, and an xml element. This second parameter allows to pass extra configuration to the aspect class. Since we are not loading anything from an xml file, the second parameter must be null.
Next, we create an aspect definition with the factory, defining also the name of our aspect (could be any unique name you wanted), and the scope of the aspect. Finally, we create an advice factory. This factory's constructor receives the aspect definition, the name of the advice, and the type of the advice. A second constructor is also provided. If you are declaring around advices, you can omit the advice type, as follows:
// declare the helloWorld2 advice as being of the default advice type, which is around
new AdviceFactory(aspectDefinition, “helloWorld2”);
Naturally, creating those elements is not enough, you must deploy them through our API. We will see how to do this in the next topics.

Binding Aspects to Pointcuts

Advices and interceptors are useless unless they are bound to a pointcut expression, indicating when they should be called. This takes us to the most important class of the dynamic AOP API, the org.jboss.aop.advice.AdviceBinding. This class contains a pointcut expression and a series of interceptor factories. Optionally, it can also contain a cflow expression.
It provides one constructor for dynamic AOP operations:
AdviceBinding(String pointcutExpression, String cflow)

Designed specially for dynamic AOP operations, this constructor creates a binding, defining the pointcut expression and the cflow expression you intend to use. If there is no cflow expression, the second parameter should be null. While there is a second constructor provided by AdviceBinding. It is for internal use only, so always use the one above.

The following methods add advices and interceptors to a binding:

• addInterceptor(Class clazz)
  Adds an interceptor to the binding. Always use this method when you are binding interceptors.
• addInterceptorFactory(InterceptorFactory interceptorFactory)
  Adds an interceptor factory to the binding. You must use it to add advices, in the form of AdviceFactory instances (as we have seen above, this class is an implementation of InterceptorFactory, and creates interceptor adapters to call your advice).
  

AspectManager

Most of the functionalities provided by JBoss AOP have an common entry point: the org.jboss.aop.AspectManager class. This class is our facade and provides all sort of AOP functionalities. Among them, you can find the dynamic AOP methods:

• addAspectDefinition(AspectDefinition definition): deploys an aspect
• addAdviceBinding(AdviceBinding binding): deploys a binding
• removeAdviceBinding(String bindingName): removes a binding
• removeAdviceBindings(Collection bindings): removes a collection of bindings.
  

Advisor and InstanceAdvisor

Every weaved class implements the org.jboss.aop.Advised interface. Through this interface, you can access the class Advisor, a sort of AspectManager with scope limited to that single class, and the InstanceAdvisor, with an even more specific scope, a single instance.
Take a look at the methods you can call on the Advised interface:

• Advisor _getAdvisor()
• InstanceAdvisor _getInstanceAdvisor()
  

The InstanceAdvisor class provides dynamic AOP operations that affect only the instance it advises. Its main methods are:

• insertInterceptor(Interceptor)
  Inserts an interceptor in the beginning of all interceptor chains associated with the advised instance.
• appendInterceptor(Interceptor)
Adds the interceptor to the end of the instance's chains
• removeInterceptor(String)
Removes an interceptor that has been inserted or appended. The parameter specifies the name of the interceptor to be removed.
  

Putting it all together

Take a look at the following example:


AdviceBinding binding = new AdviceBinding(“execution(public !static void Pojo->*(int, long))”, null);
binding.addInterceptor(MyInterceptor.class);
AspectManager.getInstance().addAdviceBinding(binding);

This example adds a binding dynamically. It is the API equivalent of the xml binding below:

<aop>
  <binding pointcut="execution(public !static void Pojo->*(int, long))">
    <interceptor class="MyInterceptor.class/"/>
  </binding>
</aop>
Now, an example with advices:

// declares the aspect class
AspectFactory aspectFactory = new GenericAspectFactory(MyAspect.class, null);
AspectDefinition aspectDefinition = new AspectDefinition(“myAspect”, Scope.PER_INSTANCE, aspectFactory);
AspectManager manager = AspectManager.instance();
// deploys the aspect
manager.addAspectDefinition(aspectDefinition);
// creates the advice factory
AdviceFactory adviceFactory = new AdviceFactory(aspectDefinition, “helloWorld”, AdviceType.BEFORE);
// creates the binding
AdviceBinding binding = new AdviceBinding(“execution(public !static void Pojo->*(int, long))”, null);
binding.addInterceptorFactory(adviceFactory);
// adds the binding
manager.addAdviceBinding(binding);

The example above declares and deploys an aspect, then creates an advice factory to represent an advice of this aspect. This advice factory is added to a new advice binding, that is registered at AspectManager by a call to AspectManager.addAdviceBinding method. It is the API counterpart of the xml below:
<aop>
  <aspect name="”myAspect”" class="”MyAspect”/">
  <binding pointcut="”execution(public !static void Pojo->*(int, long))”>
    <before aspect="”myAspect”" name="”helloWorld”/">
  </binding>
</aop>
To remove the advice binding, you can call the removeAdviceBinding method:
manager.removeAdviceBinding(binding.getName());

Notice that the AdviceBinding.addInterceptor and AdviceBinding.addInterceptorFactory methods can be called only before you deploy your binding. Doing so after that will cause inconsistencies.

Our last example adds an interceptor to a single instance of the class Pojo:
// create Pojo
Pojo pojo = new Pojo();
// retrieve its instance advisor
InstanceAdvisor instanceAdvisor = ((Advised) pojo)._getInstanceAdvisor();
// append an interceptor to the chains of this instance only
instanceAdvisor.append(new MyInterceptor());
// executing someMethod will trigger MyInterceptor
pojo.someMethod();

If you create another instance of Pojo, this instance will not be intercepted by MyInterceptor, as the interceptor has been added to the InstanceAdvisor of pojo:
Pojo otherPojo = new Pojo();
pojo.someMethod(); // will not be intercepted by MyInterceptor

Wrapping up

This second part of the tutorial showed the main classes involved in the dynamic AOP API. To add an aspect at runtime you have to

1. declare the aspect, by adding an AspectDefinition to AspectManager
2. create a binding, with the pointcut expression of your choice, and add interceptor factories to it
3. add the binding to AspectManager (it is at this point that the binding will be deployed to your system)
   

You have two options to add interceptors:

• create an AdviceBinding containing interceptors and add it to AspectManager as above
• use the InstanceAdvisor API
  

Next Steps

-> Take a look at our dynamic AOP example. It is available as part of our releases. Run the example and play with it:

• add advices to the advice binding, instead of interceptors;
• create an advice binding that contains interceptors and advices mixed.
  

-> Check the JBoss AOP Javadoc to learn more about all methods provided by the InstanceAdvisor class. Edit the dynamic AOP example, this time using the InstanceAdvisor methods you learned. Try removing an interceptor at runtime.
-> Get engaged! Help us design a state of the art dynamic AOP API, which will be part of a future release:
http://www.jboss.com/index.html?module=bb&op=viewtopic&p=4166298#4166298

Dynamic AOP Tutorial - Part 1

The goal of this tutorial is to show how to use dynamic AOP with JBoss AOP. Notice that, by dynamic AOP, we mean the dynamic weaving of aspects, and not dynamic pointcut expressions (such as cflow), as other tools refer to them using the same term.

There are two ways of using dynamic AOP with JBoss AOP: hot deployment (when running your application in AS); or through our API.

In the next topics, we will show what are the prerequisites for dynamic AOP, and how to use hot deployment of aspects at the server. In the second part of our tutorial, we will see how to use our API to perform dynamic operations.

What is Dynamic AOP?

Dynamic AOP or dynamic weaving consists of adding/removing aspects to/from your system at runtime, without need for recompilation or rebooting.

In practice, this means that you can enable and disable aspects at runtime, including aspects previously unknown to your system. There are several scenarios where this functionality comes in handy. For example, to debug failures that show up only after your application has been running for a long time. In a situation like this, a lot of time could be saved as dynamic AOP will not require the system to be rebooted in order to attach an aspect to debug your application. Furthermore, dynamic AOP allows the runtime addition of extensions to a system that cannot be rebooted frequently. Another example of applicability is to fix an aspect that contains a bug, or that needs to have its functionality extended at runtime.

JBoss AOP supports dynamic AOP by rebuilding interceptor chains associated with a joinpoint when aspects are added and/or removed. If hot swap is enabled, JBoss AOP also instruments the code at runtime to insert/remove invocations to these chains whenever appropriate. Otherwise, the calls to chains are inserted during compilation or class loading (depending on whether you are using compile time or load time weaving).

Preparing your Application for Dynamic AOP

In order to perform dynamic AOP operations, JBoss AOP must know beforehand which joinpoints need to be instrumented, so that the invocations to interceptor chains are added to the code before it gets executed.
This restriction applies even with hot swap enabled. Due to security constraints of the JVM, the list of methods, constructors, and fields of a class cannot change at runtime. Nor can their signatures. For weaving, JBoss AOP inserts auxiliary fields and methods into your class bytecodes. Given the JVM constraints, this step must be performed before your code gets executed and, hence, the joinpoints to be instrumented must be known at the first weaving stage (compile time or loadtime weaving).

To indicate which joinpoints must be instrumented for dynamic AOP, you must use prepare expressions. A prepare expression can be declared either in an xml file or as an annotation. Look at the example below:

<aop>
  <prepare expr="all(Pojo)"/>
</aop>

This is the content of a jboss-aop.xml file. This file contains a single declaration of a prepare expression, but it could contain as many as you wish. Naturally, it could contain as well tags for non-dynamic AOP purposes, such as pointcuts, bindings, introductions, etc.

Prepare expressions can also be declared in the form of annotations:

@Aspect(scope = Scope.PER_VM)
public class MyAspect
{
  @Prepare ("all(Pojo)")
  public static Pointcut preparePOJO;

  @PointcutDef("execution(Pojo->new())")
  public static Pointcut aPointcut;
}

Notice above the similarity in the syntax of the declaration of a prepare expression, with the @Prepare annotation, and of a pointcut expression, with the @PointcutDef expression. Except for the annotation used, their syntax is the same.

The annotation @Prepare can also be used to annotate plain-old Java classes:

@Prepare
public class Pojo
{
  ...
}

In this case, it indicates that the method execution and field access joinpoints contained in Pojo class must be prepared for runtime weaving of aspects.

Joinpoints matched by plain pointcut expressions can also be the target of dynamic AOP operations. JBoss AOP treats joinpoints matched by pointcuts and joinpoints matched by prepare expression in a very similar way.

The main difference between the two types of expressions lies in their semantic meaning. When you run across a prepare expression, you immediately know that it is being declared for dynamic AOP purposes. On the other hand, if you see a pointcut expression you expect it to be used in one or more bindings. For readability, always prefer to use prepare expressions over plain pointcuts to indicate dynamic AOP usage.

In addition, JBoss AOP does not affect the control flow of joinpoints matched by prepare expressions when using hot swap. The control flow of those joinpoints will be affected only after a dynamic aspect addition is performed, which means you will have a better performance when prepare expressions are used appropriately.

Hot Deployment of Aspects

Hot deployment is the most straightforward way of using dynamic AOP with JBoss AOP, and is available for JBoss AS.

In JBoss AS, all deployment units, such as ears, wars, jars, can be hot deployed. JBoss AS will automatically load the applications added to the deploy folder, and unload them when their units are removed from the deploy folder.

The JBoss AOP deployment units have the .aop suffix. By deploying such an unit at runtime, the aspects contained in it will be automatically deployed to all prepared joinpoints of the previously deployed applications. If you are running the server with load time weaving, all the applications deployed after this moment will also be instrumented by JBoss AOP to insert the aspects contained in the deployment unit, according to the bindings and pointcuts it contains.
Similarly, when a .aop file is removed from the deploy dir, the bindings it contains will be automatically removed from the running applications.

As an alternative to using .aop units, you can use other deployment units and xml files to hot deploy aspects to the server. In this case, the aspect classes are bundled into a non-aop deployment unit (such as a .jar or an .ear) and deployed to the server. The binding declarations are deployed to the server separately in an xml file whose name must end with -aop.xml. The effect of this two-part deployment is the same as you get by deploying an .aop file, but with one advantage. This type of deployment allows you to redeploy only the *-aop.xml file, without causing the aspect classes to be reloaded. The simple removal of your *-aop.xml file will cause the bindings to be undeployed. And the addition of a new *-aop.xml file will cause the bindings declared in it to be deployed to the server.

Wrapping up

In a nutshell, we have seen that:

• only joinpoints matched by prepare and pointcut expressions during compile/load time weaving can be the target of dynamic operations.


• to use dynamic aop in the AS, you can deploy and undeploy .aop files.


• an alternative is to deploy xml files ending in -aop.xml, containing the declarations of bindings and pointcut expressions.

Next Steps

Take a look at the injboss example, available as part of the JBoss AOP documentation. It shows the different ways of packaging aspectized applications to be run in JBoss AS. Try running those examples and playing with dynamic AOP to see it in action! (For example, run $ ant deploy-basic-lt-war and try removing the jboss-aop.xml file from your server deploy dir in order to have the aspects undeployed)

In the next part of the tutorial, we will show how to use the JBoss AOP API to perform dynamic AOP operations. Stay tuned!