Building JBoss AOP Applications

Building JBoss AOP applications is slightly different from building plain Java applications because the aspects and advices need to be instrumented into the compiled Java bytecode. For example, if an advice is bound to a method invocation joinpoint, the AOP instrumentation process would modify the joinpoint bytecode to call out to the advice method with the properly composed invocation object as an argument.

Compiling to Bytecode

The first step in building a JBoss AOP application is to compile all the classes, including the aspect classes, to bytecode by using the regular javac utility. If you use JDK 5.0 and the J2SE 5.0style annotation, the annotation is automatically compiled into the bytecode class files.

Compiling Annotations

You can skip this step if you use Java annotations with the JDK 5.0. However, if you want to use JBoss AOP annotations with JDK 1.4, you have to embed the annotations in the JavaDoc comments. They are not processed by the javac compiler. You have to use an annotation compiler provided by JBoss AOP to process the source code. The annotation compiler can directly add annotations to the bytecode class files or generate the annotation data in a separate XML file called metadata.xml. The following example compiles the annotation in the Foo.java file into the Foo.class file:

annotationc <classpath of the Foo.class file> -bytecode Foo.java

The following example compiles the annotation into a metadata.xml file in the current directory and does not alter the Foo.class file. The metadata.xml file can be used later in the AOP bytecode instrumentation process.

annotationc <classpath> -xml Foo.java

You can also run the annotation compiler within an Ant build script. The following example modifies the Java bytecode class files directly to add annotations:

 <taskdef name="annotationc"          classname="org.jboss.aop.ant.AnnotationC"          classpathref="jboss.aop.classpath" /> <target name="annotate">   <annotationc compilerclasspathref="classpath"                classpath="path/to/classfile"                bytecode="true">     <src path="."/>   </annotationc> </target> 

Note

This book builds applications using Ant, so the Ant version of the annotation compiler is used.

AOP Instrumentation

The AOP instrumentation process modifies the Java bytecode to add runtime hooks around pointcuts. Those hooks collect reflection information and invoke advices. The aopc utility in JBoss AOP instruments the bytecode offline for JDK 1.4. If you use JDK 5.0, you have to replace all the aopc below to aopc15. It takes a pointcut's definition from the jboss-aop.xml file or the metadata.xml file or the annotation tags already embedded in the bytecode by the annotation compiler. The following example shows how to invoke aopc from the command line with an associated jboss-aop.xml file:

aopc <classpath> -aoppath jboss-aop.xml Foo.class

If both jboss-aop.xml and metadata.xml files are present, you can put them in one directory and pass the directory name to aopc. In fact, all the *-aop.xml files in this directory will be treated as jboss-aop.xml by the aopc compiler:

 aopc <classpath> -aoppath <directory to XML files> Foo.class aopc <classpath> -aopclasspath <classpath to annotated aspect classes> Foo.class 

The following example shows how to invoke aopc within an Ant build script:

 <taskdef name="aopc"          classname="org.jboss.aop.ant.AopC"          classpathref="jboss.aop.classpath" /> <target name="aopc">   <aopc compilerclasspathref="classpath" verbose="true">     <classpath path="${classes.dir}"/>     <src path="${classes.dir}"/>     <aoppath path="jboss-aop.xml"/>     <aopclasspath path="aspects.jar"/>   </aopc> </target> 

The aopc instrumented bytecode can run directly in any JVM. Another option is to instrument the bytecode at the class load time. This way, you do not need to run the separate aopc program. In fact, if you use JDK 5.0style annotations or do not use annotations, you do not even need to run the annotatec program. The JBoss application server can be configured to instrument AOP bytecode at class load time (see the "Configuring the AOP Service" section, later in this chapter).