Introduction

This document explains the different options provided to enable AspectWerkz online mode (on the fly weaving, class load time weaving).

The main concept is that the core Java class loading architecture has to be enhanced to allow weaving (modification of the bytecode) just before a class is loaded in the JVM. This overhead is very light when no class at all have aspects bounded, and occurs only once per class per class loader hierarchy when aspects (pointcuts, introductions, advices) are bounded.

AspectWerkz hooks in directly after the bootstrap class loader and can perform bytecode transformations on classes loaded by all the preceeding class loaders, making it compatible with J2EE environments with complex class loader hierarchy between system, ear, ejb-jar and war deployments.

AspectWerkz2 comes with Java 5 JVMTI support and hotswap is fully standardized in Java 5. In case you are running Java 5, you should read the following section..

All options are described in terms of architecture and impact, and a sample is given on how to startup an application with this option.

Choosing the best option depends of your needs. Refer to the comparison matrix for a quick view.

For a more schematic view (does not apply for Java 5) about this architecture, refer to official slides.

Note on previous releases

The releases prior to 0.8 where using JMangler to plug in the class loading hierarchy. JMangler is a very innovative solution, but starting with 0.8, AspectWerkz uses its own architecture, having full control over it.

The core theoretical concept of hooking in the class loader hierarchy is inspired from the JMangler project.

Having full control over this low level architecture was a crucial point to achieve for AspectWerkz.

All the options described here are not part of JMangler and neither provided by JMangler. These are the fruit of the efforts made to provide several lightweight, cross platform, efficient and tight to the needs options to integrate AspectWerkz online mode in the most seamless way.

JSR-163 JVMTI for Java 5 is supported since the 1.0 release.

Weaving Schemes

AspectWerkz supports several integration schemes. Each scheme depends on your requirements and provides different advantages and drawbacks. It is possible to use :

  • post compilation of the application (like AspectJ does): offline weaving at application build time
  • class load time weaving: online weaving at application deployment time
  • runtime weaving: online weaving in a running application (experimental)
AspectWerkz distribution contains a command line tool that helps to be up and running quickly, although it is a good thing to really understand the different schemes for a production environment.

Overview of options for online weaving

This part describes the main concept of each option. For a detailled understanding, refer to the option section.

Some options are suitable for Java 1.4 only. Refer to the comparison matrix section.

  • Command line tool

    The command line tool bin/aspectwerkz is an unification of HotSwap and Transparent bootclasspath. It sets the classpath and pathes required and is thus the easiest way to start with, though it might not allow for advanced use. The command line tool allows auto detection of Java 1.3 and Java 1.4.

  • BEA JRockit

    A specific extension for BEA JRockit JVM (version 7 ie Java 1.3 and 8.1 ie Java 1.4) is available. This extension is based on official BEA Java Management API (JMAPI). It allows to run AspectWerkz online mode in a JRockit VM in a well designed way (no change at the java.lang.ClassLoader level).

  • Java 5

    Java 5 JSR-163 JVMTI ( read JSR) allows to integrate AspectWerkz with just a single -javaagent:lib/aspectwerkz-jdk5-$VERSION.jar JVM option. This is supported since release 1.0.

  • HotSwap

    A first JVM launchs your target application in a second JVM. The first JVM hooks AspectWerkz in the second one just before the main class (and all dependencies) gets loaded, and then connects to the stdout / stderr / stdin stream of the second JVM to make them appear as usual through the first JVM.

  • Transparent bootclasspath

    For JVM or Java version like 1.3 which don't support class replacement at runtime (HotSwap), this option allows for same mechanism by putting an enhanced class loader in the target application VM bootclasspath.

  • Native HotSwap

    A native C JVM extension running in the target application VM handles the replacement of the class loader by the enhanced one.

  • Remote HotSwap

    The application VM is launched suspended. The replacement of the enhanced class loader is done through a separate manual process, which can easily be scripted.

  • Prepared bootclasspath

    The enhanced class loader is builded and packaged as a jar file in a first separate manual process, which can easily be scripted. The application VM is launched with options to use this enhanced class loader.

  • IBM JRE

    IBM SDK / JRE is supported as a regular Sun VM although there are some implementation differences. Note that HotSwap might not be supported.

How to choose the right option

Comparison matrix

OptionJava version

supported
Number of JVM

