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
  • javassist- 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:
    • javassist- version.jar
    • 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:
    • javassist- version.jar
    • 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
  • javassist- 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.