JBoss.org Community Documentation

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.

<?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.

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

Define also the path of your JBoss AOP installation, as well as the path to the lib directory:

          <property name="jboss.aop.root" value="PATH TO JBOSS AOP HOME"/>
          <property name="jboss.aop.lib" value="${jboss.aop.root}/lib"/>
         

Include the jboss-aop.jar and the jars it depends on in the classpath:

      <path id="classpath">
         <pathelement path="${jboss.aop.lib}/jboss-aop.jar"/>
         <pathelement path="${jboss.aop.lib}/javassist.jar"/>
         <pathelement path="${jboss.aop.lib}/trove.jar"/>
         <pathelement path="${jboss.aop.lib}/jboss-common-core.jar"/>
         <pathelement path="${jboss.aop.lib}/jboss-logging-spi.jar"/>
         <pathelement path="${jboss.aop.lib}/jboss-logging-log4j.jar"/>
         <pathelement path="${jboss.aop.lib}/jboss-mdr.jar"/>
         <pathelement path="${jboss.aop.lib}/jboss-reflect.jar"/>
         <pathelement path="${jboss.aop.lib}/log4j.jar"/>
      </path>
         

As an alternative, you can use the single jar provided with JBoss AOP. This jar bundles all the libraries used by JBoss AOP in a single unit. To use this jar, just define:

      <path id="classpath">
         <pathelement path="${jboss.aop.lib}/jboss-aop-single.jar"/>
      </path>
         

Now, 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 classes directory and weaves those classes, ovewriting them with the corresponding weaved version.

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

The last tag, aopclasspath, must be used only if you used annotations to configure aspects, bindings, and the like. If this is the case and you are not using a jboss-aop.xml file, you can ommit the aoppath tag. You can also use both annotations and XML to configure aspects. In this case, you must declare both tags. The complete list of the parameters that org.jboss.aop.ant.AopC ant task takes follows:

  • 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
                   <aoppath>
                   <pathelement path="jboss-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 browse 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.