running
Notes
BEA JRockit Java 1.3 (JRockit 7), Java 1.4 (JRockit 8.1)1 -Xmanagement JVM option

Recommended for BEA JRockit
Java 5 Java 51 -javaagent: JVM option

Recommended for Java 5
HotSwap 1.4 + HotSwap2bin/aspectwerkz or ProcessStarter

Autodetection mechanism
Transparent bootclasspath 1.3 and later2bin/aspectwerkz or ProcessStarter

Autodetection mechanism

-Daspectwerk.classloader.clbootclasspath=... option in first VM
Native HotSwap 1.4 + HotSwap1 -Xrunaspectwerkz JVM native extension

Remote HotSwap 1.4 + HotSwap1Two step process
Prepared bootclasspath 1.3 and later1Two step process for the first use

Recommended for complete integration on Java 1.3 and HotSpot 1.4

Note on Java 1.3 support

Java 1.3 support is achieved through two options:

Both options put the enhanced class loader in the -Xbootclasspath/p: option, whether programmatically (2 JVM), whether manually (1 JVM, two step process). This means that a Sun provided class of rt.jar is overriden by a custom one, which contravenes the Java 2 Runtime Environment binary code license as stated in Sun documentation.

On the same topic, the following Sun statement is contradictory.

Due to these legal issues, AspectWerkz do not ship nor release the overriden class.

Java 1.3 support is provided for educational purpose and your application using this option should not be deployed as doing so would contravene the Java 2 Runtime Environment binary code license. As a side note, you will note that overriding a class of rt.jar is possible through HotSwap Sun technology with Java 1.4, or with JVMPI CLASS_LOAD_HOOK event since Java 1.2.

Moreover, commercial solutions for Application Performance Management like Mercury are using -Xbootclasspath in the application they sell.

Note on HotSwap support

HotSwap is available on Sun JVM since Java 1.4. It requires the JVM with -Xdebug option, to allow recording of method call dependencies, in order to reorganize them when a method is replaced at runtime through HotSwap.

With -client JVM option, the overhead of -Xdebug is almost null on Java 1.4.

With -server JVM option, the overhead is stated to be from 5 to 10%, since HotSpot optimizations cannot be all set up.

General rules

No matter the option used to enable online mode, some general rules must be respected.

Released jar organization

  • aspectwerkz-core-*.jar must always be in the bootclasspath of the JVM. Use -Xbootclasspath/p: JVM option.
  • when HotSwap (excepted native HotSwap) is used, JAVA_HOME/jre/bin must be in the PATH, and JAVA_HOME/lib/tools.jar must be in the bootclasspath of the JVM.
  • aspectwerkz-*.jar and all dependencies must be in regular classpath. You must choose aspectwerkz-jdk14-*.jar or aspectwerkz-jdk5-*.jar depending on the Java version you run with. One and only one of those file should be present.

Weaver options

The online mode supports the following options:

  • -Daspectwerkz.definition.file=... should point to a valid XML definition file. If not specified, the first aspectwerkz.xml file found in the classpath will be used.
  • -Daspectwerkz.transform.verbose=true (or =yes) turns on verbose mode
  • -Daspectwerkz.transform.details=true (or =yes) turns on verbose mode for the matching of pointcuts
  • -Daspectwerkz.transform.dump=... will dump loaded class in ./_dump/ directory. If the value is * it will dump all classes. If the value is my.package.* it will dump only my.package package' classes. If the value is my.package..* it will dump only my.package package' and subpackage' classes. The pattern is the same as for poincut pattern If the value is postfixed by ,before ( my.package.,before), class bytecode will be dumped twice, in ./_dump/before/ for the original class and in ./_dump/after/ for the weaved one.

Command line tool

The command line tool bin/aspectwerkz allow for basic use of the options HotSwap and Transparent bootclasspath through an autodetection mechanism.

It sets the classpath and pathes for you.

The command line tool also allow for offline mode compilation, though it can be achieve by direct Java invocation.

BEA JRockit

Description

This options is based on BEA JMAPI. The AspectWerkz weaver is embedded as a ClassPreProcessor component in the JRockit JVM. BEA provides this ClassPreProcessor based mechanism natively.

This option is the only available and most elegant way to integrate AspectWerkz in a JRockit environment:

  • HotSwap is not supported in JRockit JVM (version 7 and 8.1 unless latest 1.4.2 versions).
  • -Xbootclasspath/p option does not allow to override java.lang.ClassLoader class in JRockit JVM
  • The provided extension is based on official BEA APIs

