Chapter 10. Running Aspectized Applications
Prev |  | Next

## Chapter 10. Running Aspectized Applications

This section will show you how to run JBoss AOP with standalone applications and how to run it integrated with the JBoss application server.

## 10.1. Loadtime, Compiletime and HotSwap Modes

There are 3 different modes to run your aspectized applications. Precompiled, loadtime or hotswap. JBoss AOP needs to weave your aspects into the classes which they aspectize. You can choose to use JBoss AOP's precompiler to accomplish this (Compiletime) or have this weavining happen at runtime either when the class is loaded (Loadtime) or after it (HotSwap).

Compiletime happens before you run your application. Compiletime weaving is done by using the JBoss AOP precompiler to weave in your aspects to existing .class files. The way it works is that you run the JBoss AOP precompiler on a set of .class files and those files will be modified based on what aspects you have defined. Compiletime weaving isn't always the best choice though. JSPs are a good instance where compiletime weaving may not be feasible. It is also perfectly reasonable to mix and match compile time and load time though. If you have load-time transformation enabled, precompiled aspects are not transformed when they are loaded and ignored by the classloader transformer.

Loadtime weaving offers the ultimate flexibility. JBoss AOP does not require a special classloader to do loadtime weaving, but there are some issues that you need to think about. JDK 1.4 does not have a standard simple way of transforming/instrumenting classes at runtime, so what JBoss AOP does is have a way to modify `java.lang.ClassLoader.class` to add the appropriate hooks. Its pretty simple. Take a look at the source under `org.jboss.aop.hooks` package and you'll see what we're doing is not that magical at all. Although this JDK 1.4 works with JDK 5, JDK5 actually has a simple standard mechanism of hooking in a class transformer through the `-javaagent`. JBoss AOP an additional load-time transformer that can hook into classloading via this standard mechanism.

Load-time weaving also has other serious side effects that you need to be aware of. JBoss AOP needs to do the same kinds of things that any standard Java profiling product needs to do. It needs to be able to process bytecode at runtime. This means that boot can end up being significantly slowed down because JBoss AOP has to do a lot of work before a class can be loaded. Once all classes are loaded though, load-time weaving has zero effect on the speed of your application. Besides boottime, load-time weaving has to create a lot of Javassist datastructure that represent the bytecode of a particular class. These datastructures consume a lot of memory. JBoss AOP does its best to flush and garbage collect these datastructures, but some must be kept in memory. We'll talk more about this later.

HotSwap weaving is a good choice if you need to enable aspects in runtime and don't want that the flow control of your classes be changed before that. When using this mode, your classes are instrumented a minimum necessary before getting loaded, without affecting the flow control. If any joinpoint becomes intercepted in runtime due to a dynamic AOP operation, the affected classes are weaved, so that the added interceptors and aspects can be invoked. As the previous mode, hot swap contains some drawbacks that need to be considered.

## 10.2. Regular Java Applications

JBoss AOP does not require an application server to be used. Applications running JBoss AOP can be run standalone outside of an application server in any standard Java application. This section focuses on how to run JBoss AOP applications that don't run in the JBoss application server.

### 10.2.1. Precompiled instrumentation

Running a precompiled aop application is quite similar to running a normal java application. In addition to the classpath required for your application you need to specify the files required for aop:

- `javassist.jar`
- `trove.jar`
- `concurrent.jar`
- `jboss-common.jar`
- `jboss-aop.jar`
- or `jboss-aop-jdk50.jar`

- depending on if you are using JDK 1.4 (jboss-aop.jar) or JDK 5.0 (jboss-aop-jdk50.jar)

JBoss AOP finds XML configuration files in these two ways:

- You tell JBoss AOP where the XML files are. Set the `jboss.aop.path` system property. (You can specify multiple files or directories separated by ':' (*nix) or ';' (Windows), i.e. `-Djboss.aop.path=jboss-aop.xml;metadata-aop.xml`) If you specify a directory, all `aop.xml` files will be loaded from there as well.
- Let JBoss AOP figure out where XML files are. JBoss AOP will look for all XML files that match this pattern `/META-INF/jboss-aop.xml`. So, if you package your jars and put your JBoss AOP XML files within `/META-INF/jboss-aop.xml`, JBoss AOP will find these files.

