AspectWerkz - Plain Java AOP

##### General Information

- Overview
- Features
- License
- Downloads

##### Documentation

- New features in 2.x
- Introduction
- Tutorials
- Implementation issues
- General definition issues
- Annotation definition
- XML definition
- Annnotation driven development
- Deployment
- Weaving
- Dynamic AOP
- AOP container extensions
- Examples
- IDE integration
- JavaDoc
- FAQ

##### Misc.

- Releases & Release notes
- Build & install
- CVS access
- Mailing lists
- Tasks
- Papers, articles & talks

##### Project Documentation

- About AspectWerkz - Plain Java AOP
- Project Info
- Project Reports
- Development Process

## Table of Contents

1. Introduction
2. Note on previous releases
3. Weaving Schemes
4. Overview of options for online weaving
5. How to choose the right option
6. General rules
7. BEA JRockit
8. Java 5
9. HotSwap
10. Transparent bootclasspath
11. Native HotSwap
12. Remote HotSwap
13. Prepared bootclasspath
14. Released native HotSwap modules
15. Offline weaving (post compilation of the application)
16. Ant task for Offline weaving
17. AspectWerkz command line tool

## 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.
`AspectWerkz2` comes with Java 5 JVMTI support and hotswap is fully standardized in Java 5. In case you are running Java 5, you should read the following section..

All options are described in terms 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 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 fruit 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 5 is supported since the 1.0 release.

## Weaving Schemes

AspectWerkz supports several integration schemes. Each scheme depends on your requirements and provides different advantages and drawbacks. It is possible to use :

- post compilation of the application (like AspectJ does): offline weaving at application build time
- class load time weaving: online weaving at application deployment time
- runtime weaving: online weaving in a running application (experimental)

AspectWerkz distribution contains a command line tool that helps to be up and running quickly, although it is a good thing to really understand the different schemes for a production environment.

## Overview of options for online weaving

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 the classpath and pathes 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 5
  Java 5 `JSR-163 JVMTI` ( read JSR) allows to integrate AspectWerkz with just a single `-javaagent:lib/aspectwerkz-jdk5-$VERSION.jar` JVM option. This is supported since release 1.0.
- 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 of 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

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 5 | Java 5 | 1 | `-javaagent:` JVM option Recommended for Java 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

### Note on Java 1.3 support

Java 1.3 support is achieved through two options:

- Transparent bootclasspath
- Prepared bootclasspath

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 dependencies, 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.

## General rules

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

### Released jar organization

- `aspectwerkz-core-*.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. You must choose `aspectwerkz-jdk14-*.jar` or `aspectwerkz-jdk5-*.jar` depending on the Java version you run with. One and only one of those file should be present.

### 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 the classpath and pathes for you.
The command line tool also allow for offline mode compilation, though it can be achieve by direct Java invocation.

## 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 ClassPreProcessor 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 dependencies are in the JVM regular classpath using `-cp ...`

    # set AspectWerkz version and libs dependencies
    set VERSION=2.0
    set DEPS=... // AspectWerkz dependencies - see bin/setEnv for the complete list

    # for Java 1.3 or 1.4
    set DEPS=$DEPS:aspectwerkz-jdk14-$VERSION.jar
    # for Java 5
    # set DEPS=$DEPS:aspectwerkz-jdk5-$VERSION.jar

    # all AspectWerzk jar and dependencies
    set AW_PATH=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 5

### Description

This options is based on `JSR-163 JVMTI`, part of Java 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 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 5 might not be compiled in the release you obtained. It is advised to recompile your release using your own Java 5 environment since at the time of this release, Java 5 is not in its final version neither.
Set `ASPECTWERZ_HOME` environment variable and type:
`java -version`
to be sure you are running Java 5 as a default and then type
`ant clean jars`

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

- The JVM is started with `-javaagent:lib/aspectwerkz-jdk5-$VERSION.jar` VM option
- All `AspectWerkz` jars and dependencies are in the JVM regular classpath using `-cp ...` or `CLASSPATH` environment variable.

    # set AspectWerkz version and libs dependencies
    set VERSION=2.0
    set DEPS=... // AspectWerkz dependencies - see bin/setEnv for the complete list

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

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

### Key advantages

Key advantages using this mode are:

- based on official standardized API of Java 5

## HotSwap

### Description

HotSwap is a technology provided by Sun starting with Java 1.4 which allows on the fly class replacement. Not all JVMs support it, though 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 of 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` in the first VM classpath
- add `aspectwerkz-core-*.jar` and `JAVA_HOME/lib/tools.jar` in the second VM bootclasspath
- add `aspectwerkz-*.jar` and dependencies in the second VM classpath (including aspectwerkz-jdk14-*.jar)

    set JAVA_HOME=...
    set PATH=$JAVA_HOME/jre/bin:$PATH

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

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

    # For Java 1.4, add aspectwerkz-jdk14 to the classpath
    # Else for Java 5, add aspectwerkz-jdk5 [but you would have then better using JVMTI -javaagent option]

    # 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 one with your favourite 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 and JAVA_HOME/lib/tools.jar in `-Xbootclasspath/a`