Usage

You first need to have the aspectwerkz-extensions.jar AspectWerkz library containing the JRockit AspectWerkz module. This jar file should be included in the release.

It is possible to compile this file using the build commands: ant jars

although this one should be part of the distribution. This will generate aspectwerkz-extensions.jar in ASPECTWERKZ_HOME/lib directory.

You then need to adapt bin/aspectwerkz script to uncomment the line allowing JRockit support. Another option is to modify your own startup script so that

  • The JVM is started with -Xmanagement:class=org.codehaus.aspectwerkz.extension.jrockit.JRockitPreProcessor VM option
  • All AspectWerkz jars and dependencies are in the JVM regular classpath using -cp ...
# set AspectWerkz version and libs dependencies
set VERSION=2.0
set DEPS=... // AspectWerkz dependencies - see bin/setEnv for the complete list

# for Java 1.3 or 1.4
set DEPS=$DEPS:aspectwerkz-jdk14-$VERSION.jar
# for Java 5
# set DEPS=$DEPS:aspectwerkz-jdk5-$VERSION.jar

# all AspectWerzk jar and dependencies
set AW_PATH=aspectwerkz-extensions-$VERSION.jar:aspectwerkz-core-$VERSION.jar:aspectwerkz-$VERSION.jar:$DEPS

# -Xmanagement option and -Xbootclasspath/a:
java -Xmanagement:class=org.codehaus.aspectwerkz.extension.jrockit.JRockitPreProcessor -cp $AW_PATH... ..
     .. -Daspectwerkz.definition.file=... my.MyApp
                    

Key advantages

Key advantages using this mode are:

  • based on official BEA API
  • no dynamic or static replacement of a JRE class (java.lang.ClassLoaer)
  • JVM does not requires -Xdebug flag as in HotSwap modes

Java 5

Description

This options is based on JSR-163 JVMTI, part of Java 5 Tiger release. The AspectWerkz weaver is embedded as a Java standardized preMain agent in the JVM and thus activated before any call to the main method in a transparent way.

This option is the only available and most elegant way to integrate AspectWerkz in a Java 5 environment:

  • It is simply the Java standard.

Usage

Due to some distributions issues and Java 1.3 / 1.4 support requirement, the module for Java 5 might not be compiled in the release you obtained. It is advised to recompile your release using your own Java 5 environment since at the time of this release, Java 5 is not in its final version neither.

Set ASPECTWERZ_HOME environment variable and type:

java -version

to be sure you are running Java 5 as a default and then type

ant clean jars

You then have to adapt bin/aspectwerkz script (if you are using it) to uncomment the line allowing Java 5 support. On your own applications make sure of the following:

  • The JVM is started with -javaagent:lib/aspectwerkz-jdk5-$VERSION.jar VM option
  • All AspectWerkz jars and dependencies are in the JVM regular classpath using -cp ... or CLASSPATH environment variable.
# set AspectWerkz version and libs dependencies
set VERSION=2.0
set DEPS=... // AspectWerkz dependencies - see bin/setEnv for the complete list

# all AspectWerzk jar, and dependencies
set AW_PATH=aspectwerkz-core-$VERSION.jar:aspectwerkz-$VERSION.jar:$DEPS

# -javaagent option
# adapt the path to aspectwerkz-core-$VERSION.jar as required
java -javaagent:lib/aspectwerkz-jdk5-$VERSION.jar -cp $AW_PATH... ..
     .. -Daspectwerkz.definition.file=... my.MyApp
                    

Key advantages

Key advantages using this mode are:

  • based on official standardized API of Java 5

HotSwap

Description

HotSwap is a technology provided by Sun starting with Java 1.4 which allows on the fly class replacement. Not all JVMs support it, though it is standardized by Sun in the JPDA architecture.

A first tiny JVM launchs your target application in a second JVM. The second JVM is launched with -Xdebug and -Xrunjdwp options to allow HotSwap. The first JVM hooks AspectWerkz in the second one just before the main class (and all dependencies) gets loaded, and then connects to the stdout / stderr / stdin stream of the second JVM to make them appear as usual through the first JVM.

