Chapter 9. Building and Compiling Aspectized Java
Prev   Next

Chapter 9. Building and Compiling Aspectized Java

9.1. Instrumentation modes

JBoss AOP works by instrumenting the classes you want to run. This means that modifications to the bytecode are made in order to add extra information to the classes to hook into the AOP library. JBoss AOP allows for two types of instrumentation

  • Precompiled - The classes are instrumented in a separate aop compilation step before they are run.
  • Loadtime - The classes are instrumented when they are first loaded.

This chapter describes the steps you need to take to precompile your classes with the aop precompiler.

9.2. Ant Integration

JBoss AOP comes with an ant task that you can use for precompiling your classes with the aop precompiler. An example build.xml file is the basis for the explanation. (It is quite similar to the one used in the previous chapter.) There will be differences in the build.xml file if you are using JDK 1.4.2 or JDK 5.0, these are outlined below: 

<?xml version="1.0" encoding="UTF-8"?>

<project default="compile" name="JBoss/AOP">
   <target name="prepare">

Define the source directory, and the directory to compile classes to. If you're not fussy, they can point to the same directory. 

         <property name="src.dir" value="PATH TO YOUR SOURCE DIR">
         <property name="classes.dir" value="PATH TO YOUR DIR FOR COMPILED CLASSES">

Include the jars AOP depends on, these are common to all JDK's 

         <path id="javassist.classpath">
            <pathelement path="../../../javassist.jar"/>
         </path>

         <path id="trove.classpath">
            <pathelement path="../../../trove.jar"/>
         </path>

         <path id="concurrent.classpath">
            <pathelement path="../../../concurrent.jar"/>
         </path>

         <path id="jboss.common.classpath">
            <pathelement path="../../../jboss-common.jar"/>
         </path>

         <path id="lib.classpath">
            <path refid="javassist.classpath"/>
            <path refid="trove.classpath"/>
            <path refid="jboss.aop.classpath"/>
            <path refid="jboss.common.classpath"/>
            <path refid="concurrent.classpath"/>
         </path>

This snippet shows what to do for JDK 1.4. It will also work with JDK 5.0 if your classes do not use JDK 5.0 style annotations and enums: 

         <!--                  JDK version 1.4.2                         -->
         <!-- Do not include this if using JDK 1.5 with annotations!!!!  -->

         <path id="jboss.aop.classpath">
            <pathelement path="../../../jboss-aop.jar"/>
         </path>

         <!--            JDK version 1.4.2 - END                         -->

This snippet shows what to do for JDK 5.0 if you are using JDK 5.0 annotations: 

         <!--            JDK version 1.5                                 -->
         <!-- Do not include this if using JDK 1.4.2!!!!                 -->

         <path id="jboss.aop.classpath">
            <pathelement path="../../../jboss-aop-jdk15.jar"/>
         </path>

         <!--            JDK version 1.5 - END                           -->

(You should only use one of the two previous snippets for setting up jboss.aop.classpath)

Now we set up the full classpath of all the needed libraries: 

         <path id="classpath">
            <path refid="lib.classpath"/>
            <path refid="jboss.aop.classpath"/>
         </path id="classpath">

Define the org.jboss.aop.ant.AopC ant aop precompiler task: 

         <taskdef name="aopc" classname="org.jboss.aop.ant.AopC"
               classpathref="jboss.aop.classpath"/>
         </target>
         

>
            <target name="compile" depends="prepare">

