[jboss-cvs] JBossAS SVN: r69936 - in projects/aop/trunk/aop/docs/reference: aopuserguide and 2 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Feb 19 11:06:12 EST 2008
Author: stalep
Date: 2008-02-19 11:06:12 -0500 (Tue, 19 Feb 2008)
New Revision: 69936
Added:
projects/aop/trunk/aop/docs/reference/aopuserguide/
projects/aop/trunk/aop/docs/reference/aopuserguide/en/
projects/aop/trunk/aop/docs/reference/aopuserguide/en/master.xml
projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/
projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/annotations.xml
projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/aopide.xml
projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/building.xml
projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/dynamic.xml
projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/integration.xml
projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/introductions.xml
projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/maven.xml
projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/terms.xml
projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/testing.xml
projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/toc.xml
projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/what.xml
projects/aop/trunk/aop/docs/reference/aopuserguide/pom.xml
Log:
[JBAOP-529] Added docbook info on the maven plugin.
Added: projects/aop/trunk/aop/docs/reference/aopuserguide/en/master.xml
===================================================================
--- projects/aop/trunk/aop/docs/reference/aopuserguide/en/master.xml (rev 0)
+++ projects/aop/trunk/aop/docs/reference/aopuserguide/en/master.xml 2008-02-19 16:06:12 UTC (rev 69936)
@@ -0,0 +1,181 @@
+<?xml version='1.0' encoding="iso-8859-1"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
+ "../../../../../docbook-support/support/docbook-dtd/docbookx.dtd"
+[
+<!ENTITY what SYSTEM "modules/what.xml">
+<!ENTITY terms SYSTEM "modules/terms.xml">
+<!ENTITY building SYSTEM "modules/building.xml">
+<!ENTITY annotations SYSTEM "modules/annotations.xml">
+<!ENTITY introductions SYSTEM "modules/introductions.xml">
+<!ENTITY dynamic SYSTEM "modules/dynamic.xml">
+<!ENTITY integration SYSTEM "modules/integration.xml">
+<!ENTITY testing SYSTEM "modules/testing.xml">
+<!ENTITY aopide SYSTEM "modules/aopide.xml">
+<!ENTITY maven SYSTEM "modules/maven.xml">
+]>
+<book lang="en">
+ <bookinfo>
+ <title>JBoss AOP - User Guide</title>
+ <subtitle>The Case For Aspects</subtitle>
+ <releaseinfo>2.0.0</releaseinfo>
+ </bookinfo>
+
+ <toc/>
+
+ <preface id="target" revision="1">
+ <title>Target Audience</title>
+ <para> All JBoss AOP users. This is an introduction to AOP and JBoss AOP. If you only need to lookup certain reference/specs, the reference guide might be more helpful.</para>
+ </preface>
+
+
+ <preface id="preface" revision="1">
+ <title>Preface</title>
+
+ <para>
+ Aspect-Oriented Programming (AOP) is a new paradigm that allows you to organize
+ and layer your software applications in ways that are impossible with traditional
+ object-oriented approaches. Aspects allow you to transparently glue functionality together
+ so that you can have a more layered design. AOP allows you to intercept any event in a Java
+ program and trigger functionality based on those events. Mixins allow you to introduce
+ multiple inheritance to Java so that you can provide APIs for your aspects. Combined with
+ JDK 5.0 annotations, it allows you to extend the Java language with new syntax.
+ </para>
+
+ <para>
+ JBoss AOP is a 100% Pure Java aspected oriented framework usuable in any programming
+ environment or as tightly integrated with our application server.
+ </para>
+
+ <para>
+ This document walks you through how AOP can be used to build your applications. A large number of real-world examples
+ are given in each section to illustrate various ideas. The book is broken up in the
+ following manner:
+ </para>
+ <variablelist spacing="compact">
+ <varlistentry>
+ <term>What is an Aspect?</term>
+ <listitem>
+ <para>
+ The section gives an overview on exactly what Aspect-Oriented Programming is.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Terms</term>
+ <listitem>
+ <para>
+ Defines some basic AOP terms that you will need when reading this document.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Building Aspects</term>
+ <listitem>
+ <para>
+ The chapter walks through some examples of building an aspect. One example shown is how to
+ detect JDBC connection leakages in your code. Another example is using the Observer/Observable pattern
+ Another is doing dependency injection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Aspect-Oriented Annotations</term>
+ <listitem>
+ <para>
+ This chapter walks through how you can use JDK 5.0 annotations and AOP to actually extend the Java
+ language with new syntax. Numerous real-world examples are given.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Mixins and Introductions</term>
+ <listitem>
+ <para>
+ This chapter walks through how you can use AOP introductions and mixins to have aspects with APIs,
+ or how to extend a POJO's functionality transparently. Specific examples are an Asynchronous framework
+ and making a POJO into a JMX MBean.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Dynamic AOP</term>
+ <listitem>
+ <para>
+ This chapter walks through how you can use the dynamic per-instance API that each aspectized class
+ has to define aspects on a per instance basis rather than for every instance of a class.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Integration with Pointcuts</term>
+ <listitem>
+ <para>
+ This chapter steps away from writing aspects, but rather talks about how you can publish pointcuts
+ that can be used by users/customers to integrate with your products.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Testing with AOP</term>
+ <listitem>
+ <para>
+ This chapter shows how you can use AOP to test your applications in a easier way.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ If you have questions, use the user forum linked on the JBoss AOP website. We also
+ provide a tracking links for tracking bug reports and feature requests. If you
+ are interested in the development of JBoss AOP, post a message on the forum. If
+ you are interested in translating this documentation into your language, contact us
+ on the developer mailing list.
+ </para>
+
+ <para>
+ Commercial development support, production support and training for JBoss AOP is
+ available through JBoss Inc. (see http://www.jboss.org/).
+ JBoss AOP is a project of the JBoss Professional Open Source product suite.
+ </para>
+
+ <para>
+ In some of the example listings, what is meant to be displayed on one line does not fit
+ inside the available page width. These lines have been broken up. A '\' at the end of a
+ line means that a break has been introduced to fit in the page, with the following lines
+ indented. So:
+ <programlisting>
+ Let's pretend to have an extremely \
+ long line that \
+ does not fit
+ This one is short
+ </programlisting>
+ Is really:
+ <programlisting>
+ Let's pretend to have an extremely long line that does not fit
+ This one is short
+ </programlisting>
+ </para>
+ </preface>
+
+ &what;
+
+ &terms;
+
+ &building;
+
+ &annotations;
+
+ &introductions;
+
+ &dynamic;
+
+ &integration;
+
+ &testing;
+
+ &aopide;
+
+ &maven;
+
+</book>
Property changes on: projects/aop/trunk/aop/docs/reference/aopuserguide/en/master.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/annotations.xml
===================================================================
--- projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/annotations.xml (rev 0)
+++ projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/annotations.xml 2008-02-19 16:06:12 UTC (rev 69936)
@@ -0,0 +1,311 @@
+<chapter id="annotations">
+
+ <title>Aspect-Oriented Annotations</title>
+
+ <para>
+ Annotations are a new feature of JDK 5.0 that allow you to attach metadata to any Java construct. They allow you
+ to define metadata in a typesafe way and apply it to a class, method, constructor, field, or parameter. For those
+ of you familiar with XDoclet, annotations will be very intuitive to you in that you are used to declaring tags to
+ generate code. The main difference between the two is that annotations are a typed part of the Java language,
+ while XDoclet tags can be mistyped and are harder to create. In a nutshell, JDK 5.0 annotations allow you to
+ define new Java syntax.
+ </para>
+ <para>
+ AOP provides a unique way of encapsulating behavior and applying it transparently to your application code. If
+ you combine it with annotations, you basically have a very structured, simple way of extending the Java language.
+ The annotation is the syntax, and the aspect provides the functionality for that aspect. This chapter walks
+ through detailed examples on how you can use AOP and annotations to turn your frameworks into Java language
+ features.
+ </para>
+
+ <sect1 id="annotations1" revision="1">
+ <title>Methods and Annotations</title>
+ <para>
+ Let's take a look at how you can use method annotations with AOP. Using annotations and AOP together and
+ applying this to a method is very analogous to using Java's synchronized keyword with a method. When you tag
+ a method as synchronized, you are telling the JVM that you want that method to behave in a special way when it
+ is invoked. Annotations allow you to define new keywords that you want to have trigger your own special custom
+ behavior. AOP gives you the ability to encapsulate this behavior and weave it into the execution of the method.
+ </para>
+ <para>
+ Let's say we want to add a new syntax that will allow us to fire <literal>void</literal> methods in the
+ background, in another
+ thread, if they are tagged as <literal>@Oneway</literal>. Using this new syntax would look like this:
+ </para>
+ <programlisting><![CDATA[import org.jboss.aspects.Oneway;
+
+public class Foo
+{
+ @Oneway public static void someMethod() {...}
+
+ public static void main(String[] args)
+ {
+ someMethod(); // executes in background
+ }
+}]]></programlisting>
+ <para>
+ When <literal>someMethod()</literal> is invoked within main, it will run asynchronously so that the code in main is free to do
+ ther tasks in parallel.
+ </para>
+ <para>
+ To implement this functionality, the first thing that must be done is to define the new Java syntax for our
+ <literal>@Oneway</literal> tag within an annotation.
+ </para>
+ <programlisting>
+package org.jboss.aspects;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+ at Target({ElementType.METHOD})
+public @interface Oneway {}
+ </programlisting>
+ <para>
+ Simple enough. The <literal>@Target</literal> tag allows you to narrow down where the annotation is allowed to
+ be applied. In this case, our @Oneway annotation can only be applied to a method. Remember, this is all pure
+ 100 percent Java that is available in J2SE 5.0.
+ </para>
+ <para>
+ The next thing we have to do is to define an aspect class that will encapsulate our <literal>@Oneway</literal>
+ behavior.
+ </para>
+ <programlisting>
+package org.jboss.aspects;
+
+public OnewayAspect
+{
+ private static class Task implements Runnable
+ {
+ private MethodInvocation invocation;
+
+ public Task(MethodInvocation invocation)
+ {
+ this.invocation = invocation;
+ }
+ public void run()
+ {
+ try { invocation.invokeNext(); }
+ catch (Throwable ignore) { }
+ }
+ }
+
+
+ public Object oneway(MethodInvocation invocation) throws Throwable
+ {
+ MethodInvocation copy = invocation.copy();
+ Thread t = new Thread(new Task(copy));
+ t.setDaemon(false);
+ t.start();
+ return null;
+ }
+}
+ </programlisting>
+ <para>
+ The aspect is simple enough. The oneway() method copies the invocation, creates a thread, fires off the complete
+ invocation in the background, and returns. We could imagine a more sophisticated example using some of the new
+ Executors within the J2SE 5.0 java.util.concurrent package, but hopefully this code illustrates how you could
+ build on this example to implement more complete implementations.
+ </para>
+ <para>
+ The last thing that must be done is to specify the pointcut expression that will trigger the application of the
+ <literal>OnewayAspect</literal> when the <literal>@Oneway</literal> annotation is declared on a method.
+ </para>
+ <programlisting><![CDATA[
+<aop>
+ <aspect class="org.jboss.aspects.OnewayAspect"/>
+
+ <bind pointcut="execution(void *->@org.jboss.Oneway(..))">
+ <advice name="oneway"
+ aspect="org.jboss.aspects.OnewayAspect"/>
+ </bind>
+</aop>]]></programlisting>
+ <para>
+ The pointcut expression states that any void method that is tagged as <literal>@Oneway</literal> should have
+ the <literal>OnewayAspect.oneway()</literal> method executed before it itself executes. With the annotation,
+ aspect, and pointcut expression now defined, the @Oneway syntax is now usable in your application. A simple,
+ clean, easy way of extending the Java language!
+ </para>
+ </sect1>
+
+ <sect1 id="annotations2" revision="1">
+ <title>Fields and Annotations</title>
+ <para>
+ Let's look at how you could use field annotations and AOP. Using annotations and AOP, you can can actually
+ change how a field is stored by an object or as a static member of a class. What we want to accomplish in this
+ example is that when you tag a field (static or member) as @ThreadBased, its value will behave as though it
+ were stored in a java.lang.ThreadLocal. Sure, you could use a ThreadLocal variable directly, but the problem
+ with ThreadLocal is that it is untyped and you have to use "verbose" (okay, they're not that verbose) get()
+ and set() methods. So what we'll do here is create a typed ThreadLocal field. Basically, we'll create a new
+ Java field type called the @Threadbased variable.
+ </para>
+ <para>
+ Using this new type would look like this:
+ </para>
+ <programlisting>
+import org.jboss.aspects.Threadbased;
+
+public class Foo
+{
+ @Threadbased private int counter;
+}</programlisting>
+ <para>
+ To implement this functionality, we must first define the annotation.
+ </para>
+ <programlisting>
+package org.jboss.aspects;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+ at Target({ElementType.FIELD})
+public @interface Threadbased {}
+</programlisting>
+ <para>
+ Simple enough. The @Target tag allows you to narrow down where the annotation is allowed to be applied. In this
+ case, our @Threadbased annotation can only be applied to fields.
+ </para>
+ <para>
+ The next thing to do is to define the aspect that will encapsulate our ThreadLocal behavior.
+ </para>
+ <programlisting>
+package org.jboss.aspects;
+
+import org.jboss.aop.joinpoint.*;
+import java.lang.reflect.Field;
+
+public class ThreadbasedAspect
+{
+ private ThreadLocal threadbased = new ThreadLocal();
+
+ public Object access(FieldReadInvocation invocation)
+ throws Throwable
+ {
+ // just in case we have a primitive,
+ // we can't return null
+ if (threadbased.get() == null)
+ return invocation.invokeNext();
+ return threadbased.get();
+ }
+
+ public Object access(FieldWriteInvocation invocation)
+ throws Throwable
+ {
+ threadbased.set(invocation.getValue());
+ return null;
+ }
+}</programlisting>
+ <para>
+ ThreadbasedAspect encapsulates the access to a Java field. It has a dedicated ThreadLocal variable within it to
+ track threadlocal changes to a particular field. It also has separate access() methods that are invoked
+ depending upon whether a get or set of the field is called. These methods delegate to the ThreadLocal to obtain
+ the current value of the field.
+ </para>
+ <para>
+ Finally, we must define a pointcut expression that will trigger the application of the ThreadbasedAspect when
+ the @Threadbased annotation is specified on a particular field.
+ </para>
+ <programlisting><![CDATA[
+<aop>
+ <aspect class="org.jboss.aspects.ThreadbasedAspect"
+ scope="PER_JOINPOINT"/>
+ <bind pointcut="field(* *->@org.jboss.aspects.Threadbased)">
+ <advice name="access"
+ aspect="org.jboss.aspects.ThreadbasedAspect"/>
+ </bind>
+</aop>]]></programlisting>
+ <para>
+ Just in case we have multiple @Threadbased variables defined in one class, we want an instance of
+ ThreadbasedAspect to be allocated per field for static fields. For member fields, we want an instance of
+ ThreadbasedAspect to be allocated per field, per object instance. To facilitate this behavior, the aspect
+ definition scopes the instance of when and where the aspect class will be allocated by setting it to
+ PER_JOINPOINT. If we didn't do this scoping, JBoss AOP would only allocate one instance of ThreadbasedAspect
+ and different fields would be sharing the same instance of the ThreadLocal -- something that we don't want.
+ </para>
+ <para>
+ Well that's it. A clean, easy way of extending Java to specify a new special type. Note: This particular aspect
+ comes bundled with JBoss AOP.
+ </para>
+ </sect1>
+ <sect1 id="annotations3" revision="1">
+ <title>Dependency Injection</title>
+ <para>
+ Another interesting place where field annotations and AOP can be used is with dependency injection. Dependency
+ injection is about objects declaring what information, configuration, or service references they need, and
+ having the runtime automagically inject those dependencies rather than having your code do explicit lookups on
+ a registry service. In J2EE-land, getting access to a javax.transaction.TransactionManager service is not
+ standardized and is actually different per vendor implementation. Many framework developers need to use the
+ TransactionManager to implement custom transactional services. The use of AOP with field annotations is a great
+ way to provide this dependency injection and to abstract away the details of how a TransactionManager is
+ referenced by components that need it. Let's define an aspect that will inject a reference to a
+ TransactionManager into the value of a field.
+ </para>
+ <para>
+ First, we must again define our annotation.
+ </para>
+ <programlisting>
+package org.jboss.aspects;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+ at Target({ElementType.FIELD})
+public @interface Inject {}</programlisting>
+ <para>
+ Next we will define the aspect class that will encapsulate the resolving of the TransactionManager. This aspect
+ will be specific to the JBoss application server, but you could define different implementations per vendor.
+ </para>
+ <programlisting><![CDATA[package org.jboss.aspects;
+
+import org.jboss.aop.joinpoint.*;
+import java.lang.reflect.Field;
+import javax.transaction.TransactionManager;
+import org.jboss.tm.TxManager;
+
+public InjectTMAspect
+{
+ private TransactionManager tm = TxManager.getInstance();
+
+ public Object access(FieldReadInvocation invocation)
+ throws Throwable
+ {
+ return tm;
+ }
+
+ public Object access(FieldWriteInvocation invocation)
+ throws Throwable
+ {
+ throw new RuntimeException(
+ "Setting an @Injected variable is illegal");
+ }
+}]]></programlisting>
+ <para>
+ Finally, we have to define the XML binding that will trigger the application of the InjectTMAspect when the
+ @Inject tag is applied to a field. The pointcut expression basically states that for any field of type
+ TransactionManager and tagged as @Inject, apply the InjectTMAspect.
+ </para>
+ <programlisting><![CDATA[<aop>
+ <aspect class="org.jboss.aspects.InjectTMAspect"/>
+
+ <bind pointcut="field(javax.transaction.TransactionManager *->@org.jboss.aspects.Inject)">
+ <advice name="access"
+ aspect="org.jboss.aspects.InjectTMAspect"/>
+ </bind>
+</aop>]]></programlisting>
+ <para>
+ Now that the annotation, aspect class, and XML binding have been defined, we can use it within our code.
+ </para>
+ <programlisting>import javax.transaction.TransactionManager;
+import org.jboss.aspects.Inject;
+
+public class MyTransactionalCache
+{
+ @Inject private TransactionManager tm;
+...
+}</programlisting>
+
+ </sect1>
+</chapter>
+
+
+
+
Property changes on: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/annotations.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/aopide.xml
===================================================================
--- projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/aopide.xml (rev 0)
+++ projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/aopide.xml 2008-02-19 16:06:12 UTC (rev 69936)
@@ -0,0 +1,360 @@
+<chapter id="aopide">
+
+ <title>JBoss AOP IDE</title>
+ <sect1 id="aopide-intro" revision="1">
+ <title>The AOP IDE</title>
+ <para>
+ JBoss AOP comes with an Eclipse plugin that helps you define interceptors to an eclipse project
+ via a GUI, and to run the application from within Eclipse. This is a new project, and expect the
+ feature set to grow quickly!
+ </para>
+ </sect1>
+
+ <sect1 id="aopide-install" revision="1">
+ <title>Installing</title>
+ <para>
+ You install the JBoss AOP IDE in the same way as any other Eclipse plugin.
+ <itemizedlist>
+ <listitem>
+ Make sure you have Eclipse 3.0.x installed, and start it up.
+ </listitem>
+ <listitem>
+ Select Help > Software Updates > Find and Install in the Eclipse
+ workbench.
+ </listitem>
+ <listitem>
+ In the wizard that opens, click on the "Search for new features to install" radio
+ button, and click Next.
+ </listitem>
+ <listitem>
+ On the next page you will need to add a new update site for JBossIDE. Click the
+ "New Remote Site.." button.
+ </listitem>
+ <listitem>
+ Type in "JBossIDE" for the name, and "http://jboss.sourceforge.net/jbosside/updates"
+ for the URL, and click OK.
+ </listitem>
+ <listitem>
+ You should see a new site in the list now called JBossIDE. click the "+" sign next to
+ it to show the platforms available.
+ </listitem>
+ <listitem>
+ Now, depending if you just want to install the AOP IDE (if you don't know what JBoss-IDE is,
+ go for this set of options):
+ <itemizedlist>
+ <listitem>
+ Check the "JBoss-IDE AOP Standalone" checkbox.
+ </listitem>
+ <listitem>
+ In the feature list you should check the "JBoss-IDE AOP Standalone 1.0" checkbox.
+ </listitem>
+ </itemizedlist>
+ <para>
+ If you have JBoss-IDE installed, or want to use all the other (non-AOP) features of JBoss-IDE:
+ </para>
+ <itemizedlist>
+ <listitem>
+ If you don't have JBossIDE installed, check the "JBoss-IDE 1.4/Eclipse 3.0" checkbox.
+ </listitem>
+ <listitem>
+ Check the "JBoss-IDE AOP Extension" checkbox.
+ </listitem>
+ <listitem>
+ In the feature list you should check the "JBoss-IDE AOP Extension 1.0" checkbox, and the JBoss-IDE (1.4.0) checkbox if you don't have JBossIDE installed.
+ </listitem>
+ </itemizedlist>
+
+ </listitem>
+
+ <listitem>
+ At this point you should only need to accept the license agreement(s) and wait for the install process to finish.
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect1>
+
+ <sect1 id="aopide-tutorial" revision="1">
+ <title>Tutorial</title>
+ This tutorial is meant to guide you through creating a new AOP project in eclipse using the AOP extension to JBossIDE. It assumes that you have some working knowledge of AOP, and Java.. and possibly some minimal experience dealing with eclipse as well.
+ <sect2 id="aopide-tutorial-project" revision="1">
+ <title>Create Project</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ From eclipse's main menu, you can click on the File Menu, and
+ under it, New > Project...
+ </listitem>
+ <listitem>
+ Double click on JBoss AOP Project under the JBossAOP folder
+ </listitem>
+ <listitem>
+ In the Project Name text box, let's enter <literal>HelloAOP</literal>.
+ </listitem>
+ <listitem>
+ <literal>Use Default</literal> should be fine for the project location.
+ (If you want to use an external location, make sure there are no spaces in the path.)
+ </listitem>
+ <listitem>
+ Click <literal>Finish</literal>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ At this point, your eclipse workbench should look something like this:
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/after-initial-setup.jpg" format="JPG" align="center"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="../shared/images/after-initial-setup.jpg" format="JPG" align="center"/>
+ </imageobject>
+ </mediaobject>
+ </sect2>
+ <sect2 id="aopide-tutorial-class" revision="1">
+ <title>Create Class</title>
+ <para>
+ Next step is to create a normal Java class.
+ <itemizedlist>
+ <listitem>
+ Right click on the "src" directory in the Package Explorer and in the menu, click New > Class.
+ </listitem>
+ <listitem>
+ The only thing you should need to change is the Name of the class. Enter <literal>HelloAOP</literal> without
+ quotes into the Name textbox, and click <literal>Finish</literal>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Modify the code for your class so it loks like
+ <programlisting>
+public class HelloAOP {
+
+ public void callMe ()
+ {
+ System.out.println("AOP!");
+ }
+
+ public static void main (String args[])
+ {
+ new HelloAOP().callMe();
+ }
+}
+ </programlisting>
+ </para>
+ </sect2>
+ <sect2 id="aopide-tutorial-interceptor" revision="1">
+ <title>Create Interceptor</title>
+ <para>
+ Next we want to create an interceptor to the class.
+ <itemizedlist>
+ <listitem>
+ Right click on the "src" directory in the Package Explorer and in the menu, click
+ New > Class. In the resulting dialog:
+ <itemizedlist>
+ <listitem>
+ Name the class <literal>HelloAOPInterceptor</literal>
+ </listitem>
+ <listitem>
+ Add <literal>org.jboss.aop.advice.Interceptor</literal> to the list of interceptors.
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ Then modify the class so it looks like:
+ <programlisting>
+ import org.jboss.aop.advice.Interceptor;
+ import org.jboss.aop.joinpoint.Invocation;
+
+ public class HelloAOPInterceptor implements Interceptor {
+
+ public String getName() {
+ return "HelloAOPInterceptor";
+ }
+
+ //We renamed the arg0 parameter to invocation
+ public Object invoke(Invocation invocation) throws Throwable {
+ System.out.print("Hello, ");
+ //Here we invoke the next in the chain
+ return invocation.invokeNext();
+ }
+ }
+ </programlisting>
+ </para>
+ </sect2>
+ <sect2 id="aopide-tutorial-bind" revision="1">
+ <title>Applying the Interceptor</title>
+ <para>
+ In order to apply your Interceptor to the callMe() method, we'll first need to switch back
+ to the <literal>HelloAOP.java</literal> editor. Once the editor is active, you should be
+ able to see the callMe() method in the Outline view (If you cannot see the outline view,
+ go to Window > Show View > Outline).
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/call-me-arrow.jpg" format="JPG" align="center"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="../shared/images/call-me-arrow.jpg" format="JPG" align="center"/>
+ </imageobject>
+ </mediaobject>
+ <para>
+ Right click on this method, and click JBoss AOP > Apply Interceptor(s)... A dialog should open,
+ with a list of available Interceptors. Click on <literal>HelloAOPInterceptor</literal>, and click
+ <literal>Finish</literal>.
+ </para>
+ <para>
+ You should see in your Package Explorer that the file "jboss-aop.xml" now exists under your project root.
+ </para>
+ </sect2>
+
+
+ <sect2 id="aopide-tutorial-running" revision="1">
+ <title>Running</title>
+ <para>
+ Now all that's left is running the application! Similar to running a normal Java Application from Eclipse,
+ you must create a Run Configuration for your project.
+ <itemizedlist>
+ <listitem>
+ From the Run menu of eclipse, and choose "Run..."
+ </listitem>
+ <listitem>
+ In the dialog that opens, you should see a few choices in a list on the left. Double click on "JBoss AOP Application".
+ </listitem>
+ <listitem>
+ Once it is finished loading, you should have a new Run Configuration under JBoss AOP Application called "Hello AOP".
+ </listitem>
+ <listitem>
+ Click the "Run" button
+ </listitem>
+ </itemizedlist>
+ The Eclipse console should now say: <literal>Hello, AOP!</literal>, where
+ the <literal>Hello, </literal> bit has been added by the interceptor.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/hello-aop-console.jpg" format="JPG" align="center"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="../shared/images/hello-aop-console.jpg" format="JPG" align="center"/>
+ </imageobject>
+ </mediaobject>
+ </sect2>
+
+ <sect2 id="aopide-tutorial-navigation" revision="1">
+ <title>Navigation</title>
+ <para>
+ In the real world, when developing AOP application across a development team, you can expect it will be hard
+ to understand when and where aspects are applied in your codebase. JBoss-IDE/AOP has a few different strategies
+ for notifying developers when an aspect is applied to a certain part of code.
+ </para>
+ <sect3 id="aopide-tutorial-navigation-advised">
+ <title>Advised Markers</title>
+ <para>
+ A marker in eclipse is a small icon that appears on the left side of the editor. Most developers are familiar
+ with the Java Error and Bookmark markers. The AOP IDE provides markers for methods and fields which are
+ intercepted. To further facilitate this marking, anytime the developer presses Ctrl + 1 (the default key combination
+ for the Eclipse Quick Fix functionality)), a list of interceptors and advice will be given for that method or
+ field. This makes navigation between methods and their interceptors extremeley easy!
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/advised-marker-example.jpg" format="JPG" align="center"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="../shared/images/advised-marker-example.jpg" format="JPG" align="center"/>
+ </imageobject>
+ </mediaobject>
+ </sect3>
+ <sect3 id="aopide-tutorial-navigation-members">
+ <title>The Advised Members View</title>
+ <para>
+ The Advised Members view gives the developer an overview of every single method and field in the current class that is
+ advised by an Aspect or Interceptor. Let's have a look.
+ <itemizedlist>
+ <listitem>
+ From the Eclipse main menu, click on Window > Show View > Other...
+ </listitem>
+ <listitem>
+ In the window that opens, you should see a folder called "JBoss AOP".
+ Press the "+" to expand it.
+ </listitem>
+ <listitem>
+ Double click on "Advised Members"
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Once you've done this, you should now make sure you are currently editing the <literal>HelloAOP</literal> class we
+ created in the last tutorial. Once you have that class open in an editor, you should see something similar to this
+ in the Advised Members view:
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/advised-members-view.jpg" format="JPG" align="center"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="../shared/images/advised-members-view.jpg" format="JPG" align="center"/>
+ </imageobject>
+ </mediaobject>
+ <para>
+ Here we see that the method "callMe()" is intercepted by the interceptor <literal>HelloInterceptor</literal>.
+ Double clicking on <literal>HelloInterceptor</literal> will take you straight to it. This view is similar to
+ the Outline view, except it only shows members in your class which are intercepted.
+ </para>
+ </sect3>
+ <sect3 id="aopide-tutorial-navigation-aspect-manager">
+ <title>The Aspect Manager View</title>
+ <para>
+ The Aspect Manager View is a graphical representation of the AOP descriptor file (jboss-aop.xml). It
+ allows you to remove an Interceptor or advice from a pointcut, as well as apply new Interceptors and
+ Advice to existing pointcuts.
+ <itemizedlist>
+ <listitem>
+ From the Eclipse main menu, click on Window > Show View > Other...
+ </listitem>
+ <listitem>
+ In the window that opens, you should see a folder called "JBoss AOP".
+ Press the "+" to expand it.
+ </listitem>
+ <listitem>
+ Double click on "Aspect Manager"
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Under Bindings, you'll notice that a pointcut is already defined that matches our "callMe()" method, and our
+ <literal>HelloInterceptor</literal> is directly under it. Right Click on <literal>HelloInterceptor</literal>
+ will provide you with this menu:
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/aspect-manager-view-interceptor-ctxt-menu.jpg" format="JPG" align="center"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="../shared/images/aspect-manager-view-interceptor-ctxt-menu.jpg" format="JPG" align="center"/>
+ </imageobject>
+ </mediaobject>
+ <para>
+ You can remove the interceptor, or jump to it directly in code. If you right click on the binding (pointcut)
+ itself, you'll be able to apply more interceptors and advice just like when right clicking on a field or method
+ in the outline view. You can also remove the entire binding altogether (which subsequently removes all child
+ interceptors and advice, be warned)
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/aspect-manager-view-pointcut-ctxt-menu.jpg" format="JPG" align="center"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="../shared/images/aspect-manager-view-pointcut-ctxt-menu.jpg" format="JPG" align="center"/>
+ </imageobject>
+ </mediaobject>
+ </sect3>
+ </sect2>
+ </sect1>
+</chapter>
+
+
+
+
Property changes on: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/aopide.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/building.xml
===================================================================
--- projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/building.xml (rev 0)
+++ projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/building.xml 2008-02-19 16:06:12 UTC (rev 69936)
@@ -0,0 +1,114 @@
+<chapter id="building">
+
+ <title>Building Aspects</title>
+ <para>
+ The last chapter had a basic boring introduction to aspects with the lame, commonly used example of metrics. AOP
+ can be applied in a much broader sense than the overused examples of tracing and security and this chapter looks
+ into other more compelling examples of using basic AOP.
+ </para>
+ <sect1 id="identifying" revision="1">
+ <title>Identifying Aspects</title>
+ <para>
+ Aspect-Oriented programming is not a replacement
+ for object-oriented programming, but rather a compliment to it. AOPers generally say that OOP solves 90% of problems
+ and AOP solves the 10% of problems that OOP isn't good at. This section of the docbook will expand over time,
+ but let's discuss some ways in which you can identify whether
+ or not AOP is a good solution for a particular problem.
+ </para>
+ <variablelist spacing="compact">
+ <varlistentry>
+ <term>Cross-cutting Concerns</term>
+ <listitem>
+ <para>
+ The metrics example in the previous chapter is an example of a cross-cutting concern in its purest form.
+ Sometimes you see structure in your code that can't be expressed as an object because it completly wraps
+ around the method you are invoking. If the behavior in question is something that you want to be able to
+ extend and maintain within its own structure then it may be a candidate for aspectizing.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Layering Based on Deployment</term>
+ <listitem>
+ <para>
+ Another place where AOP may be very useful is to layer your applications. Sometimes you want to model
+ a particular service or object that has many configuration options yet you don't want to bloat your service
+ with unmaintainable code. AOP provides a nice way to layer such complex services. JBoss AOP provides
+ a XML configurable mechanism to configure such aspects per deployment. A good example of this is
+ a caching service that might have different locking policies. It is easier to encapsulate such
+ locking policies as aspects so that the base caching code doesn't get polluted with locking concerns.
+ This makes the code easier to maintain.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Transparency</term>
+ <listitem>
+ <para>
+ Many times you want to write plain Java code that focuses solely on business or application logic
+ and do not want to introduce any concerns like middleware. AOP allows you to apply things like
+ middleware transparently to your code without polluting your code. Some examples include
+ the transaction demarcation and role-based security features in the JBoss AOP Aspect Library.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+ <sect1 id="exceptions" revision="1">
+ <title>Exception Handling</title>
+ <para>
+ Metrics and tracing are simple examples of building aspects. Another great simple example is to use AOP
+ for exception handling. For example, SQLException is an exception that contains error information like invalid
+ sql statement or deadlock that is similar per database vendor, but is expressed as different error codes
+ and string messages. You can use AOP to intercept statement execution, catch SQLException errors, and turn
+ them into typed exceptions that application code can handle independent of database vendor. So let's code
+ an example of this.
+ </para>
+ <programlisting>public class InvalidSQlException extends SQLException
+{
+ InvalidSQLException(SQLException ex)
+ {
+ super(ex.getMessage(), ex.getSQLState(), ex.getErrorCode());
+ }
+}</programlisting>
+ <para>
+ What we'll do is write an aspect that wraps calls to all
+ <literal>java.sql.Statement</literal> execute methods
+ and turn them into typed exceptions like the example above. We'll leave some code up to your imagination
+ since such an aspect would be quite long to deal with every error code of every database vendor, but hopefully
+ you can get the idea here.
+ </para>
+ <programlisting>public class SQLExceptionAspect
+{
+ public Object handleSqlException(Invocation invocation) throws Throwable
+ {
+ try
+ {
+ return invocation.invokeNext();
+ }
+ catch (SQLException ex)
+ {
+ if (isVendorInvalidSqlErrorCode(ex.getErrorCode())) throw new InvalidSQLException(ex);
+ if (isVendorDeadlockErrorCode(ex.getErrorCode()) throw new SQLDeadlockException(ex);
+ ... and so on ...
+ }
+ }
+ ... impl of isVendor methods ...
+}</programlisting>
+ <para>
+ Now that the aspect is defined we use a
+ <literal>call</literal> pointcut expression to intercept all the
+ execute methods of
+ <literal>java.sql.Statement</literal>.
+ </para>
+ <programlisting><![CDATA[<aspect class="SQLExceptionAspect" scope="PER_VM"/>
+<bind pointcut="call(* $instanceof{java.sql.Statement}->execute*(..))">
+ <advice name="handleSqlException" aspect="SQLExceptionAspect"/>
+</bind>]]></programlisting>
+ </sect1>
+
+</chapter>
+
+
+
+
Property changes on: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/building.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/dynamic.xml
===================================================================
--- projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/dynamic.xml (rev 0)
+++ projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/dynamic.xml 2008-02-19 16:06:12 UTC (rev 69936)
@@ -0,0 +1,38 @@
+<chapter id="dynamic">
+
+ <title>Dynamic AOP</title>
+
+ <sect1 id="dynamic1" revision="1">
+ <title>Hot Deployment</title>
+ <para>
+ Any joinpoint that has been aspectized by the <literal>aopc</literal> compiler or by a load time transformation
+ is set up to be able to have advices/interceptors added or removed from it at runtime. This is JBoss AOP's
+ first definition of Dynamic AOP. Using the <literal>prepare</literal> action allows you to aspectize
+ any joinpoint in your application so that advices/interceptors can be applied later at runtime. The over
+ head of such a massaging of the bytecode is very minimal as it is just an extra boolean expression. The benefits
+ for search an architecture allow you to do things like deploy and undeploy metrics or statistic gathering
+ on a needed basis. If you are using AOP for testing (See "Testing with AOP"), it allows you to deploy/undeploy
+ testing aspects as you run your automated tests on your live system.
+ </para>
+ </sect1>
+ <sect1 id="dynamic2" revision="1">
+ <title>Per Instance AOP</title>
+ <para>
+ JBoss AOP has the ability to apply interceptors on a per instance basis rather than having interceptors be
+ applied entirely to the class. This is very useful when you have instances of an object that need to behave
+ differently in different circumstances.
+ </para>
+ <para>
+ A perfect example of this is JBoss Cache AOP (TreeCacheAOP). It uses AOP to <literal>prepare</literal>
+ classes so that field access may be intercepted. When an object is inserted into the cache, TreeCacheAOP
+ adds field interceptors for that particular instance so that it can do automatic replication across a cluster
+ or to automatically provide transaction properties to the object's state. When the object is removed from
+ cache, the field interceptors are removed from that particular instance.
+ </para>
+ </sect1>
+
+</chapter>
+
+
+
+
Property changes on: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/dynamic.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/integration.xml
===================================================================
--- projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/integration.xml (rev 0)
+++ projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/integration.xml 2008-02-19 16:06:12 UTC (rev 69936)
@@ -0,0 +1,61 @@
+<chapter id="integration">
+
+ <title>Integration With Pointcuts</title>
+ <para>
+ This docbook has talked a lot about building aspects either with regular aspects, annotations, and introductions.
+ This chapter takes a step back and doesn't talk about building aspects, but rather how you can use plain old
+ pointcuts in your application to provide logical integration points.
+ </para>
+ <sect1 id="integration1" revision="1">
+ <title>Integration</title>
+ <para>
+ What you've seen by reading this docbook and the "Reference Manual" on JBoss AOP is that AOP provides a rich
+ pointcut expression language that allows you to intercept various points in the Java language. If you think
+ about it, the pointcut language allows you to turn any point in your Java language into an event. An event
+ that can be caught and handled by any piece of code.
+ </para>
+ <para>
+ After productizing and shipping an application, sometimes users want to integrate with such "events". They
+ want to be able to hook into different places of your application so that they can trigger things specific
+ to their particular deployment of your product. Using object-oriented techniques to provide these hooks to users
+ would require special gluecode every time a user request like this was made. Also, as more and more of these
+ hooks are exposed through object-orientation, it becomes harder and harder to redesign, refactor, or change
+ APIs as the user base is tightly coupled to existing code.
+ </para>
+ <para>
+ This is were AOP and pointcuts come in. Instead of writing sometimes complicated gluecode, or refactoring
+ the application to provide such user-request integration points, the application can provide pointcut
+ expressions the user base can use to integrate their specific integration use cases. The application provides
+ logical names to code points as pointcut expressions. The pointcut expression can change over time as the
+ application code is redesigned and/or refactored, but the logical name of the join point/event/integration point
+ stays the same and user hooks don't have to change either. Let's look at an example:
+ </para>
+ <programlisting>public class BankAccount
+{
+ public void withdraw(double amount) {...}
+}</programlisting>
+ <para>
+ Let's say the user of this bank account ERP system wanted to have an email sent to the account holder whenever
+ a successful withdraw was made. The ERP system could provide the hook as a pointcut
+ and then the user can write an email aspect that binds with this pointcut.
+ </para>
+ <programlisting><![CDATA[<pointcut name="WITHDRAW" expr="execution(public void BankAccount->withdraw(double))"/>]]></programlisting>
+ <para>
+ The <literal>BankAccount</literal> class would be instrumented with AOP hooks. The overhead is quite tiny
+ as only an additional boolean expression is needed to instrument this kind of hook. If the class or method
+ name changes, the user integration code is unaffected as they bind their email hook to the logical pointcut
+ name.
+ </para>
+ <para>
+ JBoss currently provides integration points in its EJB and MBean layers in such the same way. Recently,
+ BEA Weblogic published AspectJ style pointcuts into the Weblogic runtime so that users could integrate using
+ AspectJ. As AOP becomes more popular you'll see more and more software products offering integration points
+ through pointcut expressions.
+ </para>
+ </sect1>
+
+</chapter>
+
+
+
+
Property changes on: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/integration.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/introductions.xml
===================================================================
--- projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/introductions.xml (rev 0)
+++ projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/introductions.xml 2008-02-19 16:06:12 UTC (rev 69936)
@@ -0,0 +1,316 @@
+<chapter id="introductions">
+
+ <title>Mixins and Introductions</title>
+ <para>
+ When people thing of AOP, they usually think of interception, pointcut expressions, aspects, and advices. AOP
+ isn't just about those things. Another important feature in JBoss AOP is the ability to introduce an interface
+ to an existing Java class in a transparent way. You can force a class to implement an interface and even specify
+ an additional class called a mixin that implements that interface. Very similar to C++'s multiple inheritance.
+ Now, why would you want to use introductions/mixins? That's what this chapter is all about.
+ </para>
+
+ <sect1 id="intros" revision="1">
+ <title>Introducing Introductions</title>
+ <para>
+ The first thing we'll show here is how to force an existing Java class to implement any interface you want.
+ The JBoss AOP tutorial is a good place to start for an example, so let's grab the code from the introductions
+ tutorial.
+ </para>
+ <para>
+ The first example we'll show is how to take an existing non-serializable class and make it serializable.
+ This use case may be usable if there's a thirdparty library you don't have the source for, or you want
+ to control whether your class is serializable or not based on how you deploy your application.
+ </para>
+ <programlisting>public class POJO
+{
+ private String field;
+}</programlisting>
+ <para>
+ To take this class and make it serializable is very simple. Just the following XML is required:
+ </para>
+ <programlisting><![CDATA[<introduction class="POJO">
+ <interfaces>java.io.Serializable</interfaces>
+</introduction>
+ ]]></programlisting>
+ <para>
+ The above XML just states that the AOP framework is to apply the
+ <literal>java.io.Serializable</literal> interface
+ to the
+ <literal>POJO</literal> class. You can have one or more interfaces specified with the
+ <literal>interfaces</literal>
+ element. These interfaces are comma delimited.
+ </para>
+ <para>
+ If the introduced interfaces have methods not implemented by the class, then the AOP framework with add an
+ implementation of these methods to the class. The methods will delegate to the AOP framework and must be
+ handled/serviced by an interceptor or advice otherwise a
+ <literal>NullPointerException</literal> will result.
+ </para>
+ </sect1>
+
+ <sect1 id="mixins" revision="1">
+ <title>Mixin It Up</title>
+ <para>
+ Introducing interfaces only is quite limited when the introduced interfaces have methods that the class doesn't
+ implement as you have to write a lot of generically inclined code that handle these types of method calls within
+ an advice or interceptor. This is where mixins come in. The AOP framework allows you to define a mixin class
+ that implements the introduced interface(s). An instance of this mixin class will be allocated the first time
+ you invoke a method of the introduced interface.
+ </para>
+ <para>
+ Again, let's steal from the introductions tutorial. We'll take an existing class, force it to implement
+ the
+ <literal>java.io.Externalizable</literal> interface and provide a class that implements
+ <literal>Externalizable</literal>
+ </para>
+ <programlisting>public class POJO
+{
+ private String field;
+}</programlisting>
+ <para>
+ To take this class and make it externalizable is very simple. Just the following XML is required:
+ </para>
+ <programlisting><![CDATA[<introduction class="POJO">
+ <mixin>
+ <interfaces>
+ java.io.Externalizable
+ </interfaces>
+ <class>ExternalizableMixin</class>
+ <construction>new ExternalizableMixin(this)</construction>
+ </mixin>
+</introduction>]]></programlisting>
+ <para>
+ The above XML just states that the AOP framework is to apply the
+ <literal>java.io.Externalizable</literal> interface
+ to the
+ <literal>POJO</literal> class. You can have one or more interfaces specified with the
+ <literal>interfaces</literal>
+ element. These interfaces are comma delimited.
+ </para>
+ <para>
+ The
+ <literal>class</literal> element defines the mixin class that will implement the externalizable interface
+ and handle serialization of the
+ <literal>POJO</literal> class.
+ </para>
+ <para>
+ The
+ <literal>construction</literal> element allows you to specify Java code that will be used to initialize
+ the mixin class when it is created. JBoss AOP will create a field within the
+ <literal>POJO</literal>
+ class that will hold the instance of the mixin. This field will be initialized with the Java code you provide
+ in the
+ <literal>construction</literal> element. The
+ <literal>this</literal> pointer in the construction above
+ pertains to the
+ <literal>POJO</literal> class instance.
+ </para>
+ <para>
+ Finally, you need to implement the mixin class that will handle externalization.
+ </para>
+ <programlisting>public class ExternalizableMixin implements java.io.Externalizable
+{
+ POJO pojo;
+
+ public ExternalizableMixin(POJO pojo)
+ {
+ this.pojo = pojo;
+ }
+
+ public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException
+ {
+ pojo.stuff2 = in.readUTF();
+ }
+ public void writeExternal(ObjectOutput out) throws IOException
+ {
+ out.writeUTF(pojo.stuff2);
+ }
+}</programlisting>
+ <sect2 id="multi" revision="1">
+ <title>Multiple Inheritance</title>
+ <para>
+ One thing that should be noted about mixins is that they allow you to do true multiple inheritance within
+ Java. Yes, it is not explicit multiple inheritance as you must define the inheritance mappings in XML
+ or via an annotation binding, but it does allow you to take advantage of something C++ has had for years.
+ Many thought leaders argue against the use of multiple inheritance, but when used correctly and purely
+ as an abstract mixin, it can be a very useful tool in application design.
+ </para>
+ </sect2>
+ </sect1>
+ <sect1 id="apis" revision="1">
+ <title>Aspects with APIs</title>
+ <para>
+ The serialization and externalization examples show previously in this chapter are kinda lame. Sure, you
+ can use introductions/mixins for multiple inheritance, or to do nice tricks like forcing an existing class
+ to be serializable. A more compelling use case is needed to justify this particular feature. This is what
+ this section is about.
+ </para>
+ <para>
+ The best use cases for introductions/mixins comes when you have an aspect that requires an API for the user
+ to interact with. Many aspects have runtime APIs so that the application developer can interact with a particular
+ aspect to set configuration or to gain added behavior. A good example of an aspect with an API is if we expand
+ on the
+ <literal>@Oneway</literal> example in the "Aspect-Oriented Annotations" section of this user guide.
+ <literal>@Oneway</literal> allows you to tag a method as oneway and when you invoke that method it runs in
+ the background. The problem with this example is that you can only run
+ <literal>void</literal> methods in
+ the background and cannot interact asynchronously with methods that return a value. You have no way of
+ obtaining the return value of an asynchronous call. Let's walk through an example of taking the oneway
+ aspect and adding a runtime API for that aspect so that application developers can obtain method return values
+ asynchronously.
+ </para>
+ <para>
+ The end goal of this example is to allow an application developer to tag a method as
+ <literal>@Asynchronous</literal>
+ have the method run in the background, but to provide an API so that the developer can obtain the value of a method
+ return asynchronously. What we'll use here is an introduction and mixin to provide an API to obtain a
+ <literal>java.util.concurrent.Future</literal> instance (from JDK 5.0 concurrent package) that will allow us to get access to the asynchronous
+ method's return value.
+ </para>
+ <para>Using the
+ <literal>@Asynchronous</literal> annotation
+ </para>
+ <programlisting>public class POJO
+{
+ @Asynchronous int someMethod() { ... }
+}</programlisting>
+ <para>
+ This is the interface we want to introduce to any class that has a method tagged as
+ <literal>@Asynchronous</literal>
+ </para>
+ <programlisting>public interface AsynchronousFacade
+{
+ java.util.concurrent.Future getLastFuture();
+}</programlisting>
+ <para>
+ So, the user would interact with this asynchronous aspect in the following way.
+ </para>
+ <programlisting>{
+ POJO pojo = new POJO();
+ AsynchronousFacade facade = (AsynchronousFacade)pojo;
+...
+ pojo.someMethod(); // invokes in background
+ Future future = facade.getLastFuture();
+... do other work...
+ // go back and get result. block until it returns.
+ int result = (Integer)future.get();
+}</programlisting>
+ <para>
+ The first thing we need to do is define the mixin that will provide
+ <literal>Futures</literal>. This mixin
+ should also have a private interface so that the asynchronous aspect has a way to set the current invocation's
+ future after it spawns the method invocation to the background. The mixin will be very very simple. It
+ will basically expose a
+ <literal>java.lang.ThreadLocal</literal> so that the Future can be set and acquired.
+ </para>
+ <programlisting>public class AsynchMixin implements AsynchronousFacade, FutureProvider
+{
+ private ThreadLocal currentFuture = new ThreadLocal();
+
+ public Future getLastFuture()
+ {
+ return (Future)currentFuture.get();
+ }
+
+ public void setFuture(Future future)
+ {
+ currentFuture.set(future);
+ }
+}</programlisting>
+ <para>
+ The
+ <literal>FutureProvider</literal> is an additional interface introduction that the aspect will use to
+ set the future when after it spawns the task in the background.
+ </para>
+ <programlisting>public interface FutureProvider
+{
+ public void setFuture(Future future);
+}</programlisting>
+ <para>
+ Next, let's look at the aspect that will implement the asynchronous behavior. The aspect is made up of an
+ advice that will create a
+ <literal>java.util.concurrent.Callable</literal> instance so that the current
+ method invocation will run in the background.
+ </para>
+ <programlisting>public class AsynchAspect
+{
+ ExecutorService executor = Executors.newCachedThreadPool();
+
+ public Object invokeAsynch(MethodInvocation invocation) throws Throwable
+ {
+ final Invocation copy = invocation.copy();
+ Future future = executor.submit( new Callable()
+ {
+ public Object call()
+ {
+ try
+ {
+ return copy.invokeNext();
+ }
+ catch (Throwable throwable)
+ {
+ return throwable;
+ }
+ }
+ });
+ FutureProvider provider = (FutureProvider)invocation.getTargetObject();
+ provider.setFuture(future);
+
+ return nullOrZero(invocation.getMethod().getReturnType());
+ }
+
+ private Object nullOrZero(Class type)
+ {
+ if (type.equals(long.class)) return 0;
+ //... other types ...
+ return null;
+ }
+}</programlisting>
+ <para>
+ The
+ <literal>invokeAsynch</literal> advice first copies the invocation. A copy copies the entire state
+ of the invocation objec and remembers exactly in the interceptor/advice chain to continue on when the
+ method is spawned off into a separate thread. The copy allows the current Java call stack to return while allowing
+ the copy to live in a separate thread and continue down the interceptor stack towards the actual method call.
+ </para>
+ <para>
+ After creating a callable and running the method in a separate thread, the advice gets the target object
+ from the invocation, and typecasts it to
+ <literal>FutureProvider</literal> so that it can make the
+ future available to the app developer.
+ </para>
+ <para>
+ So the mixin and aspect are written. The next thing to do is to define an advice binding so that when a method
+ is tagged as asynchronous, the asynch advice will be triggered, and the method will run in the background.
+ </para>
+ <programlisting>
+ <![CDATA[<aspect class="AsynchAspect" scope="PER_VM"/>
+<bind pointcut="execution(!static * *->@Asynchronous(..))">
+ <advice name="invokeAsynch" aspect="AsynchAspect"/>
+</bind>]]></programlisting>
+ <para>
+ After defining the aspect binding, we then come to the introduction definition itself. We want the introduction
+ to be added to any class that has any method tagged as
+ <literal>@Asynchronous</literal>. The JBoss AOP
+ pointcut expression language has a keyword
+ <literal>has</literal> to allow for this type of matching. Let's
+ look at the introduction binding.
+ </para>
+ <programlisting><![CDATA[<introduction expr="has(!static * *->@Asynchronous(..))">
+ <mixin>
+ <interfaces>AsynchronousFacade, FutureProvider</interfaces>
+ <class>AsynchMixin</class>
+ <construction>new AsynchMixin()</construction>
+ </mixin>
+</introduction>]]></programlisting>
+ <para>
+ The example is now complete. Introductions/mixins aren't solely limited to pseudo-multiple inheritance and the
+ asynch aspect is a great example of an aspect with a runtime API.
+ </para>
+ </sect1>
+
+</chapter>
+
+
+
+
Property changes on: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/introductions.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/maven.xml
===================================================================
--- projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/maven.xml (rev 0)
+++ projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/maven.xml 2008-02-19 16:06:12 UTC (rev 69936)
@@ -0,0 +1,285 @@
+<chapter id="maven">
+
+ <title>Building JBoss AOP with Maven2</title>
+ <para>
+ Since JBoss AOP requires either loadtime or compiletime weaving we need to customize maven a bit
+ to make it do what we want. JBoss AOP provides plugins to make this weaving as easy as possible.
+ </para>
+
+ <para>
+ The JBoss AOP plugin is named jbossaop and is provided under the maven2 jboss.org repository.
+ For the final releases use:
+ <programlisting><![CDATA[
+<repository>
+ <id>maven.jboss.org</id>
+ <name>JBoss Maven Repository</name>
+ <url>http://repository.jboss.com/maven2</url>
+</repository> ]]></programlisting>
+ If you want to use the snapshot releases use:
+ <programlisting><![CDATA[
+<repository>
+ <id>snapshots.jboss.org</id>
+ <name>JBoss Maven Snapshot Repository</name>
+ <url>http://snapshots.jboss.org/maven2</url>
+</repository>]]></programlisting>
+
+ The jbossaop maven plugin will provide all the aop dependencies needed to weave and run. There is no need
+ to include aop dependencies other than the plugin.
+
+ NOTE: The version used in these examples may be obsolete, please check the latest release for the reference
+ version instead of using the version in these examples.
+
+ </para>
+
+
+ <sect1 id="compiling" revision="1">
+ <title>AOP Compile with Maven2</title>
+ <para>
+ The aop compile plugin is configured to run after the default maven compile phase has ended. By default it
+ will try to find the jboss-aop.xml file in <literal>src/main/resources/jboss-aop.xml</literal>. It will also
+ try to weave every class in <literal>$project.build.outputDirectory</literal> (usually target/classes).
+ List of options:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>aoppaths</literal> - an array of possible jboss-aop.xml files. Default is
+ <literal>src/main/resources/jboss-aop.xml</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>verbose</literal> - if set to true it will provide debug information during the aop weaving. '
+ Default set to true.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>suppress</literal> - suppress when a class cannot be found that a class references.
+ This may happen if code in a class references something and the class is not in the classpath.
+ Default set to true.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>noopt</literal> - do not optimize the weaving. Default set to false.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>report</literal> - store the output to a file (<literal>aop-report.xml</literal>).
+ Default set to false.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>includeProjectDependency</literal> - if set to true all project dependencies will also
+ be included to the aop classpath. Only needed if a class inherits a class thats not defined in
+ the current module. Default set to false.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>classPath</literal> - classpath, by default set to null. If its set to null it will use
+ the plugin dependencies (and add project dependencies if <literal>includeProjectDependency</literal>
+ is set) + the output build path. Do not change this if you are not sure.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>aopClassPath</literal> - load xml files that adds aspects to the manager. Do not change this
+ if you are not sure. By default set to null.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>includes</literal> - an array of classes that will be weaved. Note that if this is specified
+ just the classes thats specified here will be weaved. Default set to null.
+ </para>
+ </listitem>
+ </itemizedlist>
+ There is a lot of options that can be set, but noone are mandatory (if they are mandatory
+ they have a default value set). The average user would moste likely only change <literal>aoppaths</literal>.
+ A more complete example would look like:
+ <programlisting><![CDATA[
+<plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifactId>maven-jbossaop-plugin</artifactId>
+ <version>1.0</version>
+ <executions>
+ <execution>
+ <id>compile</id>
+ <configuration>
+ <!-- if you want to include dependencies from the current module
+ (only needed if a class inherits a class thats not defined in this module
+ -->
+ <includeProjectDependency>true</includeProjectDependency>
+ <aoppaths>
+ <aoppath>src/main/resources/jboss-aop_test2.xml</aoppath>
+ <!-- for a second jboss-aop.xml file
+ <aoppath>src/main/resources/jboss-aop.xml</aoppath>
+ -->
+ </aoppaths>
+ <!-- You can specify to only aopc a specific set of classes
+ <includes>
+ <include>POJO.class</include>
+ </includes>
+ -->
+ </configuration>
+ <goals>
+ <goal>compile</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin> ]]></programlisting>
+ </para>
+ </sect1>
+
+ <sect1 id="compiletests" revision="1">
+ <title>AOP Compile tests with Maven2</title>
+ <para>
+ The only difference between aop compiling tests and non-tests are the name of the plugin. The options
+ are the same for tests and non-tests. A quick example:
+ <programlisting><![CDATA[
+<plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifactId>maven-jbossaop-plugin</artifactId>
+ <version>1.0</version>
+ <executions>
+ <execution>
+ <id>compile-test</id>
+ <configuration>
+ <aoppaths>
+ <aoppath>src/main/resources/jboss-aop_testcase.xml</aoppath>
+ </aoppaths>
+ </configuration>
+ <goals>
+ <goal>compile-test</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin> ]]></programlisting>
+ </para>
+ </sect1>
+
+ <sect1 id="running" revision="1">
+ <title>Running precompiled with Maven2</title>
+ <para>
+ JBoss aop run plugin is configured to run after the package phase. There are less options here than for
+ the compile step and they are very similar.
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>aoppaths</literal> - an array of possible jboss-aop.xml files. Default is
+ <literal>src/main/resources/jboss-aop.xml</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>includeProjectDependency</literal> - if set to true all project dependencies will also
+ be included to the aop classpath. Only needed if a class inherits a class thats not defined in
+ the current module. Default set to false.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>classPath</literal> - classpath, by default set to null. If its set to null it will use
+ the plugin dependencies (and add project dependencies if <literal>includeProjectDependency</literal>
+ is set) + the output build path. Do not change this if you are not sure.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>executable</literal> - the java class that will be executed
+ </para>
+ </listitem>
+ </itemizedlist>
+ A small example using default jboss-aop.xml:
+ <programlisting><![CDATA[
+<plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifactId>maven-jbossaop-plugin</artifactId>
+ <version>1.0.CR1</version>
+ <executions>
+ <execution>
+ <id>run</id>
+ <configuration>
+ <executable>Foo</executable>
+ </configuration>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin> ]]></programlisting>
+ </para>
+ </sect1>
+
+
+ <sect1 id="runningweaving" revision="1">
+ <title>Running loadtime weaving with Maven2</title>
+ <para>
+ Running a java application in loadtime weaving is almost identical to compile time (except that you dont need
+ to precompile it first). The only change is that we need an option to say that we want to run it loadtime.
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>loadtime</literal> - set it to true if you want loadtime weaving. Default is set to false.
+ </para>
+ </listitem>
+ </itemizedlist>
+ A small example:
+ <programlisting><![CDATA[
+<plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifactId>maven-jbossaop-plugin</artifactId>
+ <version>1.0.CR1</version>
+ <executions>
+ <execution>
+ <id>run</id>
+ <configuration>
+ <aoppaths>
+ <aoppath>src/main/resources/jboss-aop_testcase.xml</aoppath>
+ </aoppaths>
+ <loadtime>true</loadtime>
+ <executable>Test</executable>
+ </configuration>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin> ]]></programlisting>
+ </para>
+ </sect1>
+
+
+ <sect1 id="runningtests" revision="1">
+ <title>Running tests with Maven2</title>
+ <para>
+ Running tests with aop is a different matter since the maven tests plugin is rather complex.
+ But we can add the hooks we need to run it both compiletime and loadtime with the maven tests too.
+ An example on how to run a test thats been aop compiled:
+ <programlisting><![CDATA[
+<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <version>2.4</version>
+ <configuration>
+ <forkMode>always</forkMode>
+ <useSystemClassLoader>true</useSystemClassLoader>
+ <argLine>-Djboss.aop.path=src/main/resources/jboss-aop_testcase.xml</argLine>
+ </configuration>
+</plugin> ]]></programlisting>
+ </para>
+ <para>
+ To run it loadtime we only need to add the javaagent option to argLine. Like this:
+ <programlisting><![CDATA[
+ <argLine>-javaagent:${settings.localRepository}/org/jboss/jboss-aop/2.0.0.CR3/jboss-aop-2.0.0.CR3.jar -Djboss.aop.path=src/main/resources/jboss-aop_testcase.xml</argLine> ]]></programlisting>
+ - big thanks to henrik and finn for figuring out how to do this :)
+ Note again that the versions used here are just for a reference and to provide as examples. Check the JBoss AOP
+ homepage for the up-to-date versions.
+ </para>
+ </sect1>
+
+
+</chapter>
Added: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/terms.xml
===================================================================
--- projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/terms.xml (rev 0)
+++ projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/terms.xml 2008-02-19 16:06:12 UTC (rev 69936)
@@ -0,0 +1,86 @@
+<chapter id="terms">
+
+ <title>Terms</title>
+
+ <sect1 id="base-terms" revision="1">
+ <title>Overview</title>
+
+ <para>
+ The section defines some basic terms that will be used throughout this guide.
+ </para>
+
+ <para>
+
+ <variablelist spacing="compact">
+ <varlistentry>
+ <term>Joinpoint</term>
+ <listitem>
+ <para>
+ A joinpoint is any point in your java program. The call of a method. The execution of a constructor
+ the access of a field. All these are joinpoints. You could also think of a joinpoint as a particular
+ Java event. Where an event is a method call, constructor call, field access etc...
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Invocation</term>
+ <listitem>
+ <para>
+ An Invocation is a JBoss AOP class that encapsulates what a joinpiont is at runtime. It could
+ contain information like which method is being called, the arguments of the method, etc...
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Advice</term>
+ <listitem>
+ <para>
+ An advice is a method that is called when a particular joinpoint is executed, i.e., the behavior
+ that is triggered when a method is called. It could also be thought of as the code that does the
+ interception. Another analogy is that an advice is an "event handler".
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Pointcut</term>
+ <listitem>
+ <para>
+ Pointcuts are AOP's expression language. Just as a regular expression matches strings, a pointcut
+ expression matches a particular joinpoint.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Introductions</term>
+ <listitem>
+ <para>
+ An introduction modifies the type and structure of a Java class. It can be used to force
+ an existing class to implement an interface or to add an annotation to anything.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Aspect</term>
+ <listitem>
+ <para>
+ An Aspect is a plain Java class that encapsulates any number of advices, pointcut definitions,
+ mixins, or any other JBoss AOP construct.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Interceptor</term>
+ <listitem>
+ <para>
+ An interceptor is an Aspect with only one advice named "invoke". It is a specific interface
+ that you can implement if you want your code to be checked by forcing your class to implement an interface.
+ It also will be portable and can be reused in other JBoss environments like EJBs and JMX MBeans.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect1>
+
+</chapter>
+
Property changes on: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/terms.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/testing.xml
===================================================================
--- projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/testing.xml (rev 0)
+++ projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/testing.xml 2008-02-19 16:06:12 UTC (rev 69936)
@@ -0,0 +1,363 @@
+<chapter id="testing">
+
+ <title>Testing with AOP</title>
+ <para>
+ In the previous sections we talked more about using AOP to build and design applications and services. This chapter
+ focuses on how you can use AOP to test your applications.
+ </para>
+
+ <sect1 id="exception" revision="1">
+ <title>Testing Exception Handling</title>
+ <para>
+ The sign of a well design application is how gracefully it can handle errors. To be able to handle errors
+ gracefully in all circumstances though requires lots and lots of testing. You have to test that your application
+ is catching and handling exceptions carefully. Sometimes its hard to produce error conditions because your
+ code is interacting with a third party library, or third party service like a database or something. You can
+ write complex mock objects in these scenarios, but let's see how you can create these error conditions in an
+ easier and more flexible way with JBoss AOP.
+ </para>
+ <para>
+ The example scenario we'll give is an application that needs to be tested on whether or not it handles an
+ Oracle database deadlock exception gracefully. What we'll do is write an advice that intercepts calls
+ to <literal>java.sql.Statement</literal> execute methods and always throw a SQLException with the appropriate
+ deadlock error code.
+ </para>
+ <programlisting>public class SQLDeadlockExceptionInjector
+{
+ public Object throwDeadlock(Invocation invocation) throws Throwable
+ {
+ throw new SQLException("Oracle Deadlock", "RETRY", ORACLE_DEADLOCK_CODE);
+ }
+}</programlisting>
+ <para>
+ What's great about the JBoss AOP approach to testing exception handling is that you can use it on a live system
+ and change how your tests run by deploying and/or undeploying certain aspects at runtime during your automatic testing
+ phase. Let's apply this aspect.
+ </para>
+ <programlisting><![CDATA[<aspect class="SQLDeadlockExceptionInjector/>
+<bind pointcut="call(* $instanceof{java.sql.Statement}->execute*(..))">
+ <advice name="throwDeadlock" aspect="SQLDeadlockExceptionInjector"/>
+</bind>]]></programlisting>
+ <para>
+ So, the above binding will throw a deadlock exception every time an execute method of a Statement is invoked.
+ This example is a bit limited though. Maybe not all code paths can handle deadlock exceptions, or they
+ should not handle deadlock exceptions and just rollback and such. The pointcut expression language allows
+ you to do more fine grain application of this particular exception aspect. Let's say that only our
+ BankAccount class is designed to successfully recover from a Oracle deadlock exception. We can change the
+ pointcut expression to be as follows:
+ </para>
+ <programlisting><![CDATA[<bind pointcut="call(* $instanceof{java.sql.Statement}->execute*(..)) AND /
+ within(BankAccount)">
+ <advice name="throwDeadlock" aspect="SQLDeadlockExceptionInjector"/>
+</bind>]]></programlisting>
+ <para>
+ The difference in this expression is the <literal>within</literal>. It is saying that any call to execute
+ methods that are within the BankAccount class. We can even get more fine grained than that. We can even
+ specify which methods within BankAccount the exception aspect should be applied to.
+ </para>
+ <programlisting><![CDATA[<bind pointcut="call(* $instanceof{java.sql.Statement}->execute*(..)) AND /
+ withincode(void BankAccount->withdraw(double))">
+ <advice name="throwDeadlock" aspect="SQLDeadlockExceptionInjector"/>
+</bind>]]></programlisting>
+ <para>
+ In the above listing the <literal>withincode</literal> keyword specificies to match the calling of any execute
+ method that is invoked within the <literal>BankAccount.withdraw()</literal> method.
+ </para>
+ <para>
+ AOP gives you a lot of flexibilty in testing error conditions, JBoss AOP in particular. Because JBoss AOP
+ allows you to hotdeploy (deploy/undeploy) aspects at runtime it is very easy to integrate these types of tests
+ into a live system instead of having to go through the pain of writing complex mock objects and running your
+ applications outside of the application server environment.
+ </para>
+
+ </sect1>
+
+ <sect1 id="testing1" revision="1">
+ <title>Injecting Mock Objects</title>
+ <para>
+ This section was taken from Staale Pedersen's article at <literal>http://folk.uio.no/staalep/aop/testing.html</literal>.
+ Thanks Staale for putting together some ideas on how you can use JBoss AOP for use in unit testing.
+ </para>
+ <para>
+ The use of unit testing has increased tremendously lately, and many developers have seen the increase in quality
+ and speed that comes from having a comprehensive unit-test suite. As the use of unit testing has increased, so
+ have the number of situations where writing test are troublesome or maybe impossible. A common problem with
+ writing tests is that it can require large amount of setup code. Testing code that rely on a remote system or
+ data access from file/db/net can be almost impossible to implement. But with the help of JBoss AOP and mock
+ objects this is no longer any problem.
+ </para>
+ <para>
+ In this example we will examine a common situation where writing unit tests is difficult, but desirable. For
+ simplicity we will use POJO's, but the example can easily be translated for a large J2EE application.
+ </para>
+ <sect2 id="required" revision="1">
+ <title>Required Knowledge</title>
+ <para>
+ This article focuses on unit testing with JUnit using Mock Maker and of course JBoss AOP. Knowledge of JUnit
+ and JBoss AOP is required, Mock Maker is used, but thoroughly knowledge is not required. The example source
+ code is compiled with Ant, env JUNIT_HOME must be set (mock maker and JBoss AOP jars are included in the
+ example source).
+ </para>
+ </sect2>
+ <sect2 id="problem" revision="1">
+ <title>The Problem</title>
+ <para>
+ The situation is common, we have a Bank application that manages Customers which can have one or more
+ BankAccounts. The Bank has different business methods to calculate interest, accept loans, etc. (in
+ production code this would be large and complex methods.) We want to write tests for the Bank's business
+ methods to make sure they work as intended and that we don't introduce bugs if we refactor, extend, modify
+ etc. The Bank has three business methods.
+ </para>
+ <programlisting><![CDATA[package bank;
+
+import java.util.ArrayList;
+
+import customer.*;
+
+public class BankBusiness {
+
+ private BankAccountDAO bankAccountDAO;
+
+ public BankBusiness() {
+ try {
+ bankAccountDAO = BankAccountDAOFactory.getBankAccountDAOSerializer();
+ }
+ catch(Exception e) {
+ System.out.println(e.getMessage());
+ }
+ }
+
+ public boolean creditCheck(Customer c, double amount) {
+ return (getSumOfAllAccounts(c) < amount * 0.4);
+ }
+
+ public double calculateInterest(BankAccount account) {
+ if(account.getBalance() < 1000)
+ return 0.01;
+ else if(account.getBalance() < 10000)
+ return 0.02;
+ else if(account.getBalance() < 100000)
+ return 0.03;
+ else if(account.getBalance() < 1000000)
+ return 0.05;
+ else
+ return 0.06;
+ }
+
+ public double getSumOfAllAccounts(Customer c) {
+ double sum = 0;
+ if(c.getAccounts().size() < 1)
+ return sum;
+ else {
+ for(int i=0; i < c.getAccounts().size(); i++) {
+ BankAccount a =
+ bankAccountDAO.getBankAccount( ((Long) c.getAccounts().get(i)).longValue());
+ if(a != null)
+ sum += a.getBalance();
+ }
+ }
+ return sum;
+ }
+
+}]]></programlisting>
+ <para>
+ <literal>calculateInterest(BankAccount b)</literal> can easily be tested since it is only dependent on the
+ object it recieves as a parameter.
+ </para>
+ <para>
+ <literal>creditCheck(Customer c, double amount)</literal> and <literal>getSumOfAllAccounts(Customer)</literal>
+ are more complicated since they are data dependent. It uses a DAO layer to fetch all BankAccounts for a
+ specified customer. The test should not be dependent of the DAO implementation since its goal is to check
+ the business logic, not the DAO layer. In this example the DAO implementation is a simple serializer, but it
+ could easily be an Entity beans, Hibernate, etc..
+ </para>
+ </sect2>
+ <sect2 id="mock" revisition="1">
+ <title>Mock Objects</title>
+ <para>
+ Mock objects are objects that implement no logic of their own and are used to replace the parts of the
+ system with which the unit test interacts. In our case it is the DAO layer we would like to mock. We could
+ write our own mock implementation, but mock maker does a very good job of autogenerating the mock for us.
+ </para>
+ <programlisting><![CDATA[package bank;
+/**
+ * @mock
+ */
+public interface BankAccountDAO {
+
+ public void saveBankAccount(BankAccount b) throws Exception;
+
+ public BankAccount getBankAccount(long a);
+
+ public void removeBankAccount(BankAccount b) throws Exception;
+}]]></programlisting>
+ <para>
+ With the <literal>@mock</literal> tag in the header mock maker generates the mock. In the example the ant target
+ <literal>ant generate-mocks</literal> generates the mock implementation of BankAccount. Now we need to
+ replace the DAO call to return our mock objects instead of the DAO implementation.
+ </para>
+ </sect2>
+ <sect2 id="aop" revision="1">
+ <title>AOP with Mocks</title>
+ <para>
+ - and intercepting a method invocation is just what aop does best. Our jboss-aop.xml file:
+ </para>
+ <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<aop>
+ <bind pointcut="execution(public static bank.BankAccountDAO bank.BankAccountDAOFactory->getBankAccountDAO*())">
+ <interceptor class="bank.BankAccountDAOInterceptor"/>
+ </bind>
+</aop>]]></programlisting>
+ <para>
+ The pointcut expression intercepts the factorycall bank.BankAccountDAOFactory.getBankAccountDAO*() and
+ calls the interceptor bank.BankAccountDAOInterceptor.
+ </para>
+ <programlisting><![CDATA[package bank;
+
+import org.jboss.aop.joinpoint.Invocation;
+import org.jboss.aop.joinpoint.MethodInvocation;
+import org.jboss.aop.advice.Interceptor;
+
+import util.MockService;
+
+public class BankAccountDAOInterceptor implements Interceptor {
+
+ public String getName() { return "BankAccountDAOInterceptor"; }
+
+ public Object invoke(Invocation invocation) throws Throwable {
+ try {
+ MockService mockService = MockService.getInstance();
+
+ Object mock = mockService.getMockForInterface( "BankAccountDAO");
+ if(mock == null) {
+ System.out.println("ERROR: BankAccountDAOInterceptor didnt find class!");
+ // this will probably fail, but its the sainest thing to do
+ return invocation.invokeNext();
+ }
+
+ return mock;
+ }
+ finally {
+ }
+ }
+}]]></programlisting>
+ <para>
+ Instead of returning <literal>invocation.invokeNext()</literal>, we ignore the invocation stack since we want
+ to replace the invocation call with a mock implementation. The interceptor receives the invocation and get
+ an instance of the singleton MockService. The use of MockService may not be clear, but we want the test to
+ instanciate the mock objects. That way, the test can easily modify the input to the methods we want to test.
+ The test creates an object of the mock and put it into the MockService with the interface name as the key.
+ The Interceptor then tries to get the mock from MockService and return it.
+ </para>
+ <programlisting><![CDATA[package util;
+
+import java.util.Hashtable;
+import java.util.Iterator;
+import java.util.Map;
+import java.util.Set;
+
+public class MockService {
+
+ private static MockService instance = new MockService();
+
+ private Map mockReferences = null;
+
+ protected MockService() {
+ mockReferences = new Hashtable();
+ }
+
+ public static MockService getInstance() {
+ return instance;
+ }
+
+ public void addMock(String c, Object mock) {
+ mockReferences.put(c, mock);
+ }
+
+ public Object getMockForInterface(String myKey) {
+ Set keys = mockReferences.keySet();
+
+ for (Iterator iter = keys.iterator(); iter.hasNext();) {
+ String key = (String) iter.next();
+ if(myKey.equals(key)) {
+ return mockReferences.get(key);
+ }
+ }
+ return null;
+ }
+
+}]]></programlisting>
+ </sect2>
+ <para>
+ Everyting is now in place to write the test. Note that much of this setup code is written once and it will be
+ reused by all similar tests. Then the test: BankBusinessTestCase
+ </para>
+ <programlisting><![CDATA[package bank;
+
+import junit.framework.TestCase;
+
+import customer.Customer;
+import util.MockService;
+
+public class BankBusinessTestCase extends TestCase {
+
+ private MockBankAccountDAO mock;
+ private Customer customer;
+
+ public BankBusinessTestCase(String name) {
+ super( name);
+ }
+
+ public void setUp() {
+ mock = new MockBankAccountDAO();
+
+ BankAccount account = new BankAccount( 10);
+ account.setBalance( 100);
+ BankAccount account2 = new BankAccount( 11);
+ account2.setBalance( 500);
+
+ mock.setupGetBankAccount( account);
+ mock.setupGetBankAccount( account2);
+
+ MockService mockService = MockService.getInstance();
+ mockService.addMock( "BankAccountDAO", mock);
+
+ customer = new Customer("John", "Doe");
+ customer.addAccount( new Long(10));
+ customer.addAccount( new Long(11));
+ }
+
+ public void testSumOfAllAccounts() {
+ BankBusiness business = new BankBusiness();
+ double sum = business.getSumOfAllAccounts( customer);
+ assertEquals((double) 600, sum);
+ System.out.println("SUM: "+sum);
+ }
+}]]></programlisting>
+ <para>
+ To compile and run the test we call ant compile test. Output from the test:
+ </para>
+ <programlisting><![CDATA[test-bankbusiness:
+ [junit] .SUM: 600.0
+ [junit] Time: 0,23
+ [junit] OK (1 test)]]></programlisting>
+ <para>
+ The testresult was exactly what we expected.
+ </para>
+ <para>
+ With the the use of AOP we can test every aspect of our code. This example show the limits of object-oriented
+ programming (OOP) compared to AOP. It must be pointed out that it is possible to write these tests without AOP,
+ but it would require to edit production code just to make the tests pass.
+ </para>
+ <para>
+ The approach in this example can easily be used to mock SessionBeans instead of a DAO layer.
+ Theoretically, we can test all of the business methods in a large J2EE application outside the container.
+ This would greatly increase quality and speed during software development.
+ </para>
+ </sect1>
+
+</chapter>
+
+
+
+
Property changes on: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/testing.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/toc.xml
===================================================================
--- projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/toc.xml (rev 0)
+++ projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/toc.xml 2008-02-19 16:06:12 UTC (rev 69936)
@@ -0,0 +1 @@
+<toc/>
Added: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/what.xml
===================================================================
--- projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/what.xml (rev 0)
+++ projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/what.xml 2008-02-19 16:06:12 UTC (rev 69936)
@@ -0,0 +1,185 @@
+<chapter id="what">
+
+ <title>What Is Aspect-Oriented Programming?</title>
+
+ <sect1 id="whatif" revision="1">
+ <title>What is it?</title>
+ <para>
+ An aspect is a common feature that's typically scattered across methods, classes, object hierarchies, or even
+ entire object models. It is behavior that looks and smells like it should have structure, but you can't find
+ a way to express this structure in code with traditional object-oriented techniques.
+ </para>
+ <para>
+ For example, metrics is one common aspect. To generate useful logs from your application, you have to
+ (often liberally) sprinkle informative messages throughout your code. However, metrics is something that your
+ class or object model really shouldn't be concerned about. After all, metrics is irrelevant to your actual
+ application: it doesn't represent a customer or an account, and it doesn't realize a business rule.
+ It's simply orthogonal.
+ </para>
+ <para>
+ In AOP, a feature like metrics is called a crosscutting concern, as it's a behavior that "cuts" across multiple
+ points in your object models, yet is distinctly different. As a development methodology, AOP recommends that
+ you abstract and encapsulate crosscutting concerns.
+ </para>
+ <para>
+ For example, let's say you wanted to add code to an application to measure the amount of time it would take to
+ invoke a particular method. In plain Java, the code would look something like the following.
+ </para>
+ <programlisting>public class BankAccountDAO
+{
+ public void withdraw(double amount)
+ {
+ long startTime = System.currentTimeMillis();
+ try
+ {
+ // Actual method body...
+ }
+ finally
+ {
+ long endTime = System.currentTimeMillis() - startTime;
+ System.out.println("withdraw took: " + endTime);
+ }
+ }
+}</programlisting>
+ <para>
+ While this code works, there are a few problems with this approach:
+ </para>
+ <orderedlist>
+ <listitem>
+ It's extremely difficult to turn metrics on and off, as you have to manually add the code in the
+ try>/finally block to each and every method or constructor you want to benchmark.
+ </listitem>
+ <listitem>
+ The profiling code really doesn't belong sprinkled throughout your application code. It makes your code
+ bloated and harder to read, as you have to enclose the timings within a try/finally block.
+ </listitem>
+ <listitem>
+ If you wanted to expand this functionality to include a method or failure count, or even to register these
+ statistics to a more sophisticated reporting mechanism, you'd have to modify a lot of different files (again).
+ </listitem>
+ </orderedlist>
+ <para>
+ This approach to metrics is very difficult to maintain, expand, and extend, because it's dispersed throughout
+ your entire code base. And this is just a tiny example! In many cases, OOP may not always be the best way to
+ add metrics to a class.
+ </para>
+ <para>
+ Aspect-oriented programming gives you a way to encapsulate this type of behavior functionality. It allows you
+ to add behavior such as metrics "around" your code. For example, AOP provides you with programmatic control to
+ specify that you want calls to BankAccountDAO to go through a metrics aspect before executing the actual body
+ of that code.
+ </para>
+ </sect1>
+ <sect1 id="create" revision="1">
+ <title>Creating Aspects in JBoss AOP</title>
+ <para>
+ In short, all AOP frameworks define two things: a way to implement crosscutting concerns, and a
+ programmatic construct -- a programming language or a set of tags -- to specify how you want to apply those
+ snippets of code.
+ </para>
+ <para>
+ Let's take a look at how JBoss AOP, its cross-cutting concerns, and how you can implement a metrics aspect
+ in JBoss.
+ </para>
+ <para>
+ The first step in creating a metrics aspect in JBoss AOP is to encapsulate the metrics feature in its own
+ Java class. Listing Two extracts the try/finally block in Listing One's BankAccountDAO.withdraw() method
+ into Metrics, an implementation of a JBoss AOP Interceptor class.
+ </para>
+ <para>Listing Two: Implementing metrics in a JBoss AOP Interceptor</para>
+ <programlisting>01. public class Metrics implements org.jboss.aop.advice.Interceptor
+02. {
+03. public Object invoke(Invocation invocation) throws Throwable
+04. {
+05. long startTime = System.currentTimeMillis();
+06. try
+07. {
+08. return invocation.invokeNext();
+09. }
+10. finally
+11. {
+12. long endTime = System.currentTimeMillis() - startTime;
+13. java.lang.reflect.Method m = ((MethodInvocation)invocation).method;
+14. System.out.println("method " + m.toString() + " time: " + endTime + "ms");
+15. }
+16. }
+17. }</programlisting>
+ <para>
+ Under JBoss AOP, the Metrics class wraps withdraw(): when calling code invokes withdraw(), the AOP
+ framework breaks the method call into its parts and encapsulates those parts into an Invocation object.
+ The framework then calls any aspects that sit between the calling code and the actual method body.
+ </para>
+ <para>
+ When the AOP framework is done dissecting the method call, it calls Metric's invoke method at line 3.
+ Line 8 wraps and delegates to the actual method and uses an enclosing try/finally block to perform the
+ timings. Line 13 obtains contextual information about the method call from the Invocation object,
+ while line 14 displays the method name and the calculated metrics.
+ </para>
+ <para>
+ Having the metrics code within its own object allows us to easily expand and capture additional
+ measurements later on. Now that metrics are encapsulated into an aspect, let's see how to apply it.
+ </para>
+ </sect1>
+ <sect1 id="apply" revision="1">
+ <title>Applying Aspects in JBoss AOP</title>
+ <para>
+ To apply an aspect, you define when to execute the aspect code. Those points in execution are called
+ pointcuts. An analogy to a pointcut is a regular expression. Where a regular expression matches strings,
+ a pointcut expression matches events/points within your application. For example, a valid pointcut
+ definition would be "for all calls to the JDBC method executeQuery(), call the aspect that verifies SQL syntax."
+ </para>
+ <para>
+ An entry point could be a field access, or a method or constructor call. An event could be an exception
+ being thrown. Some AOP implementations use languages akin to queries to specify pointcuts. Others use tags.
+ JBoss AOP uses both. Listing Three shows how to define a pointcut for the metrics example.
+ </para>
+ <para>Listing Three: Defining a pointcut in JBoss AOP</para>
+ <programlisting><![CDATA[1. <bind pointcut="public void com.mc.BankAccountDAO->withdraw(double amount)">
+2. <interceptor class="com.mc.Metrics"/>
+3. </bind >
+
+4. <bind pointcut="* com.mc.billing.*->*(..)">
+5. <interceptor class="com.mc.Metrics"/>
+6. </bind >]]></programlisting>
+ <para>
+ Lines 1-3 define a pointcut that applies the metrics aspect to the specific method BankAccountDAO.withdraw().
+ Lines 4-6 define a general pointcut that applies the metrics aspect to all methods in all classes in the
+ com.mc.billing package.
+ </para>
+ <para>
+ There is also an optional annotation mapping if you do not like XML. See our Reference Guide for more information.
+ </para>
+ <para>
+ JBoss AOP has a rich set of pointcut expressions that you can use to define various points/events in your
+ Java application so that you can apply your aspects. You can attach your aspects to a specific Java class
+ in your application or you can use more complex compositional pointcuts to specify a wide range of classes
+ within one expression.
+ </para>
+ <para>
+ With AOP, as this example shows, you're able to pull together crosscutting behavior into one object and
+ apply it easily and simply, without polluting and bloating your code with features that ultimately don't
+ belong mingled with business logic. Instead, common crosscutting concerns can be maintained and extended
+ in one place.
+ </para>
+ <para>
+ Notice too that the code within the BankAccountDAO class has no idea that it's being profiled. This is what
+ aspect-oriented programmers deem orthogonal concerns. Profiling is an orthogonal concern. In the OOP code
+ snippet in Listing One, profiling was part of the application code. With AOP, you can remove that code.
+ A modern promise of middleware is transparency, and AOP (pardon the pun) clearly delivers.
+ </para>
+ <para>
+ Just as important, orthogonal behavior could be bolted on after development. In Listing One, monitoring
+ and profiling must be added at development time. With AOP, a developer or an administrator can (easily)
+ add monitoring and metrics as needed without touching the code. This is a very subtle but significant
+ part of AOP, as this separation (obliviousness, some may say) allows aspects to be layered on top of or
+ below the code that they cut across. A layered design allows features to be added or removed at will.
+ For instance, perhaps you snap on metrics only when you're doing some benchmarks, but remove it for production.
+ With AOP, this can be done without editing, recompiling, or repackaging the code.
+ </para>
+ </sect1>
+
+</chapter>
+
+
+
+
Property changes on: projects/aop/trunk/aop/docs/reference/aopuserguide/en/modules/what.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/aop/trunk/aop/docs/reference/aopuserguide/pom.xml
===================================================================
--- projects/aop/trunk/aop/docs/reference/aopuserguide/pom.xml (rev 0)
+++ projects/aop/trunk/aop/docs/reference/aopuserguide/pom.xml 2008-02-19 16:06:12 UTC (rev 69936)
@@ -0,0 +1,19 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>org.jboss</groupId>
+ <artifactId>documentation</artifactId>
+ <version>1.0</version>
+ </parent>
+
+ <groupId>org.jboss.aop</groupId>
+ <artifactId>aop-user-guide-${translation}</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>jdocbook</packaging>
+ <name>AOP_User_Guide_(${translation})</name>
+
+</project>
More information about the jboss-cvs-commits
mailing list