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.

This feature is standardized in Java 1.5 thru JSR-163 and supported as well.

All options are described in term 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 1.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 fruits 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 1.5 is supported since the 1.0 release.

Overview

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 all classpath and path 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 1.5

    Java 1.5 JSR-163 JVMTI ( read JSR) allows to integrate AspectWerkz with just a single -javaagent:lib/aspectwerrkz-core-XXX.jar JVM option. This is supported since release 1.0.

    Note: due to JSR-163 updates, this option might not be supported in J2SE 5 beta2. Instead, you may have to use -javaagent:org.codehaus.aspectwerkz.hook.Agent

  • 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 ot 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 1.5 Java 1.51 -javaagent: JVM option

Recommended for Java 1.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 dependancies, 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.

A work is in progress to provide an enhanced native HotSwap module that will not require the JVM to run with -Xdebug. Note that the existing native HotSwap module does not requires the JVM to run in -Xdebug mode under Java 1.4.0, but requires it under Java 1.4.1 or 1.4.2 due to JVMPI API changes.

General rules

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

Released jar organization

  • aspectwerkz-core-*.jar and javassist-*.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

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 all classpath and path for you.

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

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 ClasPreProcessor 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 dependancies are in the JVM regular classpath using -cp ...
# set AspectWerkz version and libs dependancies
set VERSION=1.0
set DEPS=... // AspectWerkz dependancies - see bin/setEnv for the complete list

# all AspectWerzk jar and dependancies
set AW_PATH=javassist-*.jar: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 1.5

Description

This options is based on JSR-163 JVMTI, part of Java 1.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 1.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 1.5 might not be compiled in the release you obtained. It is advised to recompile your release using your own Java 1.5 environment since at the time of this release, Java 1.5 is not in its final version neither.

Set ASPECTWERZ_HOME environment variable and type:

java -version

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

ant clean jars

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

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

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

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

Key advantages

Key advantages using this mode are:

  • based on an official standardized API of Java 1.5

HotSwap

Description

HotSwap is a technology provided by Sun starting with Java 1.4 which allows on the fly class replacement. Not all JVM supports it, thought 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 ot 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 and javassist-*.jar in the first VM classpath
  • add aspectwerkz-core-*.jar, javassist-*.jar and JAVA_HOME/lib/tools.jar in the second VM bootclasspath
  • add aspectwerkz-*.jar and dependencies in the second VM classpath
set JAVA_HOME=...
set PATH=$JAVA_HOME/jre/bin:$PATH

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

set CLASSPATH_1=javassist-*.jar:aspectwerkz-core-$VERSION.jar:$CLASSPATH
set BOOT_PATH=javassist-*.jar: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

# 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 defaults one with your favorite 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, javassist-*.jar and JAVA_HOME/lib/tools.jar in -Xbootclasspath/a
  • add aspectwerkz.jar and dependancies in the regular classpath
# set AspectWerkz version and libs dependancies
set VERSION=1.0
set DEPS=... // AspectWerkz dependancies - 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=javassist-*.jar: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 dependancies 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, javassist-*.jar and JAVA_HOME/lib/tools.jar to the -Xbootclasspath/a:
  • add aspectwerkz.jar and dependancies in regular classpath
For more information about JDWP option refer to Sun JDWP documentation.
# set AspectWerkz version and libs dependancies
set VERSION=1.0
set DEPS=... // AspectWerkz dependancies - see bin/setEnv for the complete list

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

set BOOT_PATH=javassist-*.jar: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:javassist-*.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:javassist-*.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 dependancies
set VERSION=1.0
set DEPS=... // AspectWerkz dependancies - see bin/setEnv for the complete list

set BOOT_PATH=javassist-*.jar: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.