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.
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.
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.
AspectWerkz
online mode in
a JRockit VM in a well designed way (no change at the java.lang.ClassLoader level).
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.
-javaagent:org.codehaus.aspectwerkz.hook.Agent
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.
Option | Java 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.5 | 1 |
-javaagent: JVM option
Recommended for Java 1.5 |
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 extension
|
Remote HotSwap | 1.4 + HotSwap | 1 | Two step process |
Prepared bootclasspath | 1.3 and later | 1 | Two step process for the first use
Recommended for complete integration on Java 1.3 and HotSpot 1.4 |
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.
AspectWerkz
do not ship nor release the overriden class.
rt.jar
is possible through 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 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.
No matter the option used to enable online mode, some general rules must be respected.
aspectwerkz-core-*.jar
and
javassist-*.jar
must always be in the bootclasspath of the JVM. Use
-Xbootclasspath/p:
JVM option.
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
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.
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.
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
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
-Xmanagement:class=org.codehaus.aspectwerkz.extension.jrockit.JRockitPreProcessor
VM option
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 using this mode are:
-Xdebug
flag as in HotSwap modes
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:
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:
-javaagent:lib/aspectwerkz-core-XXX.jar
VM option
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
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)
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:
JAVA_HOME
JAVA_HOME/jre/bin
to your PATH to enable HotSwap API
aspectwerkz-core-*.jar
and
javassist-*.jar
in the first VM classpath
aspectwerkz-core-*.jar
,
javassist-*.jar
and
JAVA_HOME/lib/tools.jar
in the second VM bootclasspath
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.
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.
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 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 ...
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
AspectWerkz
native HotSwap module through
-Xrunaspectwerkz
-Xbootclasspath/a
# 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.
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.
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 option
suspend=y
as a JDWP option
-Xbootclasspath/a:
# 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.
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 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.
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: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
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
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.