Note: this dual JVM mechanism was the single option in previous JMangler based releases, but there is a key improvement. This option now allows to further connect a JPDA based debugger to the target application JVM (for example Kamirra Debugger, or any IDE integrated one)

Usage

This option can be used out of the box with the command line tool bin/aspectwerkz. Use bin/aspectwerkz as a replacement of JAVA_HOME/bin/java.

set JAVA_HOME=...
set ASPECTWERKZ_HOME=...

# standard launched: java -cp myJar.jar my.App args

$ASPECTWERKZ_HOME/bin/aspectwerkz -cp myJar.jar -Daspectwerkz.definition.file=... my.App args

# Note: On windows, adapt with %ASPECTWERKZ_HOME%\bin\aspectwerkz
                    

For more advanced usage and fine tuning, you should avoid using the bin/aspectwerkz. Use org.codehaus.aspectwerkz.hook.ProcessStarter instead.

Requirements:

  • have Java 1.4
  • set JAVA_HOME
  • add JAVA_HOME/jre/bin to your PATH to enable HotSwap API
  • add aspectwerkz-core-*.jar in the first VM classpath
  • add aspectwerkz-core-*.jar and JAVA_HOME/lib/tools.jar in the second VM bootclasspath
  • add aspectwerkz-*.jar and dependencies in the second VM classpath (including aspectwerkz-jdk14-*.jar)
set JAVA_HOME=...
set PATH=$JAVA_HOME/jre/bin:$PATH

# set AspectWerkz version
# set AspectWerkz jar dependencies
set VERSION=2.0
set DEPS=... // AspectWerkz dependencies - see bin/setEnv for the complete list

set CLASSPATH_1=aspectwerkz-core-$VERSION.jar:$CLASSPATH
set BOOT_PATH=aspectwerkz-core-$VERSION.jar:$JAVA_HOME/lib/tools.jar

# set CLASSPATH as needed for your application
set CLASSPATH=...:$CLASSPATH
set CLASSPATH=aspectwerkz-$VERSION.jar:$DEPS:$CLASSPATH

# For Java 1.4, add aspectwerkz-jdk14 to the classpath
# Else for Java 5, add aspectwerkz-jdk5 [but you would have then better using JVMTI -javaagent option]

# set OPTIONS as needed for your application VM
set OPTIONS=...
java -cp $CLASSPATH_1 org.codehaus.aspectwerkz.ProcessStarter ..
    .. $OPTIONS -Xbootclasspath/a:$BOOT_PATH_2 -cp $CLASSPATH_2 ..
    .. -Daspectwerkz.definition.file=... my.App args

# Note:On windows adapt with %CLASSPATH_1% , ";" as classpath separator and "\" as path separator
                    

ProcessStarter is used as a replacement of a JAVA_HOME/bin/java and some additional jars are added to the application VM classpath.

The script described above is basically bin/aspectwerkz, but you can now add more options.

The regular AspectWerkz weaver options -Daspectwerkz.transform.verbose=true, -Daspectwerkz.transform.details=true and -Daspectwerkz.transform.dump=...can be used. Simply place them after ProcessStarter.

java ... org.codehaus.aspectwerkz.hook.ProcessStarter -Daspectwerkz.transform.verbose=yes ...
                    

Both options can slow down the weaving process and should be used for debugging / educational purpose.

If you want to connect to your remote application, the default JDWP configuration is transport=dt_socket,address=9300. You can override this one with your favourite one by specifying the -Xrunjdwp:... option in the target application VM section (after ProcessStarter).

For more information about JDWP option, read Sun JDWP documentation.

Key advantages

Using HotSwap through bin/aspectwerkz or ProcessStarter is very convenient since it can be used as JAVA_HOME/bin/java replacement.

A key advantage is that it autodetects HotSwap support (and thus Java 1.3) and transparently behaves as the transparent bootclasspath option.

Transparent bootclasspath

Description

For JVM or Java version like 1.3 which don't support HotSwap, this option allows for same mechanism by putting an enhanced class loader in the target application VM bootclasspath.

This option is part of an autodetection mechanism, which allow to use it the same way as the previously described option. For Java 1.4 VM supporting HotSwap, it is possible to force this mode, which does not run the target application VM with -Xdebug option.

Usage

For Java 1.3, use the bin/aspectwerkz script as described here.

It will create a temporary ./_boot/ directory, which will be automatically added in the -Xbootclasspath/p: section of the target application VM.