- add aspectwerkz.jar and dependencies in the regular classpath

    # set AspectWerkz version and libs dependencies
    set VERSION=2.0
    set DEPS=... // AspectWerkz dependencies - 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=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 dependencies 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 and JAVA_HOME/lib/tools.jar to the `-Xbootclasspath/a:`
- add aspectwerkz.jar and dependencies in regular classpath

For more information about JDWP option refer to Sun JDWP documentation.

    # set AspectWerkz version and libs dependencies
    set VERSION=2.0
    set DEPS=... // AspectWerkz dependencies - see bin/setEnv for the complete list

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

    set BOOT_PATH=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.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: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: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 dependencies
    set VERSION=2.0
    set DEPS=... // AspectWerkz dependencies - see bin/setEnv for the complete list

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

## Offline weaving

### Introduction

AspectWerkz provides several way to weave the aspects in the application classes at build time. This is called offline weaving, offline mode, or even class post-processing.

With this mode you have to be sure to post-process the application classes as many times as required if you plan to use multiple Aspect Systems as described here.

There is mainly two ways to achieve this, allthough some variants can be built on top of them:

- Use the AspectWerkz command line tool with the `-offline` option on a specific `.class` file, directory or jar file.
- Use the `org.codehaus.aspectwerkz.compiler.AspectWerkzC` utility in an Ant or Maven script.

As you might have understood, the command line tool is delegating to the `AspectWerkzC` class after all required jars have been added to the classpath.

### Command line tool usage

The command line tool is described in a next part.

### AspectWerkzC and Ant / Maven integration

You can find several samples of Ant and Maven integration in the AspectWerkz distribution.
The following are the options supported by the AspectWerkzC tool. Most of them can be used as well in the AspectWerkz command line tool.

    # set the classpath correctly
    # see bin/setEnv in the AspectWerkz distribution

    # Add Ant-1.5 in the classpath

    java -cp ... org.codehaus.aspectwerkz.compiler.AspectWerkzC [-verbose] [-details] [-genjp] [-haltOnError] [-verify] [-cp {additional cp i}]*  {target 1} [{target i}]*

    # Use -Daspectwerkz.definition.file=... option to specify the XML definition file to use
    # Or rely on the META-INF/aop.xml and WEB-INF/aop.xml path lookup

- `-verbose`: turns on verbose mode (optional)
- `-details`: turns on detailed matching mode (optional)
- `-genjp`: turns on keeping of join point classes (optional)
- `-haltOnError`: stops the compilation at the first error (target2 will not be post-processed if it fails on target1) (optional)
- `-verify`: do some bytecode verification (mainly usefull for AspectWerkz development team) (optional)
- `-cp path1;path2/some.jar`: additional classpath needed for the compilation. Put your aspect classes in this path, and your application third parties jar if any. This is mainly needed to match on subtype patterns (java.lang.String +), where the complete classes dependencies is needed. For convenience you can use several `-cp ...` option. Be sure to use ";" or ":" as a path separator as for the regular JVM classpath option.
- `target path/classes path/application.jar`: defines the classes, classes directories and jar files to post-process. It is possible to pass as many target as needed.

