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

## Frequently Asked Questions

AspectWerkz 2.x

1. What are the gotchas when migrating from 1.x to 2.x?
2. What is this jit join point I heard about in the docs, in articles, or with this `-genjp` option?
3. What are the common steps to perform when I have some troubles?

General

1. What is AspectWerkz?
2. How can I use it without starting up the application or application server with the command line tool?
3. What does the aspectwerkz command line tool do?
4. If I use the post-processor, I'll lose the possibility to change my configurations at runtime, right?
5. Is there any DTD or XML Schema I can use to write the AspectWerkz XML definition fil?
6. Why can't I build AspectWerkz in a directory whose name contains whitespaces?

BEA integration

1. Does AspectWerkz support BEA JRockit?
2. I am having troubles with WebLogic Server / Integration when using AspectWerkz, with a "getEncoding" error !

Other

1. Does AspectWerkz supports custom JRE like IBM ones?
2. Does AspectWerkz support BEA JRockit?
3. Does AspectWerkz support Java 1.3?
4. Can I weave classes from my JDK?
5. What are the jar needed at runtime? Is there a nodeps jar?

## AspectWerkz 2.x

What are the gotchas when migrating from 1.x to 2.x?

  - Build and develop for Java 5 -
    To build on Java 5 you will have to put the `./lib/aspectwerkz-jdk5-2.0.jar` on the classpath instead of `./lib/aspectwerkz-jdk14-2.0.jar`. Same if you want to run it inside an IDE, or use an Ant script. This jar contains the Java 5 implementations of the AspectWerkz annotations.
  - No more `perThread` deployment model -
    We have removed the `perThread` deployment model for both aspects and mixins. It should have never been added in the first place. We are working on supporting the much more fine-grained and expressive `percflow` and `percflowbelow`.
  - Currently no `perJVM` deployment model for mixins -
    This will most likely be added for the 2.0 final release.
  - No more annotation proxies -
    This implementation has been replaced by a better one, in which you only have to write an interface that is very similar to a Java 5 annotation component. For details see this section.
  - New Mixin implementation -
    The Mixin implementation is completely new, both the way it is implemented and defined. For details see this section.
  - For mixin definition, `@Introduce` and `<introduce ...>` -
    has been replaced by `@Mixin` and `<mixin ...>` (child of <system> XML element)
  - For interface only introduction, `@Implements` and `<introduce ...>` -
    Has been replaced by `@Introduce` and `<introduce ...>` (child of <aspect> XML element)
  - Dynamic AOP requires AspectWerkz native library in `PATH` - unless using Java 5.
    To make use of the dynamic features, such as runtime deployment and undeployment, you need to have the AspectWerkz native library (*.dll, *.so or *.jnilib) in your `PATH`. These can be found here.
    A consequence is that the dynamic tests will fail if you have not done this. The native library is not needed with Java 5.

What is this jit join point I heard about in the docs, in articles, or with this `-genjp` option?
  AspectWerkz 2.x architecture enables statically compilation of the advices. This does not means you have to do all the weaving in compilation phase at all. This means that in your classes that AspectWerkz instruments, the advices are invoked statically (not reflectively). This ensure maximum speed.
  To enable that, the architecture relies on the concept of jit join point. This is an AspectWekrz generated structure (very little class) that is statically invoked from the weaved classes and that in turn statically invokes the advices. This jit join point is usually generated on the fly (ie when the weaved class gets loaded in the JVM) and can be replaced on the fly (this is how the dynamic deployment works internally).
  In some cases it is interesting to compile this jit join point ahead of time (for debugging purpose or for restricted environment that do not allow jit definition of classes due to java security restrictions etc). In such case, you can use the `-genjp` option of the offline mode to generated those jit join point classes as part of the weaving process and output, and thus package them with your application.

What are the common steps to perform when I have some troubles?
  The following options and process are common answers to problems:
  - use -Daspectwerkz.transform.verbose=true (or -verbose with offline mode command line tool and Ant task) to turn on the verbose mode that will tell more when classes gets presented to the weaver.
  - use -Daspectwerkz.transform.details=true (or -details with offline mode command line tool and Ant task) to turn on pointcut matching verbose mode that will tell more when pointcuts match. This is usefull to understand why "nothing happen !" or why "the application is very low to start up!" (due to a pointcut matching almost every single instruction f.e.). The output will print message about "earlymatch" and "match". An early match means that there might be a match but that further analysis of the class beeing weaved is needed. A match thus means a pointcut match (thus an actual join point). When a mixin is used, you only see early matches.
  - use -Daspectwerkz.transform.dump=* (or -Daspectwerkz.transform.dump=*,before) to dump to disk the weaved classes. The second form dumps classes before and after weaving. The dump folder cannot be changed and is "./_dump" relative to application startup folder. You can replace "*" with some package prefix like "com.bar.*" to narrow the dump.
  - use offline mode to see how it goes before using online weaving (that can be sometime more complex to set up)
  - make sure you practice successfully the HelloWorld tutorial in the tutorial section
  - ask for help on the mailling lists (you have to subscribe by sending an email before posting)

## General

What is AspectWerkz?

  `AspectWerkz` is a dynamic, lightweight and high-performant AOP/AOSD framework for Java.

