This tutorial does not explain AOP, so if your new to the idea of AOP then please check out JavaWorld's series of articles to get you started.
What this tutorial will do is to try to walk you through a simple example on how you can write, define and weave in an aspect into your application.
Download the latest release and unzip it into the relevant location. This tutorial is based on 0.10.
The latest distribution can be found here.
After installation you need to set the
ASPECTWERKZ_HOME environment variable to point to the installation directory. This is because quite a few of the scripts use this to find the required libraries. How this variable is set depends on you OS. Since I'm using Linux I've amended my
.bashrc file, windows users could do this by using the control panel.
The Test Application
Now we've installed aspectwerkz, we need a test application into which to weave our aspects. As is the tradition, I'm going to use the standard HelloWorld application.
This is simply a standard Java application, and can be compiled with
javac -d target HelloWorld.java
Writing the Aspect
Next we need to develop the aspect which will contain the code to be weaved into our HelloWorld class. In this example I'm going to output a statement before and after the greet method is called.
Notice the signature of the aspect methods. They need to take this
JoinPoint argument otherwise the AspectWerkz weaver won't be able to identify the method when the aspect is weaved in, (and can leave you scratching your head as to why the weaving isn't working!).
To compile this aspect class you'll need to include the
aspectwerkz-0.10.jar in the classpath, i.e.
javac -d target -classpath $ASPECTWERKZ_HOME/lib/aspectwerkz-0.10.jar MyAspect.java
Defining the Aspect
At this point we have the test application and the actual aspect code, but we still need to tell AspectWerkz where to insert the aspect methods (pointcuts), and which aspect method to actual insert (advice).
Specifying pointcuts and advice can be done using either of (or a mixture of), the following methods.
Using an XML definition file
The XML definition file is just that, an XML file which specifies the pointcuts and advice using XML syntax. Here's one that will weave our MyAspect class into our HelloWorld program (
Most of this should be pretty straight forward, the main part being the aspect tag. Whilst I'm not going to explain every bit of this definition file, (I'll leave that up to the official documentation), I will explain a few important points.
When specifying the
pointcut the name can be any label you like, it's only used to bind the
advice. The expression should be any valid expression occording to the Join point selection pattern language however you MUST make sure that the full package+class name is included in the pattern. If this isn't done, or if the pattern is slightly wrong, AspectWerkz won't be able to correctly identify the greet method.
advice tag, the
name attribute should be the name of the method in the aspect class, (specified in the
aspect tag), which you wish to insert at the specific joinpoint. Type is set to
around, depending on where exactly you wish to inser the method in relation to the joinpoint.
bind-to specifies the name of the
pointcut to which this
advice will be bound.
This example identifies the
HelloWorld.greet() method and assigns it the pointcut label
greetMethod. It then inserts the
MyAspect.beforeGreeting method just before
greet is called, and
MyAspect.afterGreeting just after the
greet method returns.
Annotations provide a way to add metadata to the actual aspect class, rather than specifying it in a seperate definition file. Aspect annotations are defined using JavaDoc style comments a complete list of which is available here. Using annotations, our aspect class would look as follows:
After adding annotations you need to run a special AspectWerkz tool. This is done after compiling your aspect class files, (i.e. after running
javac). The tool, known as the
AspectC compiler, can be invoked as follows, passing in the source directory (
.), and the class directory (
java -cp $ASPECTWERKZ_HOME/lib/aspectwerkz-0.10.jar:$ASPECTWERKZ_HOME/lib/bcel.jar org.codehaus.aspectwerkz.definition.AspectC . target
More information on the
AspectC compiler can be found here.
Although using annotations means you don't have to write all aspect details in XML, you do still have to create a tiny XML 'stub' which tells the AspectWerkz runtime system which Java classes it should load and treat as aspects. An example of this is show below:
Weaving in and running the Aspect
There are basically two ways to actually weave the code together, one called online weaving performs the weaving as the classes are loaded into the JVM. The other is offline weaving, and is done before the code is actually run.
Using online weaving
When using online weaving you need to decide which JVM your going to use. This is because the hook which allows AspectWerkz to weave the classes together on the fly, is different in Sun HotSpot (where JDI/HotSwap is used), as apposed to BEA JRockit (where a PreProcessor is used). The default is setup to use Sun JDK 1.4.2, however if you want to use JRockit, simply edit the
bin/aspectwerkz file (
aspectwerkz.bat on windows), locate the "Sample Usage for JRockit" line and uncomment the command. Of course, remember to comment out the existing Java command above it.
Using JRockit is the preferred choice since it will not only perform much better (no needed to run in debug mode, which using HotSwap requires) and be more stable, but will also work on JDK 1.3, 1.4 and 1.5.
Performing the weaving is then just a matter of using the
aspectwerkz command line tool to run
java with the relevant classes, pointing it to the definition file, (even if using annotations you still need the 'stub' definition file), i.e.
$ASPECTWERKZ_HOME/bin/aspectwerkz -Daspectwerkz.definition.file=TestAspect.xml -cp target testAOP.HelloWorld
This produces the expected output:
Using offline weaving
With offline weaving, the test applications classes are modified on the disk with the aspect calls. That is to say offline weaving amends your actual class definition, (as opposed to online weaving which doesn't modify any classes). To perform offline weaving, you use the
aspectwerkz command line tool with the
-offline option, as follows:
$ASPECTWERKZ_HOME/bin/aspectwerkz -offline TestAspect.xml -cp target target
The last option on the command (
target) tells AspectWerkz where your classfiles are and is very important that you type in correctly, else nothing will get weaved into your target classes and you will wonder why nothing is happening.
Running the aspect is then just a matter of invoking your main class, although you still need some of the AspectWerkz jar's on your classpath, and you still need to provide an XML definition file:
java -cp $ASPECTWERKZ_HOME/lib/aspectwerkz-0.10.RC2.jar:$ASPECTWERKZ_HOME/lib/bcel.jar:target -Daspectwerkz.definition.file=TestAspect.xml testAOP.HelloWorld
This produces the expected output: