Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<p>Authors:  <a href="http://www.davidmaddison.com/">David Maddison</a>, <a class="confluence-link confluence-userlink" data-username="jboner" href="/display/~jboner" data-linked-resource-id="31" data-linked-resource-type="userinfo" username="jboner" data-linked-resource-default-alias="jboner jboner" data-base-url="http://docs.codehaus.org">jboner jboner</a></p>

<h3>Introduction</h3>

<p>This tutorial does not explain AOP, so if your new to the idea of AOP then please check out <a href="http://www.javaworld.com/javaworld/jw-01-2002/jw-0118-aspect.html">JavaWorld's</a> series of articles to get you started. </p>

<p>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.   </p>

<h3>Installation</h3>

<p>Download the latest release and unzip it into the relevant location.  This tutorial is based on the 2.0 version of AspectWerkz but works equally with 1.0 final.</p>

<p>The latest distribution can be found <a href="http://aspectwerkz.codehaus.org/releases.html">here</a>.</p>

<p>After installation you need to set the <code>ASPECTWERKZ_HOME</code> 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 <code>.bashrc file</code>, windows users could do this by using the control panel.</p>

<h3>The Test Application</h3>

<p>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.</p>

<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="java" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6amF2YX0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
package testAOP;

public class HelloWorld {

public static void main(String args[]) {
        HelloWorld world = new HelloWorld();
        world.greet();
    }

public String greet() {
        System.out.println("Hello World!");
    }
}
</pre></td></tr></table>

<p>This is simply a standard Java application, and can be compiled with <code>javac -d target HelloWorld.java</code> </p>

<h3>Writing the Aspect</h3>

<p>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.</p>

import org.codehaus.aspectwerkz.joinpoint.JoinPoint;

public class MyAspect {

public void beforeGreeting(JoinPoint joinPoint) {
        System.out.println("before greeting...");
    }

public void afterGreeting(JoinPoint joinPoint) {
        System.out.println("after greeting...");
    }
}
</pre></td></tr></table>

<p>Notice the signature of the aspect methods. They need to take this <code>JoinPoint</code> 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!).<br />
(Note: for 2.0, specific optimizations can be applied by using the <em>StaticJoinPoint</em> interface or no interface at all. Please refer to the AspectWerkz 2.0 documentation)</p>

<p>To compile this aspect class you'll need to include the <code>aspectwerkz-0.10.jar</code> in the classpath, i.e.</p>

<p>For AspectWerkz 1.0 final:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
javac -d target -classpath $ASPECTWERKZ_HOME/lib/aspectwerkz-1.0.jar MyAspect.java
</pre></td></tr></table>

<h3>Defining the Aspect</h3>

<p>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 (<em>pointcuts</em>), and which aspect method to actual insert (<em>advice</em>).</p>

<p>Specifying pointcuts and advice can be done using either of (or a mixture of), the following methods.</p>

<h4>Using an XML definition file</h4>

<p>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 (<code>aop.xml</code>):</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;aspectwerkz>
    &lt;system id="AspectWerkzExample">
        &lt;package name="testAOP">
            &lt;aspect class="MyAspect">
                &lt;pointcut name="greetMethod" expression="execution(* testAOP.HelloWorld.greet(..))"/>
                &lt;advice name="beforeGreeting" type="before" bind-to="greetMethod"/>
                &lt;advice name="afterGreeting" type="after" bind-to="greetMethod"/>
            &lt;/aspect>
        &lt;/package>
    &lt;/system>
&lt;/aspectwerkz>
</pre></td></tr></table>

<p>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.</p>

<p>When specifying the <code>pointcut</code> the name can be any label you like, it's only used to bind the <code>advice</code>. The expression should be any valid expression occording to the <a href="http://aspectwerkz.codehaus.org/definition_issues.html#Join point selection pattern language">Join point selection pattern language</a> however you <strong>MUST</strong> 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 <em>greet method</em>.</p>

<p>In the <code>advice</code> tag, the <code>name</code> attribute should be the name of the method in the aspect class, (specified in the <code>aspect</code> tag), which you wish to insert at the specific joinpoint. Type is set to <code>before</code>, <code>after</code>, or <code>around</code>, depending on where exactly you wish to inser the method in relation to the joinpoint. <code>bind-to</code> specifies the name of the <code>pointcut</code> to which this <code>advice</code> will be bound.</p>

<p>This example identifies the <code>HelloWorld.greet()</code> method and assigns it the pointcut label <code>greetMethod</code>. It then inserts the <code>MyAspect.beforeGreeting</code> method just before <code>greet</code> is called, and <code>MyAspect.afterGreeting</code> just after the <code>greet</code> method returns. </p>

<h4>Using Annotations</h4>

<p>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:</p>

import org.codehaus.aspectwerkz.joinpoint.JoinPoint;

public class MyAspectWithAnnotations {

/**
    * @Before execution(* testAOP.HelloWorld.greet(..))
    */
    public void beforeGreeting(JoinPoint joinPoint) {
        System.out.println("before greeting...");
    }

/**
    * @After execution(* testAOP.HelloWorld.greet(..))
    */
    public void afterGreeting(JoinPoint joinPoint) {
        System.out.println("after greeting...");
    }
}
</pre></td></tr></table>

<p>After adding annotations you need to run a special AspectWerkz tool. This is done after compiling your aspect class files, (i.e. after running <code>javac</code>). The tool, known as the <code>AnnotationC</code> compiler, can be invoked as follows, passing in the source directory (<code>.</code>), and the class directory (<code>target</code>):</p>

<p>For AspectWerkz 1.0 final:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
java -cp $ASPECTWERKZ_HOME/lib/aspectwerkz-1.0.jar org.codehaus.aspectwerkz.annotation.AnnotationC . target
</pre></td></tr></table>

<p>More information on the <code>AnnotationC</code> compiler can be found <a href="http://aspectwerkz.codehaus.org/attribute_definition.html#Attribute compilation">here</a>.</p>

<p>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:</p>

<h3>Weaving in and running the Aspect</h3>

<p>There are basically two ways to actually weave the code together, one called <em>online weaving</em> performs the weaving as the classes are loaded into the JVM. The other is <em>offline weaving</em>, and is done before the code is actually run.</p>

<h4>Using online weaving</h4>

<p>When using <em>online weaving</em> you need to decide which JVM your going to use. This is because the <em>hook</em> which allows AspectWerkz to weave the classes together on the fly, is different in <em>Sun HotSpot</em> (where JDI/HotSwap is used), as apposed to <em>BEA JRockit</em> (where a PreProcessor is used). The default is setup to use Sun JDK 1.4.2, however if you want to use <a href="http://commerce.bea.com/showproduct.jsp?family=WLJR&amp;major=JR142SDK&amp;minor=0">JRockit</a>, simply edit the <code>bin/aspectwerkz</code> file (<code>aspectwerkz.bat</code> on windows), locate the &quot;Sample Usage for JRockit&quot; line and uncomment the command. Of course, remember to comment out the existing Java command above it.</p>

<p>Using <a href="http://commerce.bea.com/showproduct.jsp?family=WLJR&amp;major=JR142SDK&amp;minor=0">JRockit</a> is the preferred choice since it will not only perform much better (no need to run in debug mode, which using HotSwap, e.g. Sun and IBM, requires) and be more stable, but will also work on JDK 1.3, 1.4 and 1.5.  </p>

<p>Performing the weaving is then just a matter of using the <code>aspectwerkz</code> command line tool to run <code>java</code> with the relevant classes, pointing it to the definition file, (even if using annotations you still need the 'stub' definition file), i.e.</p>

<p>This produces the expected output:</p>

<h4>Using offline weaving</h4>

<p>With <em>offline weaving</em>, the test applications classes are modified on the disk with the aspect calls. That is to say <em>offline weaving</em> amends your actual class definition, (as opposed to <em>online weaving</em> which doesn't modify any classes). To perform <em>offline weaving</em>, you use the <code>aspectwerkz</code> command line tool with the <code>-offline</code> option, as follows:</p>

<p>The last option on the command (<code>target</code>) 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.</p>

<p>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:</p>

<p>For AspectWerkz 1.0 final:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
java -cp $ASPECTWERKZ_HOME/lib/aspectwerkz-1.0.jar:target 
     -Daspectwerkz.definition.file=aop.xml testAOP.HelloWorld
</pre></td></tr></table>

<p><em>Note: Windows users need to replace the &quot;:&quot; path separator by a &quot;;&quot;</em></p>

<p>This produces the expected output:</p>

<h3>Conclusion</h3>

<p>Now we have learned how to: </p>
<ol>
	<li>write a simple aspect in pure Java</li>
	<li>define the aspect using annotations and XML</li>
	<li>weave the aspect into your application using online and offline mode</li>
	<li>run it</li>
</ol>

<p>Then read the next tutorial <a class="confluence-link" href="/display/AW/Hijacking+Hello+World" data-linked-resource-id="5157" data-linked-resource-type="page" data-linked-resource-default-alias="Hijacking Hello World" data-base-url="http://docs.codehaus.org">Hijacking Hello World</a> or the <a href="http://aspectwerkz.codehaus.org/">online documentation</a></p>

<p>Want to use AOP in your appplication server? </p>

<p>Then start by reading <a href="http://dev2dev.bea.com/technologies/soa/businesslogic/articles/boner_vasseur.jsp">this dev2dev article</a> on how to enable AOP in WebLogic Server (the concepts are generic an works for any application server). </p>

<h3>Credits</h3>

<p>This tutorial is based on a tutorial written by <a href="http://www.davidmaddison.com/">David Maddison</a> (with modifications and enhancements by <a class="confluence-link confluence-userlink" data-username="jboner" href="/display/~jboner" data-linked-resource-id="31" data-linked-resource-type="userinfo" username="jboner" data-linked-resource-default-alias="jboner jboner" data-base-url="http://docs.codehaus.org">jboner jboner</a>)</p>