To force the use of this option (especially with Java 1.4), you must specify the temporary boot directory through the -Daspectwerkz.classloader.clbootclasspath=_boot option. Specify as value a path which will be used (created if necessary) as temporary directory.

This option must be set for the first VM (before ProcessStarter):

java -Daspectwerkz.classloader.clbootclasspath=/temp/_boot ... org.codehaus.aspectwerkz.ProcessStarter ...
                    

Key advantages

Forcing the use of this options is not really necessary, unless specific needs, since it is used through the autodetection mechanism of HotSwap support (and thus java 1.3) and thus transparently invocated when using bin/aspectwerkz or ProcessStarter.

Native HotSwap

Description

Native HotSwap is available only for Java 1.4 VM supporting HotSwap.

Instead of using a lauching JVM that hotswaps the class laoder with an enhanced one, a native C JVM extension running in the target application VM handles it.

This is the most seamless way to hook AspectWerkz in. For a list of ready to use prebuilded platform specific modules, refer to the module release list.

Usage

Requirements:

  • Java 1.4 HotSwap supporting JVM
  • add in PATH the directory where native HotSwap module aspectwerkz.dll or libaspectwerkz.so resides
  • turn on -Xdebug option
  • turn on the AspectWerkz native HotSwap module through -Xrunaspectwerkz
  • add aspectwerkz-core.jar and JAVA_HOME/lib/tools.jar in -Xbootclasspath/a
  • add aspectwerkz.jar and dependencies in the regular classpath
# set AspectWerkz version and libs dependencies
set VERSION=2.0
set DEPS=... // AspectWerkz dependencies - see bin/setEnv for the complete list

# add directory where native HotSwap libaspectwerkz.so (or aspectwerkz.dll) resides
set PATH=$ASPECTWERKZ_HOME/lib

set BOOT_PATH=aspectwerkz-core-$VERSION.jar:$JAVA_HOME/lib/tools.jar

# standard usage with -Xrunaspectwerkz module
java -Xdebug -Xrunaspectwerkz -Xbootclasspath/a:$BOOT_PATH ..
    .. -cp aspectwwerkz-$VERSION.jar:$DEPS:... -Daspectwerkz.definition.file=... my.MyApp

# Note: for simplicity, classpath have been simplified
# Adapt according to where aspectwerk[-core].jar and dependencies are located.
# Adapt for windows usage
                    

The regular AspectWerkz weaver options -Daspectwerkz.transform.verbose=true, -Daspectwerkz.transform.details=true and -Daspectwerkz.transform.dump=...can be used.

Key advantages

In this mode, a single JVM is running. It is the easiest option to set up with a Java 1.4 VM supporting HotSwap.

Remote HotSwap

Description

With this option, a single JVM is running. The hotswapping of the enhanced class loader is done through a separate manual process, which can easily be scripted.

This option can also be used to startup a JVM as usual and further decide to activate AspectWerkz in. Doing that will not allow you to apply pointcuts on standard Java classes, but will still allow a limited usage in a J2EE environnement at deployment time of your applications.

Usage - step 1: starting up

You have to start your application VM with AspectWerkz jars and turning on a JDWP connection to allow further connection to the running JVM in order to hotswap the class loader.

Requirements:

  • Java 1.4 HotSwap supporting JVM
  • turn on JDWP listening connection with -Xrunjdwp:...
  • be sure to use server=y JDWP option
  • for JVM wide weaving, be sure to set suspend=y as a JDWP option
  • add JAVA_HOME/jre/bin to your PATH to allow jdwp
  • add aspectwerkz-core.jar and JAVA_HOME/lib/tools.jar to the -Xbootclasspath/a:
  • add aspectwerkz.jar and dependencies in regular classpath
For more information about JDWP option refer to Sun JDWP documentation.
# set AspectWerkz version and libs dependencies
set VERSION=2.0
set DEPS=... // AspectWerkz dependencies - see bin/setEnv for the complete list

# enable JDWP
set PATH=$JAVA_HOME/jre/bin:$PATH

set BOOT_PATH=aspectwerkz-core-$VERSION.jar:$JAVA_HOME/lib/tools.jar

# standard usage with -Xrunjdwp
# Note: VM will start and immediately hang until step 2 is completed due to suspend=y
# Refer to Sun JDWP documentation for transport and address options
java -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=y -Xbootclasspath/a:$BOOT_PATH ..
    .. -cp aspectwwerkz-$VERSION.jar:$DEPS:... -Daspectwerkz.definition.file=... my.MyApp
                    