A sample for Ant using the command line tool looks like the following. You will notice that the aspect classes must be in the classpath (to retrieve their annotations that defines the pointcut f.e.).

In this sample, since the command line tool is used, it is mandatory to pass the XML definition file as the second argument.

    <!-- =================================================== -->
    <!--  offline transformation of the samples -->
    <!-- =================================================== -->
    <target name="aspectwerkz:transform"
    depends="clean, aspectwerkz:init, aspectwerkz:compile, aspectwerkz:samples:aspectc">
    <exec executable="${bin.dir}/aspectwerkz.bat">
        <arg line="-offline ${basedir}/src/application/aop.xml -verbose -verify -cp ${aspect.classes} ${application.classes}"/>
    </exec>
    </target>

A sample for Ant using the AspectWerkzC class looks like the following:

    <target name="aspectwerkz:war:transform"
    depends="aspectwerkz:compile, aspectwerkz:war:aspectc">
    <java classname="org.codehaus.aspectwerkz.compiler.AspectWerkzC" fork="true">
        <classpath refid="project.class.path"/>
        <classpath>
            <pathelement path="${build.main.dir}"/><!-- needed for abstract Aspect activation -->
            <pathelement path="${build.web.dir}"/><!-- needed for Aspect activation -->
        </classpath>
        <jvmarg value="-Daspectwerkz.definition.file=${src.web.dir}/WEB-INF/aspectwerkz.xml"/>
        <jvmarg value="-Daspectwerkz.transform.verbose=true"/><!-- an AspectWerkz weaver option -->
        <arg value="-verify"/><!-- an AspectWerkzC tool option -->
        <arg value="-verbose"/><!-- an AspectWerkzC tool option -->
        <!-- below is the classes dir to post-process. It could be some jar files as well. -->
        <arg value="${build.web.dir}"/>
        <arg value="${build.main.dir}"/>
    </java>
    </target>

There is also an Ant task for this - you can read more about it here.

### Packaging the post-compiled classes

Once the application classes (or dir / jars) have been post-compiled, those have dependencies on

- AspectWerkz jars and third parties jars.
- Your own aspects classes and all aspects that might be triggered according to the `Aspect System` organization

It is then a good practice to package the aspects alongside your application just as regular classes, and then decide if AspectWerkz jars and third parties jars should be packaged within the application (f.e. in `First.war/WEB-INF/lib/`) or added to the application regular classpath. You can use the `bin/setEnv` script of the distribution for that, or change your application startup script to add those jars in the `-cp` or `-classpath` JVM classpath settings.

## Ant task for Offline weaving

An Ant task is provided for offline weaving

### Usage

First you need to activate the custom task in your Ant build.xml file with the following: (refer to Ant documentation on "taskdef" for more details)

    <!-- we assume we defined a classpath with the id="aw.class.path" for AspectWerkz jars -->
    <path id="aw.class.path">
    ...
    <pathelement path="pathToAspectWerkz.jar"/>
    ...
    </path>

    <!-- define the custom task (annotationc can be changed to what you prefer)
    <taskdef name="awc"
             classname="org.codehaus.aspectwerkz.compiler.AspectWerkzCTask"
             classpathref="aw.class.path"/>
    <!-- Note: the <taskdef> element can be nested within a <target> element at your convenience -->

    <!-- invoke the awc defined task -->
    <target name="samples:task:awc" depends="init, compile:all, samples:task:annoationc">
    <awc
        verbose="true"
        definition="${basedir}/src/samples/aop.xml"
        classpathref="project.class.path">

        <target path="${basedir}/target/samples-classes"/>
    </awc>
    </target>

