Introduction

This document explains the different options provided to enable AspectWerkz online mode (on the fly 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.

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 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 op tions described here are not part of JMangler and neither provided by JMangler. These are the fruits of the efforts the AspectWerkz team made to provide several lightweight, cross platform, efficient and tight to the needs options to integrate AspectWerkz online mode in the most seamless way.

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.

  • 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 thru the first JVM.

  • Transparent bootclasspath

    For JVM or java version like 1.3 which don't support class replace ment 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 thru 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.

How to choose the right option

Comparison matrix

Option Java version

supported
Number of JVM

running
Notes
HotSwap 1.4 + HotSwap 2 bin/asp ectwerkz or ProcessStarter

Autodetection mechanism
Transparent bootclasspath 1.3 and later 2 bin/aspectwerkz or ProcessStarter

Autodetection mechanism

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

Recommanded for java 1.4 advanced usage
Remote HotSwap 1.4 + HotSwap 1 Two step process
Prepared bootclasspath 1.3 and later 1 Two step process for the first use

Note on java 1.3 support

java 1.3 support is achieved thru 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 thru HotSwap Sun technology with java 1.4, or with JVMPI CLASS_LOAD_HOOK event since java 1.2.

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 thru 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 bcel.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 dependancies 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.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 thru 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 .

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 thru 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 bcel.jar in the first VM classpath
  • add aspectwerkz-core.jar, bcel.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=0.8
set DEPS=...

set CLASSPATH_1=bcel.jar:aspectwerkz-core-$VERSION.jar:$CLASSPATH
set BOOT_PATH=bcel.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 and -Daspectwerkz.transform.dump=... can be used. Simply place them after ProcessStarter .

java ... org.codehaus.aspectwerkz.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 thru 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 thru 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 thru 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 thru -Xrunaspectwerkz
  • add aspectwerkz-core.jar, bcel.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=0.8
set DEPS=...

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

set BOOT_PATH=bcel.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 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 JV M is running. The hotswapping of the enhanced class loader is done thru 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, bcel.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=0.8
set DEPS=...

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

set BOOT_PATH=bcel.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.defintion.file=... my.MyApp

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

Usage - step 2: remote hotswap

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

Further connection thru 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:bcel.jar:JAVA_HOME/lib/tools.jar
java -cp $CLASSPATH org.codehaus.aspectwerkz.hook.Plug -hotswap transport=dt_socket,address=8000

# A Maven / Ant target is provided in the source distribution
# ant aspectwerkz:samples:plug
# maven aspectwerkz:samples:plug

Some other org.codehaus.aspectwerkz.hook.Plug argument can be passed thru. 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:bcel.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)

# A Maven / Ant target is provided in the source distribution
# ant aspectwerkz:samples:plug
# maven aspectwerkz: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=0.8
set DEPS=...

set BOOT_PATH=bcel.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.defintion.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 .