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.
All options are described in term of architecture and impact, and a sample is given on how
to startup an application with this option.
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.
Having full control over this low level architecture was a crucial point to achieve for AspectWerkz.
Overview
This part describes the main concept of each option. For a detailled understanding, refer to the option section.
How to choose the right optionComparison matrix
Note on java 1.3 supportjava 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
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
General rulesNo matter the option used to enable online mode, some general rules must be respected. Released jar organization
Weaver optionsThe online mode supports the following options:
Command line tool
The command line tool
HotSwapDescriptionHotSwap 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
Usage
This option can be used out of the box with the command line tool
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
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
The regular AspectWerkz weaver options
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
Key advantages
Using HotSwap thru
Transparent bootclasspathDescription
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.
Usage
For java 1.3,
use the
To force the use of this option (especially with java 1.4), you must specify the temporary boot directory thru
the
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
Native HotSwapDescription
Native HotSwap is available only for java 1.4 VM supporting HotSwap.
UsageRequirements:
# 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
Key advantagesIn this mode, a single JVM is running. It is the easiest option to set up with a java 1.4 VM supporting HotSwap. Remote HotSwapDescription
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.
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.
# 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.
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
Key advantagesThis 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 bootclasspathDescription
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.
Usage - step 1: preparation
Invoque
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
# 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
Released native HotSwap modulesThe releases native HotSwap modules can be founded here . |