In the previous sample, the lauched JVM will hang, waiting for the enhanced class loader to be pushed it through remote HotSwap.

Usage - step 2: remote hotswap

The org.codehaus.aspectwerkz.hook.Plugtoo is called to prepare the enhanced class loader and connect to the remote JVM just lauched. It installs the class loader through HotSwap as specified with the -hotswap argument. It then resumes the JVM which goes on with AspectWerkz hooked in, and disconnects.

Further connection through JDWP with a suporting debugger is possible.

Note that the JAVA_HOME used to call Plug must be the same as the one used to startup the application JVM to ensure correct construction of the enhanced class loader.

set CLASSPATH=aspectwerkz-core.jar:JAVA_HOME/lib/tools.jar
java -cp $CLASSPATH org.codehaus.aspectwerkz.hook.Plug -hotswap transport=dt_socket,address=8000

# An Ant target is provided in the source distribution
# ant samples:plug

                    

Some other org.codehaus.aspectwerkz.hook.Plug argument can be passed through. Try the -help option to learn more.

Key advantages

This option is provided to allow HotSwap without native code and to have a single JVM running without the stream piping in background as with the regular HotSwap option.

If there is a native HotSwap release available for your environment, you should use it instead.

Prepared bootclasspath

Description

With this option, a single JVM is running. The enhanced class loader is builded and packaged as a jar file in a first separate manual process, which can easily be scripted.

It can then be added in the -Xbootclasspath/p: option.

This options does not uses HotSwap and is thus Java 1.3 compatible.

Usage - step 1: preparation

Invoque org.codehaus.aspectwerkz.hook.Plug -target to generate the jar file containing the enhanced class loader.

This step can be scripted, or done once for your Java environment.

set CLASSPATH=aspectwerkz-core.jar:JAVA_HOME/lib/tools.jar
java -cp $CLASSPATH org.codehaus.aspectwerkz.hook.Plug -target /path/to/enhanced.jar

# the file path/to/enhanced.jar will be created (eventually overriden)

# An Ant target is provided in the source distribution
# ant samples:plug
                    

Usage - step 1: startup

Start your application by adding the generated jar to the -Xbootclasspath/p: option. Note the /p: flag instead of the previously used /a: flag.

Add all needed jar in the -Xbootclasspath/p: or regular classpath as usual.

# set AspectWerkz version and libs dependencies
set VERSION=2.0
set DEPS=... // AspectWerkz dependencies - see bin/setEnv for the complete list

set BOOT_PATH=aspectwerkz-core-$VERSION.jar

# standard usage with -Xbootclasspath/p: pointing to step 1 generated jar
java -Xbootclasspath/p:/path/to/enhanced.jar -Xbootclasspath/a:$BOOT_PATH ..
    .. -cp aspectwwerkz-$VERSION.jar:$DEPS:... -Daspectwerkz.definition.file=... my.MyApp
                    

Key advantages

This options works both for Java 1.3 and Java 1.4. It starts a single JVM and runs it without -Xdebug option.

For a complete discussion on when to use this option read the next section.

Released native HotSwap modules

The releases native HotSwap modules can be founded here.

Offline weaving

Introduction

AspectWerkz provides several way to weave the aspects in the application classes at build time. This is called offline weaving, offline mode, or even class post-processing.

With this mode you have to be sure to post-process the application classes as many times as required if you plan to use multiple Aspect Systems as described here.

There is mainly two ways to achieve this, allthough some variants can be built on top of them:
  • Use the AspectWerkz command line tool with the -offline option on a specific .class file, directory or jar file.
  • Use the org.codehaus.aspectwerkz.compiler.AspectWerkzC utility in an Ant or Maven script.
As you might have understood, the command line tool is delegating to the AspectWerkzC class after all required jars have been added to the classpath.

Command line tool usage

The command line tool is described in a next part.

AspectWerkzC and Ant / Maven integration

You can find several samples of Ant and Maven integration in the AspectWerkz distribution.

The following are the options supported by the AspectWerkzC tool. Most of them can be used as well in the AspectWerkz command line tool.

# set the classpath correctly
# see bin/setEnv in the AspectWerkz distribution

# Add Ant-1.5 in the classpath

