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.
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.
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.
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.
Option | Java version supported | Number of JVM running | Notes |
---|---|---|---|
HotSwap | 1.4 + HotSwap | 2 | bin/aspectwerkz 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 extensionRecommanded 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 |
BEA JRockit | java 1.3 (JRockit 7), java 1.4 (JRockit 8.1) | 1 | -Xmanagement JVM option |
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.rt.jar
is possible thru HotSwap Sun technology with
java 1.4, or with JVMPI CLASS_LOAD_HOOK event since java 1.2.
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.
No matter the option used to enable online mode, some general rules must be respected.
-Xbootclasspath/p:
JVM option.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.
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 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)
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:
set JAVA_HOME=... set PATH=$JAVA_HOME/jre/bin:$PATH # set AspectWerkz version # set AspectWerkz jar dependencies set VERSION=0.9 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.
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.
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.
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 ...
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.
Requirements:
-Xdebug
option-Xrunaspectwerkz
-Xbootclasspath/a
# set AspectWerkz version and libs dependancies set VERSION=0.9 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.
With this option, a single JVM 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.
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:
-Xrunjdwp:...
server=y
JDWP optionsuspend=y
as a JDWP option-Xbootclasspath/a:
# set AspectWerkz version and libs dependancies set VERSION=0.9 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.definition.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.
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 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.
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.
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.
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
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.9 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.definition.file=... my.MyApp
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.
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:
You first need to have the extension.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 aspectwerkz:extensions:compile
or
maven aspectwerkz:extensions:compile
This will generate extensions.jar
in ASPECTWERKZ_HOME/target
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
-Xmanagement:class=org.codehaus.aspectwerkz.extension.jrockit.JRockitPreProcessor
VM option-Xbootclasspath/a:...
# set AspectWerkz version and libs dependancies set VERSION=0.9 set DEPS=... # all AspectWerzk jar, extensions.jar and dependancies set BOOT_PATH=bcel.jar:extensions.jar:aspectwerkz-core-$VERSION.jar:aspectwwerkz-$VERSION.jar:$DEPS # -Xmanagement option and -Xbootclasspath/a: java -Xmanagement:class=org.codehaus.aspectwerkz.extension.jrockit.JRockitPreProcessor -Xbootclasspath/a:$BOOT_PATH .. .. -cp .. -Daspectwerkz.definition.file=... my.MyApp
Key advantages using this mode are:
-Xdebug
flag as in HotSwap modes