If you are using annotated bindings (See Chapter "Annotated Bindings"), you must tell JBoss AOP which JARS or directories that may have annotated @Aspects. To do this you must set the `jboss.aop.class.path` system property. (You can specify multiple jars or directories separated by ':' (*nix) or ';' (Windows), i.e. `-Djboss.aop.class.path=aspects.jar;classes`)

So to run a precompiled AOP application, where your jboss-aop.xml file is not part of a jar, you enter this at a command prompt:

    $ java -cp=<classpath as described above> -Djboss.aop.path=<path to jboss-aop.xml> \
             -Djboss.aop.class.path=aspects.jar
             com.blah.MyMainClass

To run a precompiled AOP application, where your application contains a jar with a META-INF/jboss-aop.xml file, you would need to do this from the command-line:

    $ java -cp=<classpath as described above> com.blah.MyMainClass

In the /bin folder of the distribution we have provided batch/script files to make this easier. It includes all the aop libs for you, so you just have to worry about your files. The usage for JDK 1.4 is:

    $ run-precompiled classpath [-aoppath path_to_aop.xml] [-aopclasspath path_to_annotated] \
          com.blah.MyMainClass [args...]

For JDK 1.5:

    $ run-precompiled15 classpath [-aoppath path_to_aop.xml] [-aopclasspath path_to_annotated] \
          com.blah.MyMainClass [args...]

If your application is not in a jar with a META-INF/jboss-aop.xml file, you must specify the path to your `*-aop.xml` files in the `-aoppath` parameter, and if your class comtains aspects configured via annotations ( `@Aspect` etc.) you must pass in this classpath via the `-aopclasspath` parameter. (For JDK 1.4, you must have compiled the annotations first).

### 10.2.2. Loadtime

This section describes how to use loadtime instrumentation of classes with aop. The classes themselves are just compiled using Java, but are not precompiled with the aop precompiler. (If you want to use annotations with JDK 1.4, you will still need to use the JDK 1.4 Annotation Compiler). In the examples given if your classes are contained in a jar with a META-INF/jboss-aop.xml file, you would omit the `-Djboss.aop.path` system property.

#### 10.2.2.1. Loadtime JDK 1.4

In order to do loadtime weaving of aspects with JDK 1.4, we had to massage `java.lang.ClassLoader`. `java.lang.ClassLoader` is modified to add hooks for class transformation before class loading. It is very similar to JDK 5's built in ability to define class transformers. What you have to do is generate a modification of `java.lang.ClassLoader` and add this class to the default bootstrap class path (bootclasspath) for your classes to get instrumented at loadtime. The classes used are dependent upon the VM. At present this custom classloader has only been tested with Sun's J2SE 1.4.x and 5.0. The steps to compile and use the custom classloader are shown below.

    $ java -cp=<classpath as described above>  \
           org.jboss.aop.hook.GenerateInstrumentedClassLoader <output dir>

For the following example, the `aop boot classpath` should be the `output dir` specified above, followed by the jars needed for AOP, i.e. `javassist.jar`, `trove.jar`, `concurrent.jar`, `jboss-common.jar` and `jboss-aop.jar`. You separate the classpath elements as normal, with ';' (Windows) or ':' (Unix). The path to your classes should NOT be included here! You then use this `aop boot classpath` as the argument for `-Xbootclasspath` option as shown here:

    $ java -Xbootclasspath/p:<aop boot classpath as described> \
          -Djboss.aop.path=<path to jboss-aop.xml> \
          -classpath <path to your classes> com.blah.MyMainClass

In the /bin folder of the distribution we have provided batch/script files to make this easier. It includes all the aop libs for you, so you just have to worry about your files:

    $ run-load-boot classpath [-aoppath path_to_aop.xml] [-aopclasspath path_to_annotated] \
          com.blah.MyMainClass [args...]

The parameters have the same meaning as for the run-precompiled scripts. (Since this is for JDK 1.4, you must have compiled the annotations first). This script both creates the instrumented class loader and makes sure that that the JAVA_HOME environment variable has been set (Your job is to make sure it points to a 1.4 distribution!).

#### 10.2.2.2. Loadtime with JDK 5