java -cp ... org.codehaus.aspectwerkz.compiler.AspectWerkzC [-verbose] [-details] [-genjp] [-haltOnError] [-verify] [-cp {additional cp i}]*  {target 1} [{target i}]*

# Use -Daspectwerkz.definition.file=... option to specify the XML definition file to use
# Or rely on the META-INF/aop.xml and WEB-INF/aop.xml path lookup
                    
  • -verbose: turns on verbose mode (optional)
  • -details: turns on detailed matching mode (optional)
  • -genjp: turns on keeping of join point classes (optional)
  • -haltOnError: stops the compilation at the first error (target2 will not be post-processed if it fails on target1) (optional)
  • -verify: do some bytecode verification (mainly usefull for AspectWerkz development team) (optional)
  • -cp path1;path2/some.jar: additional classpath needed for the compilation. Put your aspect classes in this path, and your application third parties jar if any. This is mainly needed to match on subtype patterns (java.lang.String +), where the complete classes dependencies is needed. For convenience you can use several -cp ... option. Be sure to use ";" or ":" as a path separator as for the regular JVM classpath option.
  • target path/classes path/application.jar: defines the classes, classes directories and jar files to post-process. It is possible to pass as many target as needed.

A sample for Ant using the command line tool looks like the following. You will notice that the aspect classes must be in the classpath (to retrieve their annotations that defines the pointcut f.e.).

In this sample, since the command line tool is used, it is mandatory to pass the XML definition file as the second argument.
<!-- =================================================== -->
<!--  offline transformation of the samples -->
<!-- =================================================== -->
<target name="aspectwerkz:transform"
depends="clean, aspectwerkz:init, aspectwerkz:compile, aspectwerkz:samples:aspectc">
<exec executable="${bin.dir}/aspectwerkz.bat">
    <arg line="-offline ${basedir}/src/application/aop.xml -verbose -verify -cp ${aspect.classes} ${application.classes}"/>
</exec>
</target>
                    

A sample for Ant using the AspectWerkzC class looks like the following:
<target name="aspectwerkz:war:transform"
depends="aspectwerkz:compile, aspectwerkz:war:aspectc">
<java classname="org.codehaus.aspectwerkz.compiler.AspectWerkzC" fork="true">
    <classpath refid="project.class.path"/>
    <classpath>
        <pathelement path="${build.main.dir}"/><!-- needed for abstract Aspect activation -->
        <pathelement path="${build.web.dir}"/><!-- needed for Aspect activation -->
    </classpath>
    <jvmarg value="-Daspectwerkz.definition.file=${src.web.dir}/WEB-INF/aspectwerkz.xml"/>
    <jvmarg value="-Daspectwerkz.transform.verbose=true"/><!-- an AspectWerkz weaver option -->
    <arg value="-verify"/><!-- an AspectWerkzC tool option -->
    <arg value="-verbose"/><!-- an AspectWerkzC tool option -->
    <!-- below is the classes dir to post-process. It could be some jar files as well. -->
    <arg value="${build.web.dir}"/>
    <arg value="${build.main.dir}"/>
</java>
</target>
                    

There is also an Ant task for this - you can read more about it here.

Packaging the post-compiled classes

Once the application classes (or dir / jars) have been post-compiled, those have dependencies on

  • AspectWerkz jars and third parties jars.
  • Your own aspects classes and all aspects that might be triggered according to the Aspect System organization
It is then a good practice to package the aspects alongside your application just as regular classes, and then decide if AspectWerkz jars and third parties jars should be packaged within the application (f.e. in First.war/WEB-INF/lib/) or added to the application regular classpath. You can use the bin/setEnv script of the distribution for that, or change your application startup script to add those jars in the -cp or -classpath JVM classpath settings.

Ant task for Offline weaving

An Ant task is provided for offline weaving

Usage

First you need to activate the custom task in your Ant build.xml file with the following: (refer to Ant documentation on "taskdef" for more details)

<!-- we assume we defined a classpath with the id="aw.class.path" for AspectWerkz jars -->
<path id="aw.class.path">
...
<pathelement path="pathToAspectWerkz.jar"/>
...
</path>

<!-- define the custom task (annotationc can be changed to what you prefer)
<taskdef name="awc" 
         classname="org.codehaus.aspectwerkz.compiler.AspectWerkzCTask" 
         classpathref="aw.class.path"/>
