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

## Introduction

`AspectWerkz` uses a class bytecode manipulation technique for applying aspects to existing Java classes. This means there is no additional language syntax or precompiler necessary. It does mean that class bytecode must be intercepted and changed some time before it gets executed. Fortunately, `AspectWerkz` provides both offline and online class interception and manipulation. Offline manipulation means all class files are scanned and modified in place sometime before the application gets executed. Online interception means classes are intercepted as they are loaded by a running application. Both techniques provide costs and benefits. Offline interception allows an entire set of classes to be changed once, making runtime execution more efficient, at the cost of making the development cycle less efficient (you've have to manipulate a class file every time you recompiled the Java source). Online interception makes application execution less efficient (because the class must be modified while the program is running), but eliminates the extra step of changing the class file on every compile.

These instructions describe how to create an execution type and a debugger type in `NetBeans` to implement online interception for use during the development cycle.

Creating the execution and debugger types affects only the project you have open at the time. You must follow these instructions for each separate `NetBeans` project.

The instructions have been prepared for `NetBeans 3.6`.

## Approach

These instructions demonstrate using the prepared bootclasspath approach to online weaving, by creating a new execution type and debugger type. This approach works well with NetBeans.

## Initial Setup

### Install AspectWerkz

Install the `AspectWerkz` distribution, or copy the following jars to an accessible location.

- aspectwerkz- version.jar
- aspectwerkz-core- version.jar
- jrexx- version.jar
- trove- version.jar

### Create an Enhanced Class Loader Jar

Using instructions located here to create the enhanced class loader jar. Place the jar in a location accessible by `NetBeans`.

## Integrate into Project

The following instructions must be repeated for each project that will use `AspectWerkz`.

## Create an Execution Type

- From the main menu, select Tools/Options
- Right click 'Execution Types', choose 'New', and then choose 'External Execution'. Enter 'AspectWerkz Prepared Boot External Execution' or some appropriate name of your choosing. Click the 'Finish' button.
- Select the newly created execution type.
- Change the External Process Arguments to the following value:

       -Xbootclasspath/p:/path/to/enhanced/class/loader.jar -Xbootclasspath/a:{bootclasspath}
       {assertEnabled} -cp {filesystems}{:}{classpath} {classname} {arguments}

  This should all be on one line, with a space between `{bootclasspath}` and `{assertEnable}`.
  Note that on Windows, you'll need to surround the path to the enhanced class loader jar in double quotes if there are embedded spaces in the path.
- Add the following jars to the Boot Classpath:
  - aspectwerkz-core- version.jar
- Make any other changes to the execution type to suit your needs.

## Create a Debugger Type

- If the options window is not already open, from the main menu, select Tools/Options
- Right click 'Debugger Types', choose 'New', and then choose 'Default Debugging'. Enter 'AspectWerkz Prepared Boot Debubgger' or some appropriate name of your choosing. Click the 'Finish' button.
- Select the newly created debugger type.
- Change the External Process Arguments to the following value:

      -Xbootclasspath/p:/path/to/enhanced/class/loader.jar -Xbootclasspath/a:{bootclasspath}
       {classic}{assertEnabled}{debuggerOptions} -Djava.compiler=NONE -classpath {q}{filesystems}{q} {main}

  This should all be on one line, with a space between `{bootclasspath}` and `{classic}`.
  Note that on Windows, you'll need to surround the path to the enhanced class loader jar in double quotes if there are embedded spaces in the path.
- Add the following jars to the Boot Classpath:
  - aspectwerkz-core- version.jar
- Make any other changes to the execution type to suit your needs.

## Activating AspectWerkz in the Project

So far, we've only created the customized execution and debugger types. To actually use these in the project, the following steps are necessary.

### Select the AspectWerkz Execution Type as the Default

- If the options window is not already open, from the main menu, select Tools/Options
- Select 'Editing', then select 'Java Sources'.
- Choose the newly created AspectWerkz execution type as the 'Default Executor'.

### Select the AspectWerkz Debugger Type as the Default

- If the options window is not already open, from the main menu, select Tools/Options
- Select 'Editing', then select 'Java Sources'.
- Choose the newly created AspectWerkz execution type as the 'Default Debugger'.

### Mount Necessary Jar Files

Mount the following jar files to the project:

- aspectwerkz- version.jar
- jrexx- version.jar
- trove- version.jar

### Configure aspectwerkz.xml

Place the `aspectwerkz.xml` into a filesystem mounted in the project. When a Java program is run, all filesystems are placed onto the classpath by `NetBeans`.