JDK 5.0 has a pluggable way of defining a class transformer via the `java.lang.instrument` package. JBoss AOP uses this mechanism to weave aspects at class load time with JDK 5. Using loadtime with JDK 5 is really easy. All you have to do is define an additional standard switch on the Java command line. `-javaagent:jboss-aop-jdk50.jar`. For these examples make sure that you use `jboss-aop-jdk50.jar` and not `jboss-aop.jar` in your classpath. Here's how run an AOP application in JDK 5.0 with loadtime instrumentation, where your jboss-aop.xml file is not part of a jar:

    $ java -cp=<classpath as described above> -Djboss.aop.path=<path to jboss-aop.xml> \
          -javaagent:jboss-aop-jdk50.jar com.blah.MyMainClass

And to run an AOP application in JDK 5.0 with loadtime instrumentation, where your application contains a jar with a META-INF/jboss-aop.xml file:

    $ java -cp=<classpath as described above> -javaagent:jboss-aop-jdk50.jar \
          com.blah.MyMainClass

In the /bin folder of the distribution we have provided batch/script files to make this easier. It includes all the aop libs for you, so you just have to worry about your files. The usage for JDK 1.5 is:

    $ run-load15 classpath [-aoppath path_to_aop.xml] [-aopclasspath path_to_annotated] \
          com.blah.MyMainClass [args...]

The parameters have the same meaning as for the run-precompiled scripts.

If you invoke the previous `java` examples with ant, by using the ant `java` task, make sure that you set `fork="true"` in the ant `java` task. Failure to do so, causes the `java` task to execute in the same VM as ant which is already running. This means that the special classloader used to do the loadtime transformations does not replace the standard one, so no instrumentation takes place.

#### 10.2.2.3. Loadtime using JRockit

In JRockit the -Xbootclass/p option does not work, so we cannot replace the classloader. Instead we plug natively into its JVM using vendor specific hooks to provide transformation when a class is loaded. All you have to do is define an additional switch on the Java command line. `-Xmanagement:class=org.jboss.aop.hook.JRockitClassPreProcessor` Here's how run an AOP application in JDK 1.4 with loadtime instrumentation, with JRockit:

    $ java -cp=<classpath as described above> -Djboss.aop.path=<path to jboss-aop.xml> \
          -Xmanagement:class=org.jboss.aop.hook.JRockitClassPreProcessor com.blah.MyMainClass

The above will also work with JRockit 5.0, but this can also use the "normal" -javaagent switch.

#### 10.2.2.4. Improving Loadtime Performance

Boss AOP needs to do the same kinds of things that any standard Java profiling product needs to do. It needs to be able to process bytecode at runtime before a class is loaded. JBoss AOP has to do a lot of work before a class can be loaded. This means that boot time can end up being significantly slowed down. Once all classes are loaded though, load-time weaving has zero effect on the speed of your application.

Besides boottime, load-time weaving has to create a lot of Javassist datastructures that represent the bytecode of a particular class. These datastructures consume a lot of memory. JBoss AOP does its best to flush and garbage collect these datastructures, but some must be kept in memory. This section focuses on how you can improve the performance of Loadtime weaving.

Increase the Java Heapspace

  In Java, when your application is getting close to eating up all of its memory/heapspace, the Java Garbage Collector starts to run more frequently and aggressively. When the GC starts running more often the performance of your application will suffer. JBoss AOP does its best to balance bootup speed vs. memory consumption, but it does require loading bytecode into Javassist datastructures so it can analyze and transform a class. For speed purposes, the datastructures are cached thus leading to the extra memory consumption. Javassist structures of non-transformed classes are placed a SoftReference cache, so they are GC'd when memory is running low. Transformed classes, however, are locked in the cache. Transformed classes are help in memory, as they may effect pointcut matching on classes that haven't been loaded yet.

  To increase your Heap size, use the standard `-Xmx` switch.

Filtering

  Filtering probably has the greatest effect on overall boot-time speed. If you've ever worked with a Java profiling product before, you probably noticed that it has an option to filter classes that you are not interested in profiling. THis can speed up performance of the tool. JBoss AOP has to analyze every class in the system to make sure it does not need to be transformed. THis is one reason why load-time weaving can be so slow. You can give JBoss AOP a lot of help by specifying sets of classes that do not need to be transformed.

  To enable filtering, you can use the `jboss.aop.exclude` System Property. This System Property is a comma delimited list. The strings in the list can be package names and/or classnames. No wildcards are allowed. Packages/classes within this list will ignored by JBoss AOP.

                           java -Djboss.aop.exclude=org.jboss,org.apache ...

  There is also a mirror opposite of exclude. The System Property `jboss.aop.include` overrides any thing specified with exclude.

