JBoss.org Community Documentation
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.