Compile the files (from the source directory to the compiled classes directory: 

         <javac srcdir="${src.dir}"
                destdir="${classes.dir}"
                debug="on"
                deprecation="on"
                optimize="off"
                includes="**">
            <classpath refid="classpath"/>
         </javac>

Now use the ant aop precompiler task, it reads the files from the 

         <aopc compilerclasspathref="classpath" verbose="true">
            <classpath path="${classes.dir}"/>
            <src path="${classes.dir}"/>
            <include name="**/*.class"/>
            <aoppath path="jboss-aop.xml"/>
            <aopclasspath path="aspects.jar"/>
         </aopc>

If you are using JDK 1.4.2 and wish to use annotations, you need to define the org.jboss.aop.ant.AnnotationC ant task, and run that BEFORE you invoke the org.jboss.aop.ant.AopC task. How to do this is shown in the previous chapter.

The org.jboss.aop.ant.AopC ant task takes several parameters.

  • compilerclasspath or compilerclasspathref - These are interchangable, and represent the jars needed for the aop precompiler to work. The compilerclasspath version takes the paths of the jar files, and the compilerclasspathref version takes the name of a predefined ant path. They can be specified as attributes of aopc, as shown above. compilerclasspath can also be specified as a child element of aopc, in which case you can use all the normal ant functionality for paths (e.g. fileset).
  • classpath or classpathref - Path to the compiled classes to be instrumented. The classpath version takes the path of the directory, and the classpathref version takes the name of a predefined ant path. They both be specified as attributes of aopc. classpath can also be specified as a child element of aopc, as shown above, in which case you can use all the normal ant functionality for paths (e.g. fileset). The full classpath of the underlying java process will be classpath + compilerclasspath.
  • src - A directory containing files to be transformed. You can use multiple src elements to specify more that one root directory for transformation.
  • include - This is optional and it serves as a filter to pick out which files within src should be transformed. You can use wildcards within the name expression, and you can also use multiple include elements.
  • verbose - Default is false. If true, verbose output is generated, which comes in handy for diagnosing unexpected results.
  • report - Default is false. If true, the classes are not instrumented, but a report called aop-report.xml is generated which shows all classes that have been loaded that pertain to AOP, what interceptors and advices that are attached, and also what metadata that has been attached. One particularly useful thing is the unbounded section. It specifys all bindings that are not bound. It allows you to debug when you might have a typo in one of your XML deployment descriptors.

    Report generation works on the instrumented classes, so to get valid data in your report, you have to to make two passes with aopc. First you run aopc with report="false" to instrument the classes, and then you run aopc with report="true" to generate the report.
  • aoppath - The path of the *-aop.xml file containing the xml configuration of your bindings. Files or Directories can be specified. If it is a directory, JBoss AOP will take all aop.xml files from that directory. This gets used for the jboss.aop.path optional system property which is described in the "Command Line" section. If you have more than one xml file, for example if you have both a "normal" jboss-aop.xml file, and a metadata-aop.xml file having used the JDK 1.4.2 annotation compiler, you can specify these as follows: 
                   <aoppath>
               <pathelement path="jboss-aop.xml"/>
               <pathelement path="metadata-aop.xml"/>
               <pathelement path="xmldir"/>
               </aoppath>
  • aopclasspath - This should mirror your class path and contain all JARs/directories that may have annotated aspects (Ses Chapter "Annotated Bindings"). The AOPC compiler will browser each class file in this path to determine if any of them are annotationed with @Aspect. This gets used for the jboss.aop.class.path optional system property which is described in the "Command Line" section. If you have more than one jar file, you can specify these as follows: 
                   <aopclasspath>
               <pathelement path="aspects.jar"/>
               <pathelement path="foo.jar"/>
               </aopclasspath>
  • maxsrc - The ant task expands any directories in src to list all class files, when creating the parameters for the java command that actually performs the compilation. On some operating systems there is a limit to the length of vaid command lines. The default value for maxsrc is 1000. If the total length of all the files used is greater than maxsrc, a temporary file listing the files to be transformed is used and passed in to the java command instead. If you have problems running the aopc task, try setting this value to a value smaller than 1000.

9.3. Command Line

To run the aop precompiler from the command line you need all the aop jars on your classpath, and the class files you are instrumenting must have everything they would need to run in the java classpath, including themselves, or the precompiler will not be able to run.

The jboss.aop.path optional system property points to XML files that contain your pointcut, advice bindings, and metadata definitions that the precompiler will use to instrument the .class files. The property can have one or files it points to delimited by the operating systems specific classpath delimiter (';' on windows, ':' on unix). Files or Directories can be specified. If it is a directory, JBoss AOP will take all aop.xml files from that directory.

The jboss.aop.class.path optional system property points to all JARs or directories that may have classes that are annotated as @Aspect (See Chapter "Annotated Bindings"). JBoss AOP will browse all classes in this path to see if they are annotated. The property can have one or files it points to delimited by the operating systems specific classpath delimiter (';' on windows, ':' on unix). Note for this to have effect with JDK 1.4, you first have to run the annotation compiler with bytecode=true.

It is invoked as: 

$java -classpath ... [-Djboss.aop.path=...] [-Djboss.aop.class.path=...] \
                     org.jboss.aop.standalone.Compiler <class files or directories>

In the /bin folder of the distribution we have provided batch/script files to make this easier. It includes all the aop libs for you, so you just have to worry about your files. The usage for JDK 1.4 is: 

$ aopc <classpath> [-aoppath ...] [-aopclasspath ...] [-report] [-verbose] \
      <class files or directories>+

And for JDK 1.5: 

$ aopc15 <classpath> [-aoppath ...] [-aopclasspath ...] [-report] [-verbose] \
      <class files or directories>+

  • classpath - path to your classes and any jars your code depends on

The other parameters are the same as above.

Prev Up Next
Chapter 8. Installing Home Chapter 10. Running Aspectized Applications