Turn off optimizations

  To increase overall runtime performance, JBoss AOP has to dynamically create a lot of extra code. If you turn off these optimizations, JBoss AOP can weave a bit quicker. There is a good chance, depending on your application that you will not even notice that these optimizations are turned off. The `jboss.aop.optimized` system property can be set to turn off optimizations.

                           java -Djboss.aop.optimized=false ...

Turn off pruning

  JBoss AOP tries to aggressive prune cached Javassist structures. This may, may not have a tiny effect on performance. The `jboss.aop.prune` system property can be set to turn off pruning.

                           java -Djboss.aop.prune=false ...

-client/-server

  Strangely enough, it seems that the -client VM switch is a little faster for JBoss AOP loadtime weaving that -server. If you are using the -server VM, trying switching to -client (the default).

bootclasspath Vs. JDK5 -javaagent

  It is significantly slower to use the -javaagent vs. the JDK 1.4 bootclasspath approach. So, if you are using JDK5, use the JDK1.4 bootclasspath approach.

Ignore

  A way to completely ignore classes from being instrumented. This overrides whatever you have set up using the include/exclude filters. The system property is `jboss.aop.ignore`, and you can use wildcards in the classnames. As for include/exclude you may specify a comma separated list of class name patterns. This following example avoids instrumenting the cglib generated proxies for hibernate:

                              java -Djboss.aop.ignore=*$$EnhancerByCGLIB$$*

### 10.2.3. HotSwap

The HotSwap feature allows bytecode of your classes to be weaved in runtime. This results in application flow control changes to your classes only when joinpoints become intercepted (to do this, use the dynamic aop funcionality provided by JBoss AOP). This is a mode to be considered when you want to assure the flow control of your classes will be kept intact until a binding or a interceptor is added.

This mode is currently provided through the `java.lang.instrument.Instrumentation` hot swap functionality, which is part of the JVMTI (Java Virtual Machine Tool Interface) added in JDK5. So, you cannot run JBoss AOP in this mode when using a previous JDK version.

To enable HotSwap, you have to add an argument to the Java command line in a very similar way to the "Loadtime with JDK5" mode: `-javaagent:jboss-aop-jdk50.jar=-hotSwap`. The difference is that the `-hotSwap` argument was added to the agent parameter list.

This way, if your jboss-aop.xml file is contained in a jar file, run:

    $ java -cp=<classpath as described above> -Djboss.aop.path=<path to jboss-aop.xml> \
    		-javaagent:jboss-aop-jdk50.jar=-hotSwap com.blah.MyMainClass

And if your jboss-aop.xml file is contained in a jar, run the following command line:

    $ java -cp=<classpath as described above> -javaagent:jboss-aop-jdk50.jar=-hotSwap \
    		com.blah.MyMainClass

The `run-load15HotSwap` batch/script files contained in the /bin folder of the distribution are similar to the `run-load15` ones, described in the previous subsection. All aop libs are included in these script files. To use them, run:

    $ run-load15 classpath [-aoppath path_to_aop.xml] [-aopclasspath path_to_annotated] \
    		com.blah.MyMainClass [args...]

When hotswap is enabled, the prunning of classes is turned off. Therefore, if you try to configure the jboss.aop.prune option as `true`, this setup will be ignored.

As with the "Loadtime with JDK5" mode, the HotSwap mode results in a boot time delay. Besides this drawback, the execution of some dynamic aop operations may be slower than in the other modes, when classes need to be hot swapped. The available options to tune performance are the same as described in the "Improving Loadtime Performance" subsection, except the pruning of classes.

## 10.3. JBoss Application Server

JBoss AOP is integrated with JBoss 4.0.1+ and JBoss 3.2.6+ application server. The integration steps are different depending on what version of JBoss AS you are using and what JDK version you are using. It is also dependent on whether you want to use loadtime or compiletime instrumentation.