How can I use it without starting up the application or application server with the command line tool?

  You can post-process (instrument/transform) your source files before use. See the Offline Weaving section.

  You can also use one of the several options to start your application with AspectWerkz enabled without the command line tool.
  For a complete discussion on this topic, see the Weaving section.

  With 2.x you can also use the AWProxy API. See the AWProxy section.

What does the aspectwerkz command line tool do?

  Basically it just invokes the normal java command line tool by calling a class that intercepts the normal class loading scheme before it invokes the main class specified. This means that you can just substitute the normal call to:
  `java -cp .. -D.. mainclass args` with: `aspectwerkz -cp .. -D.. mainclass args` and everything should work as before, the only difference is that all classes that are loaded will be transformed (if they are defined to). You can even hack the startup script of your favorite application server and start it up using the `aspectwerkz` command line tool as outlined above, or using directly aspectwerkz-core- version.jar facilities.

  The key advantage of the command line tool when you startup your application thru it is that it provides an autodetection mechanism for java 1.3 / java 1.4 support. The online architecture differs between these two java version.
  For full control on the behavior of AspectWerkz online mode (dump class, verbosity), you should avoid using the command line tool.
  Read more in the Weaving section.

If I use the post-processor, I'll lose the possibility to change my configurations at runtime, right?

  Actually no. You will still be able to to all the things covered in the Hot deployment section of the documentation.

Is there any DTD or XML Schema I can use to write the AspectWerkz XML definition fil?

  The DTD is provided since 0.8. Each distribution comes with a bundled DTD so that it is not looked for on the web at runtime.
  When you write your XML definition file, add the following at the top of your XML.

                              <!DOCTYPE aspectwerkz PUBLIC
          "-//AspectWerkz//DTD 1.0//EN"
          "http://aspectwerkz.codehaus.org/dtd/aspectwerkz_1_0.dtd">

  The DTD for the latest release for 2.x is also always referenced with

                              <!DOCTYPE aspectwerkz PUBLIC
          "-//AspectWerkz//DTD//EN"
          "http://aspectwerkz.codehaus.org/dtd/aspectwerkz2.dtd">

  The DTD for the latest release for 1.x is also always referenced with

                              <!DOCTYPE aspectwerkz PUBLIC
          "-//AspectWerkz//DTD//EN"
          "http://aspectwerkz.codehaus.org/dtd/aspectwerkz.dtd">

Why can't I build AspectWerkz in a directory whose name contains whitespaces?

  The Ant or Maven based build will fail if the `ASPECTWERKZ_HOME` (basedir) is a directory whose name contains whitespace(s). This would drastically complexify the script if we had to escape the whitespaces and thus this is not supported for convenience reason.

  The AspectWerkz online and offline mode (command line tool etc) support path whose elements contains whitespace(s) in their names.

## BEA integration

Does AspectWerkz support BEA JRockit?
  AspectWerkz supports BEA JRockit thru a dedicated module wich relies on a low level BEA API. It makes AOP integration on BEA JRockit much easier than for HotSpot. Read more.

I am having troubles with WebLogic Server / Integration when using AspectWerkz, with a "getEncoding" error !
  This is a known conflict between piccolo.jar that ships with AspectWerkz and the WebLogic 8.1 product line. Rename the lib/piccolo.jar in lib/piccolo.jar.IGNORE in the AspectWerkz distribution. Note: this is fixed as of 2.0 final since the distribution only contains a piccolo.jar.java13 that you have to rename for use with java 1.3

## Other

Does AspectWerkz supports custom JRE like IBM ones?
  AspectWerkz supports all java environments thru offline mode. With online mode, AspectWerkz hooks at the class loader level. AspectWerkz provides a transparent mechanism that support the IBM JRE which bundles a specific `java.lang.ClassLoader`.

Does AspectWerkz support BEA JRockit?
  AspectWerkz supports BEA JRockit thru a dedicated module wich relies on low level BEA API.

Does AspectWerkz support Java 1.3?
  Yes it does.
  First from the distribution `/lib`, rename `piccolo-xxx.jar.java13` to `piccolo-xxx.jar` (keep the -xxx version number) and add the `piccolo-1.03.jar` file in your `JAVA_HOME/jre/lib/ext/`.
  You will need to add xerces.jar as well at this location.
  Second, start your VM with the extra option `-Djavax.xml.parsers.SAXParserFactory=com.bluecast.xml.JAXPSAXParserFactory`.
  If you encounter troubles in your environment (IDE etc), just remove the `piccolo-1.03.jar` file from your `JAVA_HOME/jre/lib/ext/` when done.

Can I weave classes from my JDK?
  Yes you can. We don't support such a usage since you should not modify your JDK classes. A how-to has been posted in February 2005 on the user mailling list. You can search in the mailing list archives.

What are the jar needed at runtime? Is there a nodeps jar?
  The jar needed at runtime are aspectwerkz-V.jar, aspectwerkz-jdkX-V.jar, dom4j-V.jar, jrexx-V.jar and trove-V.jar. When using Offline compilation, annotation compilation and Ant task for those, you further need ant-V.jar and qdox-V.jar. When using Java 1.3, you further need piccolo-V.jar (see other entry in this FAQ) or any other XML parser implementation.
  There is also an aspectwerkz-nodeps-jdkX-V.jar that contains all you need for the runtime.
  Make sure you are using the correct version for your JDK (use the jdk14 for Java 1.3 as well).