### Reference

The AspectWerkzCTask task accepts the following:

- verbose: [optional] flag marking the weaver verbosity [true / false]
- genjp: [optional] flag marking the need to keep the generated join point classes [true / false]
- taskverbose: [optional] flag marking the task verbose [true / false]
- definition: [optional] path to aspect definition xml file (optional, can be found on the path as META-INF/aop.xml - even several)

Use the following parameters to configure the classpath and to point to the classes to be weaved. Those can be specified with nested elements as well / instead:

- classpath: classpath to use
- classpathref: classpath reference to use
- targetdir: directory where to find classes to weave
- targetpath: classpath where to find classes to weave
- targetpathref: classpath reference where to find classes to weave

Nested elements are similar to the "java" task when you configure a classpath:

- classpath: Path-like structure for the classpath to be used by the weaver. Similar to "java" task classpath
- targetpath: Path-like structure for the class to be weaved

Some rarely used options are also available:

- backupdir: directory where to backup original classes during compilation, defautls to ./_aspectwerkzc
- preprocessor: fully qualified name of the preprocessor. If not set the default is used.

## AspectWerkz command line tool

### Environment setting

The command line tool is the easiest way to start using AspectWerkz since it provides all classpath settings for both class load time weaving and offline post-processing.

To use it, you first need to set the `ASPECTWERKZ_HOME` environment variable to the directory containing the AspectWerkz installation.

    set ASPECTWERKZ_HOME=C:\aop\aspectwerkz\

    # export might be needed on Linux / Unix OS.

    # The tool assumes JAVA_HOME environment variable is correctly set.

The command line tool is then in `ASPECTWERKZ_HOME/bin` directory. You can add this directory to your `PATH` environment variable if you want.
Type `aspectwerkz` without any arguments to print the usage message.

### Offline compilation

To post-process all class files in a specific directory (recursively), jar or zip file:

`aspectwerkz -offline <definition file> [-verbose] [-details] [-genjp] [-verify] [-haltOnError] [-cp <classpath>]* <target classes to transform>+`

- The 'definition file' option is the path to the XML definition file (mandatory).
- Turns on `-verbose` to follow each step of the processing (optional).
- Turns on `-details` to follow the pointcut matching (optional).
- Turns on `-genjp` to keep generated joinpoint strcutures (optional).
- Turns on `-verify` to verify all weaved class according to the Java Class Format specification (optional, mainly usefull for AspectWerkz development team).
- When an error occurs, all classes of the current target are restored to their initilal state and the processing goes on with the next target unless `-haltOnError` was set (optional). In this case the processing stops. Else a complete status about successfull and failed targets is printed at the end of all target processing.
- The 'classpath' option is the classpath needed for compilation but not to be transformed (eg `-cp myAspects.jar;servletAPI.jar`). It is possible to use several `-cp <classpath>` option instead of doing concatenation.
- The 'target classes to transform' option specifies the classes to transform. It must the path to the root directory of the classes you want to transform, or a jar file or a zip file. Several targets can be passed in one call (eg `toTransform.jar /classes otherToTransform.jar`).

Note: when you then are running the application (without using the `aspectwerkz` command) you have to (apart from feeding it with the definition) put the aspectwerkz jars along with all the the dependency jars the `ASPECTWERKZ_HOME/lib` directory in your classpath. Read more about it here.

### Class load time weaving

It is possible to use the command line tool as a replacement of the `JAVA_HOME/bin/java` command. In such a case, the command line tool will detect a suitable option for you and will enable class load time weaving.

This is the easiest way to give a try to class load time weaving although you should read and choose the best option by yourself by reading more on this topic here.

Starting up an application (use -Daspectwerkz.definition.file=.. or have META-INF/aop.xml and WEB-INF/aop.xml files in the classpath and applications packaging as explained in this section):

`aspectwerkz [-options] <main class> [args...]`

Starting up an application using an executable jar file:

`aspectwerkz [-options] -jar <jar file> [args...]`