If you wish to use JBoss AS 4.0.0 you will need to use JBoss AOP 1.0 Final since later releases of JBoss AOP leverage improvements in JBoss's deployement architecture. If you do this please consult the docs for JBoss AOP 1.0 Final. It is recommended though that you use the latest versions of JBoss AOP and AS.

Based on what JDK you are on and what loadtime weaving option you want to you, you must configure JBoss AS differently.

### 10.3.1. Packaging AOP Applications

To deploy an AOP application in JBoss you need to package it. AOP is packaged similarly to SARs(MBeans). You can either deploy an XML file directly in the deploy/ directory with the signature *-aop.xml along with your package (this is how the base-aop.xml, included in the `jboss-aop.deployer` file works) or you can include it in the jar file containing your classes. If you include your xml file in your jar, it must have the file extension .aop and a jboss-aop.xml file must be contained in a META-INF directory, i.e. `META-INF/jboss-aop.xml`.

If you want to create anything more than a non-trivial example, using the .aop jar files, you can make any top-level deployment contain a .aop file containing the xml binding configuration. That is you can have a .aop file in an .ear file, or a .aop file in a war file etc. The bindings specified in the `META-INF/jboss-aop.xml` file contained in the .aop file will affect all the classes in the whole war!

### 10.3.2. JBoss 4.x and JDK 1.4

JBoss AOP comes distributed with the JBoss 4.x Application Server. It is best to download the latest version and update your JBoss Application Server installation as described in the "Installing" chapter of this guide. Also, the version distributed with JBoss 4.x Application Server may not be up to date. Check http://www.jboss.org/products/aop to see if a new version of JBoss AOP is available. To install a new version remove the jboss-aop.deployer file from the JBoss AS deploy/ directory and copy the jboss-aop.deployer directory from the JBoss AOP distribution to the JBoss AS deploy/ directory. This jboss-aop.deployer/ is in the JBoss AOP distribution within the jboss-40-install/ directory.

JBoss 4.x Application Server works out of the box with precompiled applications. If you want to do load-time transformations, you must edit jboss-aop.deployer/META-INF/jboss-service.xml as follows:

The `jboss-aop.deployer` file contains some MBeans that deploy and manage the AOP framework.

                      <mbean code="org.jboss.aop.deployment.AspectManagerService"
             name="jboss.aop:service=AspectManager">
             <attribute name="EnableLoadtimeWeaving">false</attribute>
             <!-- These switches are only relevant when EnableLoadtimeWeaving is true -->
             <attribute name="SuppressTransformationErrors">true</attribute>
             <attribute name="Prune">true</attribute>
             <attribute name="Include">org.jboss.test</attribute>
             <attribute name="Exclude">org.jboss.</attribute>
             <attribute name="Optimized">true</attribute>
             <attribute name="Verbose">false</attribute>
          </mbean>

          <mbean code="org.jboss.aop.deployment.AspectDeployer"
             name="jboss.aop:service=AspectDeployer">
          </mbean>

By default, JBoss application server will not do load-time bytecode manipulation of AOP files. You can turn load-time on by setting the EnableLoadtimeWeaving attribute to true. If SuppressTransformationErrors is true failed bytecode transformation will only give an error warning. This flag is needed because sometimes a JBoss deployment will not have all the classes a class references.

The next thing you have to do is create a new `java.lang.ClassLoader.class`. This new class will bytecode modify a copy of java.lang.ClassLoader.class to put in the appropriate hooks for loadtime transformation. There is a script in the bin/ directory of the JBoss-AOP distribution to create this class and also create a jar from it.

    $ cd jboss-aop1.3.bin
    $ create-pluggable-jboss-classloader.sh

This will create a jboss-classloader-transformer.jar. Copy this jar to the bin/ directory of your JBoss Application server distribution.