<!-- Note: the <taskdef> element can be nested within a <target> element at your convenience -->

<!-- invoke the awc defined task -->
<target name="samples:task:awc" depends="init, compile:all, samples:task:annoationc">
<awc
    verbose="true"
    definition="${basedir}/src/samples/aop.xml"
    classpathref="project.class.path">

    <target path="${basedir}/target/samples-classes"/>
</awc>
</target>
                

Reference

The AspectWerkzCTask task accepts the following:

  • verbose: [optional] flag marking the weaver verbosity [true / false]
  • genjp: [optional] flag marking the need to keep the generated join point classes [true / false]
  • taskverbose: [optional] flag marking the task verbose [true / false]
  • definition: [optional] path to aspect definition xml file (optional, can be found on the path as META-INF/aop.xml - even several)

Use the following parameters to configure the classpath and to point to the classes to be weaved. Those can be specified with nested elements as well / instead:
  • classpath: classpath to use
  • classpathref: classpath reference to use
  • targetdir: directory where to find classes to weave
  • targetpath: classpath where to find classes to weave
  • targetpathref: classpath reference where to find classes to weave

Nested elements are similar to the "java" task when you configure a classpath:
  • classpath: Path-like structure for the classpath to be used by the weaver. Similar to "java" task classpath
  • targetpath: Path-like structure for the class to be weaved

Some rarely used options are also available:
  • backupdir: directory where to backup original classes during compilation, defautls to ./_aspectwerkzc
  • preprocessor: fully qualified name of the preprocessor. If not set the default is used.

AspectWerkz command line tool

Environment setting

The command line tool is the easiest way to start using AspectWerkz since it provides all classpath settings for both class load time weaving and offline post-processing.

To use it, you first need to set the ASPECTWERKZ_HOME environment variable to the directory containing the AspectWerkz installation.
set ASPECTWERKZ_HOME=C:\aop\aspectwerkz\

# export might be needed on Linux / Unix OS.

# The tool assumes JAVA_HOME environment variable is correctly set.
                    
The command line tool is then in ASPECTWERKZ_HOME/bin directory. You can add this directory to your PATH environment variable if you want.

Type aspectwerkz without any arguments to print the usage message.

Offline compilation

To post-process all class files in a specific directory (recursively), jar or zip file:

aspectwerkz -offline <definition file> [-verbose] [-details] [-genjp] [-verify] [-haltOnError] [-cp <classpath>]* <target classes to transform>+
  • The 'definition file' option is the path to the XML definition file (mandatory).
  • Turns on -verbose to follow each step of the processing (optional).
  • Turns on -details to follow the pointcut matching (optional).
  • Turns on -genjp to keep generated joinpoint strcutures (optional).
  • Turns on -verify to verify all weaved class according to the Java Class Format specification (optional, mainly usefull for AspectWerkz development team).
  • When an error occurs, all classes of the current target are restored to their initilal state and the processing goes on with the next target unless -haltOnError was set (optional). In this case the processing stops. Else a complete status about successfull and failed targets is printed at the end of all target processing.
  • The 'classpath' option is the classpath needed for compilation but not to be transformed (eg -cp myAspects.jar;servletAPI.jar). It is possible to use several -cp <classpath> option instead of doing concatenation.
  • The 'target classes to transform' option specifies the classes to transform. It must the path to the root directory of the classes you want to transform, or a jar file or a zip file. Several targets can be passed in one call (eg toTransform.jar /classes otherToTransform.jar).

Note: when you then are running the application (without using the aspectwerkz command) you have to (apart from feeding it with the definition) put the aspectwerkz jars along with all the the dependency jars the ASPECTWERKZ_HOME/lib directory in your classpath. Read more about it here.

Class load time weaving

It is possible to use the command line tool as a replacement of the JAVA_HOME/bin/java command. In such a case, the command line tool will detect a suitable option for you and will enable class load time weaving.

This is the easiest way to give a try to class load time weaving although you should read and choose the best option by yourself by reading more on this topic here.

Starting up an application (use -Daspectwerkz.definition.file=.. or have META-INF/aop.xml and WEB-INF/aop.xml files in the classpath and applications packaging as explained in this section):

aspectwerkz [-options] <main class> [args...]

Starting up an application using an executable jar file:

aspectwerkz [-options] -jar <jar file> [args...]