Next, you need to copy the jdk14-pluggable-instrumentor.jar from the lib/ directory of your JBoss AOP distribution to the bin/ directory of your JBoss application server installation. Next edit run.sh or run.bat (depending on what OS you're on) and add the following to the JAVA_OPTS environment variable

On Unix/linux edit run.sh (note the `:` separating the bootclasspath entries)

    JAVA_OPTS="$JAVA_OPTS -Dprogram.name=%PROGNAME% \
    -Xbootclasspath/p:jboss-classloader-transformer.jar:jdk14-pluggable-instrumentor.jar"

Note that if you are using a cygwin shell on Windows, you will need to use a semicolon instead of a colon to separate the bootclasspath jars:

    JAVA_OPTS="$JAVA_OPTS -Dprogram.name=%PROGNAME% \
    -Xbootclasspath/p:jboss-classloader-transformer.jar;jdk14-pluggable-instrumentor.jar"

On Windows edit run.bat (note the `;` separating the bootclasspath entries)

    set JAVA_OPTS=%JAVA_OPTS% -Dprogram.name=%PROGNAME% \
    -Xbootclasspath/p:jboss-classloader-transformer.jar;jdk14-pluggable-instrumentor.jar

After modifying JAVA_OPTS and setting the EnableLoadtimeWeaving to true, then you should be ready to go.

### 10.3.3. JBoss 4.x and JDK 5

JBoss AS has special integration with JDK 5.0 to do loadtime transformations. This section explains how to use it.

JBoss AOP comes distributed with the JBoss 4.x Application Server. The version that comes with JBoss 4.x does not take advantage of JDK 5.0 features. It is best to install the jboss-aop-jdk50.deployer/ distribution into your JBoss Application Server install base. See the "Installing" chapter for more details.

If you want to do load-time transformations with JBoss 4 and JDK 5, there are two steps you must take.

The `jboss-aop-jdk50.deployer` file contains some MBeans that deploy and manage the AOP framework.

                      <mbean code="org.jboss.aop.deployment.AspectManagerServiceJDK5"
             name="jboss.aop:service=AspectManager">
             <attribute name="EnableLoadtimeWeaving">true</attribute>
             <!-- only relevant when EnableLoadtimeWeaving is true -->
             <attribute name="SuppressTransformationErrors">true</attribute>
             <attribute name="Prune">true</attribute>
             <attribute name="Include">org.jboss.test</attribute>
             <attribute name="Exclude">org.jboss.</attribute>
             <attribute name="Optimized">true</attribute>
             <attribute name="Verbose">false</attribute>
          </mbean>

          <mbean code="org.jboss.aop.deployment.AspectDeployer"
             name="jboss.aop:service=AspectDeployer">
          </mbean>

By default, JBoss application server will not do load-time bytecode manipulation of AOP files. You can turn load-time on by setting the EnableLoadtimeWeaving attribute to true. If SuppressTransformationErrors is true failed bytecode transformation will only give an error warning. This flag is needed because sometimes a JBoss deployment will not have all the classes a class references.

The next step is to copy the pluggable-instrumentor.jar from the lib-50 directory of your JBoss AOP distribution to the bin/ directory of your JBoss AOP application server installation. Next edit run.sh or run.bat (depending on what OS you're on) and add the following to the JAVA_OPTS environment variable

    set JAVA_OPTS=%JAVA_OPTS% -Dprogram.name=%PROGNAME% -javaagent:pluggable-instrumentor.jar

After modifying JAVA_OPTS and setting the EnableLoadtimeWeaving to true, then you should be ready to go.

Note that the `code` attribute of the AspectManager mbean must be `org.jboss.aop.deployment.AspectManagerServiceJDK5` as that is what works with the -javaagent weaver.

### 10.3.4. JBoss 4.x and JRockit

To use loadtime transformations with JRockit we can instruct Jrockit to use its native classloader hooks. Note that with JRockit 1.4.2 this is your only option to do loadtime transformations.

If you are using JRockit 5.0 and you wish to use the JDK 5 features of JBoss AOP, you should replace jboss-aop.deployer with jboss-aop-jdk50.deployer as mentioned in "JBoss 4.x and JDK 5.0".

If you want to do load-time transformations with JBoss 4 and JRockit, there are two steps you must take.

The `jboss-aop.deployer` or `jboss-aop-jdk50.deployer` file (depending on which you are using) contains some MBeans that deploy and manage the AOP framework.

                      <mbean code="org.jboss.aop.deployment.AspectManagerService"
             name="jboss.aop:service=AspectManager">
             <attribute name="EnableLoadtimeWeaving">true</attribute>
             <!-- only relevant when EnableLoadtimeWeaving is true -->
             <attribute name="SuppressTransformationErrors">true</attribute>
             <attribute name="Prune">true</attribute>
             <attribute name="Include">org.jboss.test</attribute>
             <attribute name="Exclude">org.jboss.</attribute>
             <attribute name="Optimized">true</attribute>
             <attribute name="Verbose">false</attribute>
          </mbean>

          <mbean code="org.jboss.aop.deployment.AspectDeployer"
             name="jboss.aop:service=AspectDeployer">
          </mbean>

By default, JBoss application server will not do load-time bytecode manipulation of AOP files. You can turn load-time on by setting the EnableLoadtimeWeaving attribute to true. If SuppressTransformationErrors is true failed bytecode transformation will only give an error warning. This flag is needed because sometimes a JBoss deployment will not have all the classes a class references.

The next step is to copy the jrockit-pluggable-instrumentor.jar from the lib directory of your JBoss AOP distribution to the bin/ directory of your JBoss AOP application server installation. Next edit run.sh or run.bat (depending on what OS you're on) and add the following to the JAVA_OPTS and JBOSS_CLASSPATH environment variables

    # Setup JBoss sepecific properties
    JAVA_OPTS="$JAVA_OPTS -Dprogram.name=$PROGNAME \
    	-Xmanagement:class=org.jboss.aop.hook.JRockitPluggableClassPreProcessor"
    JBOSS_CLASSPATH="$JBOSS_CLASSPATH:jrockit-pluggable-instrumentor.jar"

After modifying JAVA_OPTS, JBOSS_CLASSPATH and setting the EnableLoadtimeWeaving to true, then you should be ready to go.

Note that the `code` attribute of the AspectManager mbean must be `org.jboss.aop.deployment.AspectManagerService` as that is what works with the JRockit special hooks.

### 10.3.5. JBoss Application Server 3.2.x and JDK 1.4

JBoss AOP can also work with JBoss 3.2.7 (maybe 3.2.6) and higher in the JBoss 3.2 series. Look in the Installing chapter on how to install the JAR files.

After installing, you need to modify the `jboss-3.2.7/server/xxx/conf/jboss-service.xml` file to add these mbean definitions. They are similar to the 4.0 release, but notice the '32' added to the class name.

                   <mbean code="org.jboss.aop.deployment.AspectManagerService32"
             name="jboss.aop:service=AspectManager">
             <attribute name="EnableLoadtimeWeaving">false</attribute>
             <!-- only relevant when EnableLoadtimeWeaving is true -->
             <attribute name="SuppressTransformationErrors">true</attribute>
             <attribute name="Prune">true</attribute>
             <attribute name="Include">org.jboss.test</attribute>
             <attribute name="Exclude">org.jboss.</attribute>
             <attribute name="Optimized">true</attribute>
             <attribute name="Verbose">false</attribute>
          </mbean>

          <mbean code="org.jboss.aop.deployment.AspectDeployer32"
             name="jboss.aop:service=AspectDeployer">
          </mbean>

Also, copy the `base-aop.xml` file into the server/xxx/deploy/ directory if you want to use any of JBoss Aspects.

Follow the same steps to enable loadtime weaving as those for JDK 1.4 and JBoss 4.x.

### 10.3.6. JBoss 3.2.x and JDK 5

You can use the JDK 5 -javaagent stuff if you like with JBoss 3.2.x.

To use JDK 5 loadtime with JBoss 3.2.x make sure you follow the directions in the 'Installing' chapter.

If you want to do load-time transformations with JBoss 3.2.7 and JDK 5, there are two steps you must take.

After installing, you need to modify the `jboss-3.2.7/server/xxx/conf/jboss-service.xml` file to add these mbean definitions. They are similar to the 4.0 release, but notice the '32' added to the class name.

                   <mbean code="org.jboss.aop.deployment.AspectManagerService32JDK5"
             name="jboss.aop:service=AspectManager">
             <attribute name="EnableLoadtimeWeaving">false</attribute>
             <!-- only relevant when EnableLoadtimeWeaving is true -->
             <attribute name="SuppressTransformationErrors">true</attribute>
             <attribute name="Prune">true</attribute>
             <attribute name="Include">org.jboss.test</attribute>
             <attribute name="Exclude">org.jboss.</attribute>
             <attribute name="Optimized">true</attribute>
             <attribute name="Verbose">false</attribute>
          </mbean>

          <mbean code="org.jboss.aop.deployment.AspectDeployer32"
             name="jboss.aop:service=AspectDeployer">
          </mbean>

Also, copy the `base-aop.xml` file into the server/xxx/deploy/ directory if you want to use any of JBoss Aspects.

By default, JBoss application server will not do load-time bytecode manipulation of AOP files. You can turn load-time weaving the same way you do for JBoss 4.

The next step is to copy the pluggable-instrumentor.jar from the lib-50 directory of your JBoss AOP distribution to the bin/ directory of your JBoss AOP application server installation. Next edit run.sh or run.bat (depending on what OS you're on) and add the following to the JAVA_OPTS environment variable

    set JAVA_OPTS=%JAVA_OPTS% -Dprogram.name=%PROGNAME% -javaagent:pluggable-instrumentor.jar

After modifying JAVA_OPTS and setting the EnableLoadtimeWeaving to true, then you should be ready to go.

### 10.3.7. JBoss 3.2.x and JRockit

You can use the JRockit classloader integration if you like with JBoss 3.2.x. If you are using JRockit 1.4.2 this is the only way to achieve loadtime transformations.

If you want to do load-time transformations with JBoss 3.2.7 and JRockit, there are two steps you must take.

After installing, you need to modify the `jboss-3.2.7/server/xxx/conf/jboss-service.xml` file to add these mbean definitions. They are similar to the 4.0 release, but notice the '32' added to the class name. Note that the `code` attribute of the AspectManager mbean must be `org.jboss.aop.deployment.AspectManagerService` as that is what works with the JRockit special hooks.

                   <mbean code="org.jboss.aop.deployment.AspectManagerService32"
             name="jboss.aop:service=AspectManager">
             <attribute name="EnableLoadtimeWeaving">false</attribute>
             <!-- only relevant when EnableLoadtimeWeaving is true -->
             <attribute name="SuppressTransformationErrors">true</attribute>
             <attribute name="Prune">true</attribute>
             <attribute name="Include">org.jboss.test</attribute>
             <attribute name="Exclude">org.jboss.</attribute>
             <attribute name="Optimized">true</attribute>
             <attribute name="Verbose">false</attribute>
          </mbean>

          <mbean code="org.jboss.aop.deployment.AspectDeployer32"
             name="jboss.aop:service=AspectDeployer">
          </mbean>

Also, copy the `base-aop.xml` file into the server/xxx/deploy/ directory if you want to use any of JBoss Aspects.

By default, JBoss application server will not do load-time bytecode manipulation of AOP files. You can turn load-time on weaving the same way you do for JBoss 4.

The next step is to copy the jrockit-pluggable-instrumentor.jar from the lib directory of your JBoss AOP distribution to the bin/ directory of your JBoss AOP application server installation and to modify your run.sh/bat file as mentioned in "JBoss 4.x and JRockit".

### 10.3.8. Improving Loadtime Performance in a JBoss AS Environment

The same rules apply to JBoss AS for tuning loadtime weaving performance as standalone Java. See the previous chapter on tips and hints. YOU CANNOT USE THE SAME SYSTEM PROPERTIES THOUGH! Switches like pruning, optimized, and include/exclude are configured through the jboss-aop.deployer/META-INF/jboss-service.xml file talked about earlier in this chapter. You should be able to figure out how to turn the switches on/off from the above documentation.

## 10.4. Scoping aop to the classloader

By default all deployments in JBoss are global to the whole application server. That means that any ear, sar, jar etc. that is put in the deploy directory can see the classes from any other deployed archive. Similarly, aop bindings are global to the whole virtual machine. This "global" visibility can be turned off per top-level deployment.

How the following works may be changed in future versions of jboss-aop. If you deploy a .aop file as part of a scoped archive, the bindings etc. applied within the .aop/META-INF/jboss-aop.xml file will only apply to the classes within the scoped archive and not to anything else in the application server. Another alternative is to deploy -aop.xml files as part of a service archive (SAR). Again if the SAR is scoped, the bindings contained in the -aop.xml files will only apply to the contents of the SAR file. It is not currently possible to deploy a standalone -aop.xml file and have that attach to a scoped deployment. Standalone -aop.xml files will apply to classes in the whole application server.

Prev | Up | Next
Chapter 9. Building and Compiling Aspectized Java | Home | Chapter 11. Reflection and AOP