JBoss AOP - Aspect-Oriented Framework for Java

The section defines some basic terms that will be used throughout this guide.

JBoss AOP is a 100% pure Java framework. All your AOP constructs are defined as pure Java classes and bound to your application code via XML or by annotations. This sections walks through implementing aspects.

Invocation objects are the runtime encapsulation of their joinpoint. They contain runtime information of their joinpoint (args, java.lang.reflect.*, etc..), and they also drive the flow of aspects.

The Aspect Class is a plain Java class that can define zero or more advices, pointcuts, and/or mixins.

public class Aspect
 {
   public Object trace(Invocation invocation) throws Throwable {
      try {
         System.out.println("Entering anything");
         return invocation.invokeNext(); // proceed to next advice or actual call
      } finally {
         System.out.println("Leaving anything");
      }
   }
}

The example above is of an advice trace that traces calls to any type of joinpoint. Notice that invocation.invokeNext() is used to drive the advice chain. It either calls the next advice in the chain, or does the actual method or constructor invocation.

For basic interception, any method that follows the form:

Object methodName(Invocation object) throws Throwable

can be an advice. The Invocation.invokeNext() method must be called by the advice code or no other advice will be called, and the actual method, field, or constructor invocation will not happen.

Method names can be overloaded for different invocation types. For instance, let's say you wanted to have a different trace advice for each invocation type. You can specify the same method name "trace" and just overload it with the concreate invocation type.

public class Aspect
 {
   public Object trace(MethodInvocation invocation) throws Throwable {
      try {
         System.out.println("Entering method: " + invocation.getMethod()");
         return invocation.invokeNext(); // proceed to next advice or actual call
      } finally {
         System.out.println("Leaving method: " + invocation.getMethod()");
      }
   }
   public Object trace(ConstructorInvocation invocation) throws Throwable {
      try {
         System.out.println("Entering constructor: " + invocation.getConstructor()");
         return invocation.invokeNext(); // proceed to next advice or actual call
      } finally {
         System.out.println("Leaving constructor: " + invocation.getConstructor()");
      }
   }
}

JBoss AOP provides an abstraction for resolving JDK 5.0 annotations (and JDK 1.4 annotations if you use our Annotation Compiler). In future versions of JBoss AOP, there will be a way to override annotation values on a per thread basis, or via XML overrides, or even provide VM and cluster wide defaults for annotation values. Also if you want to write a truly generic advice that takes the base Invocation type, you can still get the annotation value of the method, constructor, or field you're invoking on by calling this method:

Object resolveAnnotation(Class annotation);

That's just resolving for resolving member annotations. If your aspect needs to resolve class level annotations then this method should be called:

Object resolveClassAnnotation(Class annotation)

Mixins are a type of introduction in which you can do something like C++ multiple inheritance and force an existing Java class to implement a particular interface and the implementation of that particular interface is encapsulated into a particular class called a mixin.

Mixin classes have no restrictions other than they must implement the interfaces that you are introducing.

Dynamic CFlows allow you to define code that will be executed that must be resolved true to trigger positive on a cflow test on an advice binding. (See <cflow-stack> for more information). The test happens dynamically at runtime and when combined with a pointcut expression allows you to do runtime checks on whether a advice binding should run or not. To implement a dynamic CFlow you just have to implement the simple org.jboss.aop.pointcut.DynamicCFlow interface. You can then use it within cflow expressions. (See XML or Annotations)

public interface DynamicCFlow
{
   boolean shouldExecute(Invocation invocation);
}

There are two types of wildcards you can use within pointcut expressions

Type patterns are defined by an annotation or by fully qualified class name. Annotation expressions are not allowed to have wildcards within them, but class expressions are.

To reference all subtypes of a certain class (or implementors of an interface), the $instanceof{} expression can be used. Wildcards and annotations may also be used within $instanceof{} expressions.

         $instanceof{org.acme.SomeInterface}
         $instanceof{@org.acme.SomeAnnotation}
         $instanceof{org.acme.interfaces.*}
      

are all allowed.

For very complex type expressions, the Typedef construct can be used. To reference a Typedef within a class expression $typedef{id} is used.

public void org.acme.SomeClass->methodName(java.lang.String)

The attributes( public, static, private) of the method are optional. If the attribute is left out then any attribute is assumed. Attributes accept the ! modifier for negation.

public !static void org.acme.SomeClass->*(..)

$instanceof{} in the class name.

void $instanceof{org.acme.SomeInterface}->methodName(java.lang.String)

Annotations can be used in place of the class name. The below example matches any methodName() of a tagged @javax.ejb.Entity class.

void @javax.ejb.Entity->methodName(java.lang.String)

Annotations can be also be used in place of the method name. The below examples matches any method tagged as @javax.ejb.Tx.

* *->@javax.ejb.Tx(..)

In addition you can use typedefs, $instanceof{}, annotations and wildcards for method parameters and return types. The following matches all methods called loadEntity that return a class annotated with @javax.ejb.Entity, that takes a class annotated as @org.acme.Ann and any class that matches java.*.String (such as java.lang.String).

@javax.ejb.Entity *->loadEntity(@org.acme.Ann, java.*.String)

public void org.acme.SomeClass->methodName(java.lang.String) \
      throws org.acme.SomeException, java.lang.Exception

public org.acme.SomeClass->new(java.lang.String)

Constructor expressions are made up of the fully qualified classname and the new keyword The attributes( public, static, private) of the method are optional. If the attribute is left out then any attribute is assumed. Attributes accept the ! modifier for negation.

!public org.acme.SomeClass->new(..)

$instanceof{} can be used in the class name.

$instanceof{org.acme.SomeInterface}->new(..)

Annotations can be used in place of the class name. The below example matches any constructor of a tagged @javax.ejb.Entity class.

@javax.ejb.Entity->new(..)

Annotations can be also be used in place of the new keyword. The below examples matches any constructor tagged as @javax.ejb.MethodPermission.

*->@javax.ejb.MethodPermission(..)

In addition, just as for methods you can use typedefs, $instanceof{}, annotations and wildcards for constructor parameters. The following matches all constructors that take a class annotated as @org.acme.Ann and any class that matches java.*.String (such as java.lang.String).

*->new(@org.acme.Ann, java.*.String)

You can also include an optional throws clause in the pointcut expression:

public void org.acme.SomeClass->new(java.lang.String) \
      throws org.acme.SomeException, java.lang.Exception

If any exceptions are present in the pointcut expression they must be present in the throws clause of the constructors to be matched.

public java.lang.String org.acme.SomeClass->fieldname

Constructor expressions are made up of the type, the fully qualified classname where the field resides and the field's name. The attributes( public, static, private) of the field are optional. If the attribute is left out then any attribute is assumed. Attributes accept the ! modifier for negation.

!public java.lang.String org.acme.SomeClass->*

$instanceof{} can be used in the class name. The below expression matches any field of any type or subtype of org.acme.SomeInterface

* $instanceof{org.acme.SomeInterface}->*

Annotations can be used in place of the class name. The below example matches any field where the type class is tagged with @javax.ejb.Entity.

* @javax.ejb.Entity->*

Annotations can be also be used in place of the field name. The below examples matches any field tagged as @org.jboss.Injected.

* *->@org.jboss.Injected

In addition, you can use typedefs, $instanceof{}, annotations and wildcards for field types. The following matches all fields where the type class has been tagged with @javax.ejb.Entity.

@javax.ejb.Entity *->*

Pointcuts use class, field, constructor, and method expressions to specify the actual joinpoint that should be intercepted/watched.

Pointcuts can be composed into boolean expressions.

Here's some examples.

call(void Foo->someMethod()) AND withincode(void Bar->caller())
execution(* *->@SomeAnnotation(..)) OR field(* *->@SomeAnnotation)

Pointcuts can be named in XML or annotation bindings (See in later chapters). They can be referenced directly within a pointcut expression.

some.named.pointcut OR call(void Foo->someMethod())

Sometimes, when writing pointcuts, you want to specify a really complex type they may or may not have boolean logic associated with it. You can group these complex type definitions into a JBoss AOP Typedef either in XML or as an annotation (See later in this document). Typedef expressions can also be used within introduction expressions. Typedef expressions can be made up of has, hasfield, and class expressions. class takes a fully qualified class name, or an $instanceof{} expression.

class(org.pkg.*) OR has(* *->@Tx(..)) AND !class($instanceof{org.foo.Bar})

In the last sections you saw how to code aspects and how pointcut expressions are formed. This chapter puts it all together. There are two forms of bindings for advices, mixins, and introductions. One is XML which will be the focus of this chapter. The Annotated Bindings chapter discusses how you can replace XML with JDK 5.0 annotations.

JBoss AOP resolves pointcut and advice bindings at runtime. So, bindings are a deployment time thing. How does JBoss AOP find the XML files it needs at runtime? There are a couple of ways.

<?xml version='1.0' encoding='UTF-8' ?>

<!ELEMENT aop (interceptor|introduction|metadata-loader|metadata|
               stack|aspect|pointcut|pluggable-pointcut|bind|
               prepare|cflow-stack|dynamic-cflow|annotation-introduction|typedef)+>

<!ELEMENT interceptor ANY>
<!ATTLIST interceptor name CDATA #IMPLIED>
<!ATTLIST interceptor class CDATA #IMPLIED>
<!ATTLIST interceptor factory CDATA #IMPLIED>
<!ATTLIST interceptor scope (PER_VM|PER_CLASS|PER_INSTANCE|PER_JOINPOINT) "PER_VM">

<!ELEMENT aspect ANY>
<!ATTLIST aspect name CDATA #IMPLIED>
<!ATTLIST aspect class CDATA #IMPLIED>
<!ATTLIST aspect factory CDATA #IMPLIED>
<!ATTLIST aspect scope (PER_VM|PER_CLASS|PER_INSTANCE|PER_JOINPOINT) "PER_VM">

<!ELEMENT introduction (mixin*,interfaces)>
<!ATTLIST introduction class CDATA #IMPLIED>
<!ATTLIST introduction expr CDATA #IMPLIED>
<!ELEMENT mixin (interfaces, class, construction?)>
<!ATTLIST mixin transient (true|false) "true">
<!ELEMENT interfaces (#PCDATA)>
<!ELEMENT class (#PCDATA)>
<!ELEMENT construction (#PCDATA)>

<!ELEMENT metadata-loader EMPTY>
<!ATTLIST metadata-loader tag CDATA #REQUIRED>
<!ATTLIST metadata-loader class CDATA #REQUIRED>

<!ELEMENT metadata ANY>
<!ATTLIST metadata tag CDATA #REQUIRED>
<!ATTLIST metadata class CDATA #REQUIRED>

<!ELEMENT stack (interceptor|interceptor-ref|stack-ref|advice)+>
<!ATTLIST stack name CDATA #REQUIRED>

<!ELEMENT interceptor-ref EMPTY>
<!ATTLIST interceptor-ref name CDATA #REQUIRED>

<!ELEMENT stack-ref EMPTY>
<!ATTLIST stack-ref name CDATA #REQUIRED>

<!ELEMENT advice EMPTY>
<!ATTLIST advice name CDATA #REQUIRED>
<!ATTLIST advice aspect CDATA #REQUIRED>

<!ELEMENT pointcut EMPTY>
<!ATTLIST pointcut name CDATA #REQUIRED>
<!ATTLIST pointcut expr CDATA #REQUIRED>

<!ELEMENT prepare EMPTY>
<!ATTLIST prepare expr CDATA #REQUIRED>

<!ELEMENT pluggable-pointcut ANY>
<!ATTLIST pluggable-pointcut name CDATA #REQUIRED>
<!ATTLIST pluggable-pointcut class CDATA #REQUIRED>

<!ELEMENT bind (interceptor|interceptor-ref|stack-ref|advice)+>
<!ATTLIST bind name CDATA #IMPLIED>
<!ATTLIST bind pointcut CDATA #REQUIRED>
<!ATTLIST bind cflow CDATA #IMPLIED>

<!ELEMENT cflow-stack (called|not-called)+>
<!ATTLIST cflow-stack name CDATA #REQUIRED>

<!ELEMENT called EMPTY>
<!ATTLIST called expr CDATA #REQUIRED>
<!ELEMENT not-called EMPTY>
<!ATTLIST not-called expr CDATA #REQUIRED>


<!ELEMENT dynamic-cflow EMPTY>
<!ATTLIST dynamic-cflow name CDATA #REQUIRED>
<!ATTLIST dynamic-cflow class CDATA #REQUIRED>

<!ELEMENT annotation-introduction (#PCDATA)>
<!ATTLIST annotation-introduction expr CDATA #REQUIRED>
<!ATTLIST annotation-introduction invisible (true|false) #REQUIRED>

<!ELEMENT typedef EMPTY>
<!ATTLIST typedef name CDATA #REQUIRED>
<!ATTLIST typedef expr CDATA #REQUIRED>
            
         

The <aspect> tag specifies to the AOP container to declare an aspect class. It is also used for configuring aspects as they are created and defining the scope of the aspects instance.

<aspect class="org.jboss.MyAspect"/>

<aspect class="org.jboss.MyAspect" scope="PER_VM"/>

<aspect class="org.jboss.SomeAspect">
     <attribute name="SomeIntValue">55</attribute>
     <advisor-attribute name="MyAdvisor"/>
     <instance-advisor-attribute name="MyInstanceAdvisor"/>
     <joinpoint-attribute name="MyJoinpoint"/>
</aspect>

<aspect class="org.jboss.SomeAspect">
        <attribute name="SomeIntValue">55</attribute>
        <advisor-attribute name="MyAdvisor"/>
        <instance-advisor-attribute name="MyInstanceAdvisor"/>
        <joinpoint-attribute name="MyJoinpoint"/>
</aspect>

public class SomeAspect {
   public SomeAspect() {}

   public void setSomeIntValue(int val) {...}
   public void setMyAdvisor(org.jboss.aop.Advisor advisor) {...}
   public void setMyInstanceAdvisor(org.jboss.aop.InstanceAdvisor advisor) {...}
   public void setMyJoinpoint(org.jboss.aop.joinpoint.Joinpoint joinpoin) {...}
}

<aspect name="MyAspect" factory="org.jboss.AspectConfigFactory" scope="PER_CLASS">
     <some-arbitrary-xml>value</some-arbitrary-xml>
</aspect>

<interceptor class="org.jboss.MyInterceptor" scope="PER_VM"/>
<interceptor class="org.jboss.SomeInterceptor">
     <attribute name="SomeIntValue">55</attribute>
     <advisor-attribute name="MyAdvisor"/>
     <instance-advisor-attribute name="MyInstanceAdvisor"/>
     <joinpoint-attribute name="MyJoinpoint"/>
</interceptor>
<interceptor name="MyAspect" factory="org.jboss.InterceptorConfigFactory" scope="PER_CLASS">
  <some-arbitrary-xml>value</some-arbitrary-xml>
</interceptor>

Interceptors are defined in XML the same exact way as aspects are. No difference except the tag. If there is no name attribute defined, the name of the interceptor is the same as the class or factory attribute value.

<bind pointcut="execution(void Foo->bar())">
     <interceptor-ref name="org.jboss.MyInterceptor/>
     <advice name="trace" aspect="org.jboss.MyAspect"/>
</bind>

In the above example, the MyInterceptor interceptor and the trace method of the MyAspect class will be executed when the Foo.bar method is invoked.

Stacks allow you to define a predefined set of advices/interceptors that you want to reference from within a bind element.

<stack name="stuff">
      <interceptor class="SimpleInterceptor1" scope="PER_VM"/>
      <advice name="trace" aspect="org.jboss.TracingAspect"/>
      <interceptor class="SimpleInterceptor3">
           <attribute name="size">55</attribute>
      </interceptor>
</stack>

After defining the stack you can then reference it from within a bind element.

<bind pointcut="execution(* POJO->*(..))">
       <stack-ref name="stuff"/>
</bind>

The pointcut tag allows you to define a pointcut expression, name it and reference it within any binding you want. It is also useful to publish pointcuts into your applications to that others have a clear set of named integration points.

<pointcut name="publicMethods" expr="execution(public * *->*(..))"/>
<pointcut name="staticMethods" expr="execution(static * *->*(..))"/>

The above define two different pointcuts. One that matches all public methods, the other that matches the execution of all static methods. These two pointcuts can then be referenced within a bind element.

<bind pointcut="publicMethods AND staticMethods">
      <interceptor-ref name="tracing"/>
</bind>
         

Annotation introductions allow you to embed an annotation within a the class file of the class. You can introduce an annotation to a class, method, field, or constructor.

<annotation-introduction expr="constructor(POJO->new())">
      @org.jboss.complex (ch='a', string="hello world", flt=5.5, dbl=6.6, shrt=5, lng=6, integer=7, bool=true, annotation=@single("hello"), array={"hello", "world"}, clazz=java.lang.String)
</annotation-introduction>

The expr attribute takes method(), constructor(), class(), or field(). Within those you must define a valid expression for that construct. The following rules must be followed for the annotation declaration:

Control flow is a runtime construct. It allows you to specify pointcut parameters revolving around the call stack of a Java program. You can do stuff like, if method A calls method B calls Method C calls Method D from Constructor A, trigger this advice. In defining a control flow, you must first paint a picture of what the Java call stack should look like. This is the responsibility of the cflow-stack.

<cflow-stack name="recursive2">
      <called expr="void POJO->recursive(int)"/>
      <called expr="void POJO->recursive(int)"/>
      <not-called expr="void POJO->recursive(int)"/>
</cflow-stack>

A cflow-stack has a name and a bunch of called and not-called elements that define individual constructor or method calls with a Java call stack. The expr attribute must be a method or constructor expression. called states that the expr must be in the call stack. not-called states that there should not be any more of the expression within the stack. In the above example, the cflow-stack will be triggered if there are two and only two calls to the recursive method within the stack. Once the cflow-stack has been defined, it can then be referenced within a bind element through the cflow attribute. Boolean expressions are allowed here as well.

<bind pointcut="execution(void POJO->recursive(int))" cflow="recursive2 AND !cflow2">
      <interceptor class="SimpleInterceptor"/>
</bind>

<typedef name="jmx" expr="class(@org.jboss.jmx.@MBean) OR
                          has(* *->org.jboss.jmx.@ManagedOperation) OR
                          has(* *->org.jboss.jmx.@ManagedAttribute)"/>

typedefs allow you to define complex type expressions and then use then pointcut expressions. In the above example, we're defining a class that is tagged as @Mbean, or has a method tagged as @ManagedOperaion or @ManagedAttribute. The above typedef could then be used in a pointcut, introduction, or bind element

<pointcut name="stuff" expr="execution(* $typedef{jmx}->*(..))"/>
<introduction expr="class($typedef{jmx})">

dynamic-cflow allows you to define code that will be executed that must be resolved true to trigger positive on a cflow test on an advice binding. (See Dynamic CFlow for more information). The test happens dynamically at runtime and when combined with a pointcut expression allows you to do runtime checks on whether a advice binding should run or not. Create a dynamic cflow class, then you must declare it with XML so that it can be used in bind expressions.

<dynamic-cflow name="simple" class="org.jboss.SimpleDynamicCFlow"/>

You can then use it within a bind

<bind expr="execution(void Foo->bar())" cflow="simple">

The prepare tag allows you to define a pointcut expression. Any joinpoint that matches the expression will be aspectized and bytecode instrumented. This allows you to hotdeploy and bind aspects at runtime as well as to work with the per instance API that every aspectized class has. To prepare something, just define a pointcut expression that matches the joinpoint you want to instrument.

<prepare expr="execution(void Foo-bar())"/>

You can attach untyped metadata that is stored in org.jboss.aop.metadata.SimpleMetaData structures within the org.jboss.aop.Advisor class that manages each aspectized class. The XML mapping has a section for each type of metadata. Class, method, constructor, field, and defaults for the whole shabang. Here's an example:

<metadata tag="testdata" class="org.jboss.test.POJO">
      <default>
         <some-data>default value</some-data>
      </default>
      <class>
         <data>class level</data>
      </class>
      <constructor expr="POJOConstructorTest()">
         <some-data>empty</some-data>
      </constructor>
      <method expr="void another(int, int)">
         <other-data>half</other-data>
      </method>
      <field name="somefield">
         <other-data>full</other-data>
      </field>
</metadata>

Any element can be defined under the class, default, method, field, and constructor tags. The name of these elements are used as attribute names in SimpleMetaData structures. The tag attribute is the name used to reference the metadata within the Advisor, or Invocation lookup mechanisms.

<metadata-loader tag="security" class="org.jboss.aspects.security.SecurityClassMetaDataLoader"/>

If you need more complex XML mappings for untyped metadata, you can write your own metadata binding. The tag attribute is used to trigger the loader. The loader class must implement the org.jboss.aop.metadata.ClassMetaDataLoader interface.

public interface ClassMetaDataLoader
{
   public ClassMetaDataBinding importMetaData(Element element, String name,
                                              String tag, String classExpr) throws Exception;

   public void bind(ClassAdvisor advisor, ClassMetaDataBinding data,
                    CtMethod[] methods, CtField[] fields, CtConstructor[] constructors) throws Exception;

   public void bind(ClassAdvisor advisor, ClassMetaDataBinding data,
                    Method[] methods, Field[] fields, Constructor[] constructors) throws Exception;
}

Any arbitrary XML can be in the metadata element. The ClassMetaDataBinding.importMetaData method is responsible for parsing the element and building ClassMetaDataBinding structurs which are used in the precompiler and runtime bind steps. Look at the SecurityClassMetaDataLoader code shown above for a real concrete example.

Precedence allows you to impose an overall relative sorting order of your interceptors and advices.

         <precedence>
            <interceptor-ref name="org.acme.Interceptor"/>
            <advice aspect="org.acme.Aspect" name="advice1"/>
            <advice aspect="org.acme.Aspect" name="advice2"/>
         </precedence>         
      

This says that when a joinpoint has both org.acme.Interceptor and org.acme.Aspect.advice() bound to it, org.acme.Interceptor must always be invoked before org.acme.Aspect.advice1() which must in turn be invoked before org.acme.Aspect.advice2(). The ordering of interceptors/advices that do not appear in a precedence is defined by their ordering for the individual bindings or intercerceptor stacks.

You can declare checks to be enforced at instrumentation time. They take a pointcut and a message. If the pointcut is matched, the message is printed out.

   <declare-warning expr="class($instanceof{VehicleDAO}) \
            AND !has(public void *->save())">
         All VehicleDAO subclasses must override the save() method.
   </declare-warning> 

      <declare-error expr="call(* org.acme.businesslayer.*->*(..)) \
            AND within(org.acme.datalayer.*)">
      Data layer classes should not call up to the business layer
   </declare-error> 

To mark a class as an aspect you annotate it with the @Aspect annotation. Remember that a class to be used as an aspect does not need to inherit or implement anything special, but it must have an empty constuctor and contain one or more methods (advices) of the format:

public Object <any-method-name>(org.jboss.aop.joinpoint.Invocation)

The declaration of org.jboss.aop.Aspect is:

   package org.jboss.aop;
   
   import org.jboss.aop.advice.Scope;
   import java.lang.annotation.ElementType;
   import java.lang.annotation.Retention;
   import java.lang.annotation.RetentionPolicy;
   import java.lang.annotation.Target;
      
   
   @Target({ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME)
           public @interface Aspect
   {
      Scope scope() default Scope.PER_VM;
   }

         

and Scope is:

   package org.jboss.aop.advice;
   
   public enum Scope
   {
      PER_VM, PER_CLASS, PER_INSTANCE, PER_JOINPOINT
   }
         

See the "XML Bindings" chapter for a description of the various scopes.

In JDK 1.5 we use the @Aspect annotation as follows:

   package com.mypackage;
   
   import org.jboss.aop.Aspect;
   import org.jboss.aop.advice.Scope;
   import org.jboss.aop.joinpoint.Invocation;
   
   @Aspect (scope = Scope.PER_VM)
   public class MyAspect
   {
      public Object myAdvice(Invocation invocation)
   }

         

And in JDK 1.4.2:

   package com.mypackage;
   
   /**
    * @@Aspect (scope = Scope.PER_VM)
    */
   public class MyAspect
   {
      public Object myAdvice(Invocation invocation)
      {
         return invocation.invokeNext();
      }
   }
         

The name of the class (in this case com.mypackage.MyAspect) gets used as the internal name of the aspect. The equivalent using XML configuration would be:

            <aop>
            <aspect class="com.mypackage.MyAspect" scope="PER_VM"/>
            </aop>
         

To mark a class as an interceptor or an aspect factory you annotate it with the @InterceptorDef annotation. The class must either implement the org.jboss.aop.advice.Interceptor interface or the org.jboss.aop.advice.AspectFactory interface.

The declaration of org.jboss.aop.InterceptorDef is:

   package org.jboss.aop;
   
   @Target({ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME)
           public @interface Aspect
   {
      Scope scope() default Scope.PER_VM;
   }

         

The same Scope enum is used as for Aspect. The following examples use the @Bind annotation, which will be described in more detail below.

   package com.mypackage;
   
   import org.jboss.aop.Bind;
   import org.jboss.aop.InterceptorDef;
   import org.jboss.aop.advice.Interceptor;
   
   @InterceptorDef (scope = Scope.PER_VM)
   @Bind (pointcut="execution("* com.blah.Test->test(..)")
   public class MyInterceptor implements Interceptor
   {
      public Object invoke(Invocation invocation)throws Throwable
      {
         return invocation.invokeNext();
      }
   }

            

   package com.mypackage;
   
   /**
    * @@org.jboss.aop.InterceptorDef (scope = org.jboss.aop.advice.Scope.PER_VM)
    * @@org.jboss.aop.Bind (pointcut="execution("* com.blah.Test->test(..)")
    */
   public class MyInterceptor implements Interceptor
   {
      public Object invoke(Invocation invocation)throws Throwable
      {
         return invocation.invokeNext();
      }
   }
            

               <aop>
               <interceptor class="com.mypackage.MyInterceptor" scope="PER_VM"/>
               </aop>
            

   package com.mypackage;

   import org.jboss.aop.advice.AspectFactory;
   
   @InterceptorDef (scope=org.jboss.aop.advice.Scope.PER_VM)
   @Bind (pointcut="execution("* com.blah.Test->test2(..)")
   public class MyInterceptorFactory implements AspectFactory
   {
      //Implemented methods left out for brevity
   }
            

   package com.mypackage;
   
   /**
    * @@org.jboss.aop.InterceptorDef (scope=org.jboss.aop.advice.Scope.PER_VM)
    * @@org.jboss.aop.Bind (pointcut="execution("* com.blah.Test->test2(..)")
    */
   public class MyInterceptorFactory implements AspectFactory
   {
      //Implemented methods left out for brevity
   }
            

               <aop>
               <interceptor factory="com.mypackage.MyInterceptorFactory" scope="PER_VM"/>
               </aop>
            

To define a named pointcut you annotate a field within an @Aspect or @InterceptorDef annotated class with @PointcutDef. @PointcutDef only applies to fields and is not recognised outside @Aspect or @InterceptorDef annotated classes.

The declaration of org.jboss.aop.PointcutDef is:

package org.jboss.aop;

@Target({ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME)
        public @interface PointcutDef
{
   String value();
}
         

@PointcutDef takes only one value, a valid pointcut expression. The name of the pointcut used internally and when yo want to reference it is:

<name of @Aspect/@InterceptorDef annotated class>.<name of @PointcutDef annotated field>

An example of an aspect class containing a named pointcut which it references from a bindng's pointcut expression in JDK 1.5:

   package com.mypackage;

   import org.jboss.aop.PointcutDef;
   import org.jboss.aop.pointcut.Pointcut;
            
   @Aspect (scope = Scope.PER_VM)
   public class MyAspect
   {
      @PointcutDef ("(execution("* org.blah.Foo->someMethod()) OR \
      execution("* org.blah.Foo->otherMethod()))")
      public static Pointcut fooMethods;
      
      public Object myAdvice(Invocation invocation)
      {
         return invocation.invokeNext();
      }
   }
         

It is worth noting that named pointcuts can be referenced in pointcut expressions outside the class they are declared in (if the annotated fields are declared public of course!).

The same example in JDK 1.4.2:

   package com.mypackage;

   import org.jboss.aop.pointcut.Pointcut;
            
   /**
    * @@org.jboss.aop.Aspect (scope = Scope.PER_VM)
    */
   public class MyAspect
   {
      /**
       * @@org.jboss.aop.PointcutDef ("(execution("* org.blah.Foo->someMethod()) \ 
               OR execution("* org.blah.Foo->otherMethod()))")
       */
      public static Pointcut fooMethods;
      
      public Object myAdvice(Invocation invocation)
      {
         return invocation.invokeNext();
      }
   }
         

Using XML configuration this would be:

            <aop>
            <aspect class="com.mypackage.MyAspect" scope="PER_VM"/>
            <pointcut
            name="com.mypackage.MyAspect.fooMethods" 
            expr="(execution("* org.blah.Foo->someMethod()) OR \
                  execution("* org.blah.Foo->otherMethod()))"
      />
            </aop>
         

To create a binding to an advice method from an aspect class, you annotate the advice method with @Bind. To create a binding to an Interceptor or AspectFactory, you annotate the class itself with @Bind since Interceptors only contain one advice (the invoke() method). The @Bind annotation will only be recognised in the situations just mentioned.

The declaration of org.jboss.aop.Bind is:

   package org.jboss.aop;
   
   @Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME)
           public @interface Bind
   {
      String pointcut();
      String cflow() default "";
   }
         

The @Bind annotation takes two parameters:

In the case of a binding to an advice in an aspect class, the internal name of the binding becomes:

<name of the aspect class>.<the name of the advice method>

In the case of a binding to an Interceptor or AspectFactory implementation, the internal name of the binding becomes:

<name of the Interceptor/AspectFactory implementation class>

An example of a binding using an advice method in an aspect class in JDK 1.5:

   package com.mypackage;

   import org.jboss.aop.Bind;
            
   @Aspect (scope = Scope.PER_VM)
   public class MyAspect
   {
      @PointcutDef ("(execution("* org.blah.Foo->someMethod()) \ 
            OR execution("* org.blah.Foo->otherMethod()))")
      public static Pointcut fooMethods;
      
      @Bind (pointcut="com.mypackage.MyAspect.fooMethods")
      public Object myAdvice(Invocation invocation)
      {
         return invocation.invokeNext();
      }

      @Bind (pointcut="execution("* org.blah.Bar->someMethod())")
      public Object myAdvice(Invocation invocation)
      {
         return invocation.invokeNext();
      }

   }
         

And in JDK 1.4.2:

   package com.mypackage;
   
   /**
    * @@org.jboss.aop.Aspect (scope = Scope.PER_VM)
    */
   public class MyAspect
   {
      /**
       * @@org.jboss.aop.PointcutDef ("(execution("* org.blah.Foo->someMethod()) \ 
             OR execution("* org.blah.Foo->otherMethod()))")
       */
      public static Pointcut fooMethods;
      
      /**
       * @@org.jboss.aop.Bind (pointcut="com.mypackage.MyAspect.fooMethods")
       */
      public Object myAdvice(Invocation invocation)
      {
         return invocation.invokeNext();
      }
      
      /**
       * @@org.jboss.aop.Bind (pointcut="execution("* org.blah.Bar->someMethod())")
       */
      public Object otherAdvice(Invocation invocation)
      {
         return invocation.invokeNext();
      }
   }
         

         <aop>
         <aspect class="com.mypackage.MyAspect" scope="PER_VM"/>
         <pointcut
         name="com.mypackage.MyAspect.fooMethods" 
         expr="(execution("* org.blah.Foo->someMethod()) OR \ 
               execution("* org.blah.Foo->otherMethod()))"
      />
         <bind pointcut="com.mypackage.MyAspect.fooMethods">
         <advice name="myAdvice" aspect="com.mypackage.MyAspect">
         </bind>
         <bind pointcut="execution("* org.blah.Bar->someMethod())">
         <advice name="otherAdvice" aspect="com.mypackage.MyAspect">
         </bind>
         </aop>
      

Revisiting the examples above in the @InterceptorDef section, now that we know what @Bind means, the equivalent using XML configuration would be:

            <aop>
            <interceptor class="com.mypackage.MyInterceptor" scope="PER_VM"/>
            <interceptor factory="com.mypackage.MyInterceptorFactory" scope="PER_VM"/>

            <bind pointcut="execution("* com.blah.Test->test2(..)">
            <interceptor-ref name="com.mypackage.MyInterceptor"/>
            </bind>
            <bind pointcut="execution("* com.blah.Test->test2(..)">
            <interceptor-ref name="com.mypackage.MyInterceptorFactory"/>
            </bind>
            </aop>
         

Interface introductions can be done using the @Introduction annotation. Only fields within a class annotated with @Aspect or @InterceptorDef can be annotated with @Introduction.

The declaration of org.jboss.aop.Introduction:

   package org.jboss.aop;
   
   @Target({ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME)
   public @interface Introduction
   {
      Class target() default java.lang.Class.class;
      String typeExpression() default "";
      Class[] interfaces();
   }
         

The parameters of @Introduction are:

target or typeExpression has to be specified, but not both.

This is how to use @Introduction in JDK 1.5:

   package com.mypackage;

   import org.jboss.aop.Introduction;
            
   @Aspect (scope = Scope.PER_VM)
   public class IntroAspect
   {
      @Introduction (target=com.blah.SomeClass.class, \
            interfaces={java.io.Serializable.class})
      public static Object pojoNoInterfacesIntro;
   }
         

And in JDK 1.4.2:

   package com.mypackage;

   /*
    * @@org.jboss.aop.Aspect (scope = Scope.PER_VM)
    */
   public class IntroAspect
   {
      /*
       * @org.jboss.aop.Introduction (target=com.blah.SomeClass, \ 
             interfaces={java.io.Serializable})
       */
      public static Object pojoNoInterfacesIntro;
   }
         

Notice the slight difference in the JDK 1.4.2 annotation, the class values don't have the ".class" suffix.

This means make com.blah.SomeClass.class implement the java.io.Serializable interface. The equivalent configured via XML would be:

            <introduction class="com.blah.SomeClass.class">
            <interfaces>
         java.io.Serializable
            </interfaces>
            </introduction>
         

Sometimes when we want to introduce/force a new class to implement an interface, that interface introduces new methods to a class. The class needs to implement these methods to be valid. In these cases a mixin class is used. The mixin class must implement the methods specified by the interface(s) and the main class can then implement these methods and delegate to the mixin class.

Mixins are created using the @Mixin annotation. Only methods within a class annotated with @Aspect or @InterceptorDef can be annotated with @Mixin. The annotated method has

The declaration of org.jboss.aop.Mixin:

   package org.jboss.aop;

   @Target({ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME)
   public @interface Mixin
   {
      Class target() default java.lang.Class.class;
      String typeExpression() default "";
      Class[] interfaces();
      boolean isTransient() default true;
   }            
         

The parameters of @Mixin are:

target or typeExpression has to be specified, but not both.

An example aspect using @Mixin in JDK 1.5:

   package com.mypackage;
   
   import org.jboss.aop.Mixin;
   import com.mypackage.POJO;
   
   @Aspect (scope=org.jboss.aop.advice.Scope.PER_VM)
   public class IntroductionAspect
   {
      @Mixin (target=com.mypackage.POJO.class, interfaces={java.io.Externalizable.class})
      public static ExternalizableMixin createExternalizableMixin(POJO pojo) {
          return new ExternalizableMixin(pojo);
      }
   }
         

Here's the JDK 1.4.2 version:

   package com.mypackage;
   
   import org.jboss.aop.Mixin;
   import com.mypackage.POJO;

   /**
    * @@org.jboss.aop.Aspect (scope=org.jboss.aop.advice.Scope.PER_VM)
    */   
   public class IntroductionAspect
   {
      /**
       * @org.jboss.aop.Mixin (target=com.mypackage.POJO.class, \
             interfaces={java.io.Externalizable.class})
       */   
      public static ExternalizableMixin createExternalizableMixin(POJO pojo) {
          return new ExternalizableMixin(pojo);
      }
   }
         

Since this is slightly more complex than the previous examples we have seen, the POJO and ExternalizableMixin classes are included here.

   package com.mypackage;
   
   public class POJO
   {
      String stuff;
   }
      

   package com.mypackage;
   
   import java.io.Externalizable;
   import java.io.IOException;
   import java.io.ObjectInput;
   import java.io.ObjectOutput;

   public class ExternalizableMixin implements Externalizable
   {
      POJO pojo;
      
      public ExternalizableMixin(POJO pojo)
      {
         this.pojo = pojo;
      }
   
      public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException
      {
         pojo.stuff = in.readUTF();  
      }
      
      public void writeExternal(ObjectOutput out) throws IOException
      {
         out.writeUTF(pojo.stuff);
      }
   }
      

This has the same effect as the following XML configuration:

            <introduction classs="com.mypackage.POJO">
            <mixin transient="true">
            <interfaces>
              java.io.Externalizable
            </interfaces>
            <class>com.mypackage.ExternalizableMixin</class>
            <construction>IntroductionAspect.createExternalizableMixin(this)</construction>
            </mixin>
            </introduction>
         

To prepare a joinpoint or a set of joinpoints for DynamicAOP annotate a field with @Prepare in a class anotated with @Aspect or @InterceptorDef.

The declaration of org.jboss.aop.Prepare is:

   package org.jboss.aop;
   
   @Target({ElementType.FIELD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME)
         public @interface Prepare {
       String value() default "";
   }
         

The single field value contains a pointcut expression matching one or more joinpoints.

To use @Prepare in JDK 1.5:

   package com.mypackage;

   import org.jboss.aop.Prepare;
   
   @InterceptorDef (scope = Scope.PER_VM)
   @Bind (pointcut="execution("* com.blah.Test->test(..)")
   public class MyInterceptor2 implements Interceptor
   {
      @Prepare ("all(com.blah.DynamicPOJO)")
      public static Pointcut dynamicPOJO;
   
      public Object invoke(Invocation invocation)throws Throwable
      {
         return invocation.invokeNext();
      }
   }

         

And in JDK 1.4.2:

   package com.mypackage;
   
   /**
    * @@org.jboss.aop.InterceptorDef (scope = org.jboss.aop.advice.Scope.PER_VM)
    * @@org.jboss.aop.Bind (pointcut="execution("* com.blah.Test->test(..)")
    */
   public class MyInterceptor2 implements Interceptor
   {
      /**
       * @@org.jboss.aop.Prepare ("all(com.blah.DynamicPOJO)")
       */
      public static Pointcut dynamicPOJO;

      public Object invoke(Invocation invocation)throws Throwable
      {
         return invocation.invokeNext();
      }
   }
         

Using XML configuration instead we would write:

            <prepare expr="all(com.blah.DynamicPOJO)"/>
         

This simple example used an @InterceptorDef class for a bit of variety in the examples, and to reiterate that @Pointcut, @Introduction, @Mixin, @Prepare, @Typedef, @CFlow, @DynamicCFlow and @AnnotationIntroductionDef can all be used both in @InterceptorDef annotated classes AND @Aspect annotated classes. Same for @Bind, but that is a special case as mentioned above.

   package com.mypackage;

   import org.jboss.aop.Prepare;
   
   @Prepare ("all(this)")
   public class MyDynamicPOJO implements Interceptor
   {
      ...
   }
           

   package com.mypackage;

   import org.jboss.aop.Prepare;
   
   /**
    * @@org.jboss.aop.Prepare ("all(this)")
    */
   public class MyDynamicPOJO implements Interceptor
   {
      ...
   }
           

            <prepare expr="all(com.blah.MyDynamicPOJO)"/>
           

To summarise, when using @Prepare within an @Interceptor or @Aspect annotated class, you annotate a field within that class. When using @Prepare with a POJO you annotate the class itself.

To use a typedef, you annotate a field with @TypeDef in a class anotated with @Aspect or @InterceptorDef.

The declaration of org.jboss.aop.TypeDef:

package org.jboss.aop;

@Target({ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME)
public @interface TypeDef {
    String value();
}
         

The single value field takes a type expression that resolves to one or more classes. The name of the typedef used for reference and internally is:

<name of @Aspect/@InterceptorDef annotated class>.<name of @TypeDef annotated field>

Here's how to use it with JDK 1.5:

   package com.mypackage;

   import org.jboss.aop.TypeDef;
   import org.jboss.aop.pointcut.Typedef;
   @Aspect (scope=org.jboss.aop.advice.Scope.PER_VM)
   public class TypedefAspect
   {
      @TypeDef ("class(com.blah.POJO)")
      public static Typedef myTypedef;
   
       @Bind (pointcut="execution(* \ 
             $typedef{com.mypackage.TypedefAspect.myTypedef}->methodWithTypedef())")
       public Object typedefAdvice(Invocation invocation) throws Throwable
      {
         return invocation.invokeNext();
      }
   }
         

And with JDK 1.4.2:

   package com.mypackage;

   import org.jboss.aop.TypeDef;
   import org.jboss.aop.pointcut.Typedef;
   
   /**
    * @@org.jboss.aop.Aspect (scope=org.jboss.aop.advice.Scope.PER_VM)
    */
   public class TypedefAspect
   {
      /**
       * @@org.jboss.aop.TypeDef ("class(com.blah.POJO)")
       */
      public static Typedef myTypedef;
   
      /**
       * @@org.jboss.aop.Bind (pointcut="execution(* \
          $typedef{com.mypackage.TypedefAspect.myTypedef}->methodWithTypedef())")
       */
      public Object typedefAdvice(Invocation invocation) throws Throwable
      {
         return invocation.invokeNext();
      }
   }
         

The equivalent using XML configuration would be:

            <aop>
            <aspect class="com.mypackage.TypedefAspect" scope="PER>VM"/>
            <typedef name="com.mypackage.TypedefAspect.myTypedef" expr="class(com.blah.POJO)"/>
            <bind
         pointcut="execution(* \
            $typedef{com.mypackage.TypedefAspect.myTypedef}->methodWithTypedef())"
            >
            <advice name="typedefAdvice" aspect="com.mypackage.TypedefAspect"/>
            </bind>
            </aop>
         

To create a CFlow stack, you annotate a field with @CFlowDef in a class anotated with @Aspect or @InterceptorDef. The declaration of org.jboss.aop.CFlowStackDef is:

   package org.jboss.aop;
   
   @Target({ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME)
         public @interface CFlowStackDef
   {
      CFlowDef[] cflows();
   }
         

In turn the declaration of org.jboss.aop.CFlowDef is:

   package org.jboss.aop;
   
   public @interface CFlowDef {
       boolean called();
       String expr();
   }
         

The parameters of @CFlowDef are:

The name of the CFlowStackDef used for reference and internally is:

<name of @Aspect/@InterceptorDef annotated class>.<name of @CFlowStackDef annotated field>

CFlowStackDef is used like this in JDK 1.5:

   package com.mypackage;

   import org.jboss.aop.CFlowStackDef;   
   import org.jboss.aop.pointcut.CFlowStack;   

   @Aspect (scope=org.jboss.aop.advice.Scope.PER_VM)
   public class CFlowAspect
   {
   
      @CFlowStackDef (cflows={@CFlowDef(expr= "void com.blah.POJO->cflowMethod1()", \
            called=false),  @CFlowDef(expr = "void com.blah.POJO->cflowMethod2()", \
            called=true)})
      public static CFlowStack cfNot1And2Stack;
   
      @Bind (pointcut="execution(void com.blah.POJO*->privMethod())", \ 
            cflow="com.mypackage.CFlowAspect.cfNot1And2Stack")
      public Object cflowAdvice(Invocation invocation) throws Throwable
      {
         return invocation.invokeNext();
      }
   }     
         

And in 1.4.2:

            
   package com.mypackage;

   import org.jboss.aop.pointcut.CFlowStack;   
   /**
    * @@org.jboss.aop.Aspect (scope=org.jboss.aop.advice.Scope.PER_VM)
    */
   public class CFlowAspect
   {
      
      /**
       * @@org.jboss.aop.CFlowStackDef (cflows={@org.jboss.aop.CFlowDef \
          (expr= "void com.blah.POJO->cflowMethod1()", called=false),  \
          @org.jboss.aop.CFlowDef (expr = "void com.blah.POJO->cflowMethod2()", \ 
          called=true)})
       */
      public static CFlowStack cfNot1And2Stack;
   
      /**
       * @@org.jboss.aop.Bind (pointcut="execution(void com.blah.POJO*->privMethod())", \
             cflow="com.mypackage.CFlowAspect.cfNot1And2Stack")
       */
      public Object cflowAdvice(Invocation invocation) throws Throwable
      {
         return invocation.invokeNext();
      }
   }     
         

The above means the same as this XML:

            <aop>
            <cflow-stack name="com.mypackage.CFlowAspect.cfNot1And2Stack">
            <called expr="void com.blah.POJO->cflowMethod1()"/>
            <not-called expr="void com.blah.POJO->cflowMethod2()"/>
            </cflow-stack>
            </aop>
         

To create a dynamic CFlow you annotate a class implementing org.jboss.aop.pointcut.DynamicCFlow with @DynamicCFlowDef. The declaration of @org.jboss.aop.DynamicCFlowDef is:

   package org.jboss.aop;
   
   @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
   public @interface DynamicCFlowDef
   {
   }
         

Here is a @DynamicCFlow annotated class in JDK 1.5:

   package com.mypackage;
   
   import org.jboss.aop.DynamicCFlowDef;
   import org.jboss.aop.pointcut.DynamicCFlow;
   
   @DynamicCFlowDef
   public class MyDynamicCFlow implements DynamicCFlow
   {
      public static boolean execute = false;
   
      public boolean shouldExecute(Invocation invocation)
      {
         return execute;
      }
   }
         

And the same in JDK 1.4.2:

   package com.mypackage;
   
   import org.jboss.aop.pointcut.DynamicCFlow;
   
   /**   
    * @org.jboss.aop.DynamicCFlowDef
    */
   public class MyDynamicCFlow implements DynamicCFlow
   {
      public static boolean execute = false;
   
      public boolean shouldExecute(Invocation invocation)
      {
         return execute;
      }
   }
         

The name of the @DynamicCFlowDef annotated class gets used as the name of the cflow for references.

To use the dynamic cflow we just defined in JDK 1.5:

   package com.mypackage;

   @Aspect (scope=org.jboss.aop.advice.Scope.PER_VM)
   public class CFlowAspect
   {
      @Bind (pointcut="execution(void com.blah.POJO->someMethod())", \
            cflow="com.mypackage.MyDynamicCFlow")
      public Object cflowAdvice(Invocation invocation) throws Throwable
      {
         return invocation.invokeNext();
      }
   }     
         

To use the dynamic cflow we just defined in JDK 1.5:

   package com.mypackage;
   
   /**
    * @@org.jboss.aop.Aspect (scope=org.jboss.aop.advice.Scope.PER_VM)
    */
   public class CFlowAspect
   {
      /**
       * @@org.jboss.aop.Bind (pointcut="execution(void com.blah.POJO->someMethod())", \
             cflow="com.mypackage.MyDynamicCFlow")
       */
      public Object cflowAdvice(Invocation invocation) throws Throwable
      {
         return invocation.invokeNext();
      }
   }     
         

You can introduce annotations by annotating a field with the @AnnotationIntroductionDef in a class anotated with @Aspect or @InterceptorDef. The declaration of org.jboss.aop.AnnotationIntroductionDef is:

   package org.jboss.aop;
   
   @Target (ElementType.FIELD) @Retention(RetentionPolicy.RUNTIME)
         public @interface AnnotationIntroductionDef
   {
      String expr();
      boolean invisible();
      String annotation();
   }
         

The parameters of @AnnotationIntroductionDef are:

The listings below make use of an annotation called @com.mypackage.MyAnnotation:

   package com.mypackage;
   public interface MyAnnotation
   {
      String string();
      int integer();
      boolean bool();
   }
         

What its parameters mean is not very important for our purpose.

The use of @AnnotationIntroductionDef in JDK 1.5:

   package com.mypackage;
   
   import org.jboss.aop.AnnotationIntroductionDef:
   import org.jboss.aop.introduction.AnnotationIntroduction;
   
   @.InterceptorDef (scope=org.jboss.aop.advice.Scope.PER_VM)
   @org.jboss.aop.Bind (pointcut="all(com.blah.SomePOJO)")
   public class IntroducedAnnotationInterceptor implements Interceptor
   {
      @org.jboss.aop.AnnotationIntroductionDef \
            (expr="method(* com.blah.SomePOJO->annotationIntroductionMethod())", \
             invisible=false, \
             annotation="@com.mypackage.MyAnnotation \
                (string='hello', integer=5, bool=true)")
      public static AnnotationIntroduction annotationIntroduction;
      
      public String getName()
      {
         return "IntroducedAnnotationInterceptor";
      }
   
      public Object invoke(Invocation invocation) throws Throwable
      {
         return invocation.invokeNext();
      }
   }
         

Note that the reference to @com.mypackage.MyAnnotation must use the fully qualified class name, and that the value for its string parameter uses single quotes.

The use of @AnnotationIntroductionDef in JDK 1.4.2:

   package com.mypackage;
   
   import org.jboss.aop.introduction.AnnotationIntroduction;
   
   /**
    * @@org.jboss.aop.InterceptorDef (scope=org.jboss.aop.advice.Scope.PER_VM)
    * @@org.jboss.aop.Bind (pointcut="all(com.blah.SomePOJO)")
    */
   public class IntroducedAnnotationInterceptor implements Interceptor
   {
      /**
       * @@org.jboss.aop.AnnotationIntroductionDef \
             (expr="method(* com.blah.SomePOJO->annotationIntroductionMethod())", \
             invisible=false, \
             annotation="@com.mypackage.MyAnnotation \
             (string='hello', integer=5, bool=true)")
       */
      public static AnnotationIntroduction annotationIntroduction;
      
      public String getName()
      {
         return "IntroducedAnnotationInterceptor";
      }
   
      public Object invoke(Invocation invocation) throws Throwable
      {
         return invocation.invokeNext();
      }
   }
         

Note that the reference to only uses one '@', and that the value for its string parameter uses single quotes.

The previous listings are the same as this XML configuration:

            <annotation-introduction
      expr="method(* com.blah.SomePOJO->annotationIntroductionMethod()) 
      invisible="false"
            >
      @com.mypackage.MyAnnotation (string="hello", integer=5, bool=true)
            </annotation-introduction>
         

You can declare precedence by annotating a class with @Precedence, and then annotate fields where the types are the various Interfaces/Aspects you want to sort. You annotate fields where the type is an interceptor with @PrecedenceInterceptor. When the type is an aspect class, you annotate the field with @PrecedenceAdvice. The definitions of org.jboss.aop.Precedence, org.jboss.aop.PrecedenceInterceptor and org.jboss.aop.PrecedenceAdvice are

   package org.jboss.aop;
   
   @Target({ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME)
   public @interface Precedence
   {
   }
      

   package org.jboss.aop;
   
   @Target({ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME)
   public @interface PrecedenceInterceptor
   {
   }      
      

   package org.jboss.aop;

   @Target({ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME)
   public @interface PrecedenceAdvice
   {
      String value();
   }
      

The value() attribute of PrecedenceAdvice is the name of the advice method to use.

The example shown below declares a relative sort order where org.acme.Interceptor must always be invoked before org.acme.Aspect.advice1() which must be invoked before org.acme.Aspect.advice2(). Here is the JDK 1.5 version:

   import org.jboss.aop.Precedence;
   import org.jboss.aop.PrecedenceAdvice;
         
   @Precedence
   public class MyPrecedence
   {
      @PrecedenceInterceptor
      org.acme.Interceptor intercept;

      @PrecedenceAdvice ("advice1")
      org.acme.Aspect precAdvice1;

      @PrecedenceAdvice ("advice2")
      org.acme.Aspect precAdvice2;
   }         
      

And the JDK 1.4 version:

   /**
    * @@org.jboss.aop.Precedence
    */
   public class MyPrecedence
   {
      /**
       * @@org.jboss.aop.PrecedenceInterceptor
       */
      org.acme.Interceptor intercept;

      /**
       * @@org.jboss.aop.PrecedenceAdvice ("advice1")
       */
      org.acme.Aspect precAdvice1;

      /**
       * @@org.jboss.aop.PrecedenceAdvice ("advice2")
       */
      org.acme.Aspect precAdvice2;
   }         
      

The ordering of interceptors/advices defined via annotations that have no precedence defined, is arbitrary.

You can declare checks to be enforced at instrumentation time. They take a pointcut and a message. If the pointcut is matched, the message is printed out. To use this with annotations, annotate fields with DeclareWarning or DeclareError within a class annotated with @Aspect or @InterceptorDef. The definitions of org.jboss.aop.DeclareError and org.jboss.aop.DeclareWarning are:

   package org.jboss.aop;

   @Target({ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME)
   public @interface DeclareWarning
   {
      String expr();
      String msg();
   }
      

   package org.jboss.aop;
   
   @Target({ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME)
   public @interface DeclareError
   {
      String expr();
      String msg();
   }
      

For both: the expr() attribute is a pointcut expression that should not occur, and the msg() attribute is the message to print out if a match is found for the pointcut. If you use DeclareWarning instrumentation/your application will simply continue having printed the message you supplied. In the case of DeclareError, the message is logged and an error is thrown, causing instrumentation/your application to stop. Here is an example in JDK 1.5

   import org.jboss.aop.Aspect;
   import org.jboss.aop.pointcut.Pointcut;
   import org.jboss.aop.DeclareError;
   import org.jboss.aop.DeclareWarning;
   
   @Aspect (scope=org.jboss.aop.advice.Scope.PER_VM)
   public class DeclareAspect
   {
      @DeclareWarning (expr="class($instanceof{VehicleDAO}) AND \
         !has(public void *->save())", \
         msg="All VehicleDAO subclasses must override the save() method.")
      Pointcut warning;
   
      @DeclareError (expr="call(* org.acme.businesslayer.*->*(..)) \
         AND within(org.acme.datalayer.*)", \
         msg="Data layer classes should not call up to the business layer")
      Pointcut error;
   }         
      

And in JDK 1.4:

   import org.jboss.aop.pointcut.Pointcut;
   
   /**
    * @@org.jboss.aop.Aspect (scope=org.jboss.aop.advice.Scope.PER_VM)
    */
   public class DeclareAspect
   {
      /**
       * @@org.jboss.aop.DeclareWarning (expr="class($instanceof{VehicleDAO}) AND \
          !has(public void *->save())", \
          msg="All VehicleDAO subclasses must override the save() method.")
       */
      Pointcut warning;
   
      /**
       * @@org.jboss.aop.DeclareError (expr="call(* org.acme.businesslayer.*->*(..)) \
          AND within(org.acme.datalayer.*)", \
          msg="Data layer classes should not call up to the business layer")
       */
      Pointcut error;
   }         
      

With JBoss AOP you can change advice and interceptor bindings at runtime. You can unregister existing bindings, and hot deploy new bindings if the given joinpoints have been instrumented. Hot-deploying within the JBoss application server is as easy as putting (or removing) a *-aop.xml file or .aop jar file within the deploy/ directory. There is also a runtime API for adding advice bindings at runtime. Getting an instance of org.jboss.aop.AspectManager.instance(), you can add your binding.

      org.jboss.aop.advice.AdviceBinding binding = new AdviceBinding("execution(POJO->new(..))", null);
      binding.addInterceptor(SimpleInterceptor.class);
      AspectManager.instance().addBinding(binding);

First, you allocated an AdviceBinding passing in a pointcut expression. Then you add the interceptor via its class and then add the binding through the AspectManager. When the binding is added the AspectManager will iterate through ever loaded class to see if the pointcut expression matches any of the joinpoints within those classes.

Any class that is instrumented by JBoss AOP, is forced to implement the org.jboss.aop.Advised interface.

public interface InstanceAdvised
{
   public InstanceAdvisor _getInstanceAdvisor();
   public void _setInstanceAdvisor(InstanceAdvisor newAdvisor);
}

public interface Advised extends InstanceAdvised
{
   public Advisor _getAdvisor();
}

The InstanceAdvisor is the interesting interface here. InstanceAdvisor allows you to insert Interceptors at the beginning or the end of the class's advice chain.

public interface InstanceAdvisor
{
   public void insertInterceptor(Interceptor interceptor);
   public void removeInterceptor(String name);
   public void appendInterceptor(Interceptor interceptor);

   public void insertInterceptorStack(String stackName);
   public void removeInterceptorStack(String name);
   public void appendInterceptorStack(String stackName);

   public SimpleMetaData getMetaData();

}

So, there are three advice chains that get executed consecutively in the same java call stack. Those interceptors that are added with the insertInterceptor() method for the given object instance are executed first. Next, those advices/interceptors that were bound using regular binds . Finally, those interceptors added with the appendInterceptor() method to the object instance are executed. You can also reference stacks and insert/append full stacks into the pre/post chains.

Besides interceptors, you can also append untyped metadata to the object instance via the getMetaData() method.

Dynamic AOP cannot be used unless the particular joinpoint has been instrumented. You can force intrumentation with the prepare functionality

When running JBoss AOP with HotSwap, the dynamic AOP operations may result in the weaving of bytecodes. In this case, the flow control of joinpoints matched only by prepare expressions is not affected before any advices or interceptors are applied to them via dynamic aop. Only then, the joinpoint bytecodes will be weaved to start invoking the added advices and interceptors and, as a result, their flow control will be affected.

On the other hand, if HotSwap is disabled, the joinpoints matched by prepare expressions are completely instrumented and the flow control is affected before classes get loaded, even if no interceptors are applied to them with dynamic aop.

To learn how to enable HotSwap, refer to the "Running Aspectized Application" chapter.

Annotations are only available in JDK 1.5, but using our annotation compiler you can acheive similar functionality with JDK 1.4.2.

Annotations must map to an annotation type, in JDK 1.5 they are defined as:

   package com.mypackage;
   
   public @interface MyAnnotation
   {
      String myString();
      int myInteger();
   }            
         

Annotation types for use with the annotation compiler are defined in exactly the same way for JDK 1.4.2, with the important difference that '@interface' is replaced by 'interface'. i.e. the simulater annotation type is a normal Java interface:

   package com.mypackage;
   
   public interface MyAnnotation
   {
      String myString();
      int myInteger();
   }            
         

The syntax for using annotations in JDK 1.4.2 is almost exactly the same as JDK 1.5 annotations except for these subtle differences:

This example shows an annotated class in JDK 1.4.2:

   package com.mypackage;
   
   /**
    * @@com.mypackage.MyAnnotation (myString="class", myInteger=5)
    */
   public class MyClass
   {
      /**
       * @@com.mypackage.MyAnnotation (myString="field", myInteger=4)
       */
      private String myField;
      
      /**
       * @@com.mypackage.MyAnnotation (myString="constructor", myInteger=3)
       */
      public MyClass()
      {
      }
      
      /**
       * @@com.mypackage.MyAnnotation (myString="method", myInteger=3)
       */
      public int myMethod()
      {
      }
   }            
         

Another JDK 1.5 feature that JBoss AOP helps introduce to JBoss 1.4.2 are Enums. As an example we can look at the org.jboss.aop.advice.Scope enum that is used for the @Aspect annotation. Here is the JDK 1.5 version.

            package org.jboss.aop.advice;
            
            public enum Scope
            {
               PER_VM, PER_CLASS, PER_INSTANCE, PER_JOINPOINT
            }         
         

And it's usage in JDK 1.5

   package com.mypackage;

   @Aspect (scope=org.jboss.aop.advice.Scope.PER_VM)
   public class SomeAspect
   {
   }     
         

The usage in JDK 1.4.2 is similar:

   package com.mypackage;
   
   /**
    * @@org.jboss.aop.Aspect (scope=org.jboss.aop.advice.Scope.PER_VM)
    */
   public class SomeAspect
   {
      //...
   }     
         

However the declaration of the enumeration is different in 1.4.2:

   package org.jboss.aop.advice;
   
   import java.io.ObjectStreamException;
   
   public class Scope extends org.jboss.lang.Enum
   {
      private Scope(String name, int v)
      {
         super(name, v);
      }
   
      public static final Scope PER_VM = new Scope("PER_VM", 0);
      public static final Scope PER_CLASS = new Scope("PER_CLASS", 1);
      public static final Scope PER_INSTANCE = new Scope("PER_INSTANCE", 2);
      public static final Scope PER_JOINPOINT = new Scope("PER_JOINPOINT", 3);
      
      private static final Scope[] values = {PER_VM, PER_CLASS, PER_INSTANCE, PER_JOINPOINT};
   
      Object readResolve() throws ObjectStreamException
      {
         return values[ordinal];
      }
   
   }
         

To create your own enum class for use within annotations, you need to inherit from org.jboss.lang.Enum. Each enum has two values, a String name, and an integer ordinal. The value used for the ordinal must be the same as it's index in the static array.

The annotation compiler allows you to use annotations within annotations. This is best illustrated with an example. The definitions of the annotation interfaces in JDK 1.4.2:

            com.mypackage;
            
            public interface Outer
            {
               Inner[] values();
            }
         

            com.mypackage;
            
            public interface Inner
            {
               String str();
               int integer();
            }
         

The annotations can be applied as follows

            com.mypackage;
            
            /**
             * @@com.mypackage.Outer ({@@com.mypackage.Inner (str="x", integer=1), \ 
                   @@com.mypackage.Inner (str="y", integer=2)})
             */
            public class Test
            {
               Inner[] values();
            }
         

In order to use the JDK 1.4.2 annotations you have to precompile your files with an annotation compiler.

To use the annotation compiler you can create a simple ant build.xml file

            <?xml version="1.0" encoding="UTF-8"?>

            <project default="run" name="JBoss/AOP">
            <target name="prepare">
         

Include the jars AOP depends on

            <path id="javassist.classpath">
            <pathelement path="../../../javassist.jar"/>
            </path>
            <path id="trove.classpath">
            <pathelement path="../../../trove.jar"/>
            </path>
            <path id="concurrent.classpath">
            <pathelement path="../../../concurrent.jar"/>
            </path>
            <path id="jboss.common.classpath">
            <pathelement path="../../../jboss-common.jar"/>
            </path>
            <path id="jboss.aop.classpath">
            <pathelement path="../../../jboss-aop.jar"/>
            </path>
            <path id="qdox.classpath">
            <pathelement path="../../../qdox.jar"/>
            </path>
            <path id="classpath">
            <path refid="javassist.classpath"/>
            <path refid="trove.classpath"/>
            <path refid="jboss.aop.classpath"/>
            <path refid="jboss.common.classpath"/>
            <path refid="concurrent.classpath"/>
            <path refid="qdox.classpath"/>
            </path>

         

Define the ant task that does the annnotation compilation

            <taskdef
         name="annotationc" 
         classname="org.jboss.aop.ant.AnnotationC"
         classpathref="jboss.aop.classpath"
      />
            </target>


            <target name="compile" depends="prepare">
         

Compile the source files

            <javac srcdir="."
         destdir="."
         debug="on"
         deprecation="on"
         optimize="off"
         includes="**">
            <classpath refid="classpath"/>
            </javac>
         

Run the annotation compiler

            <annotationc compilerclasspathref="classpath" classpath="." bytecode="true">
            <src path="."/>
            </annotationc>
            </target>

            </project>
         

The org.jboss.aop.ant.AnnotationC ant task takes several parameters.

You cannot currently specify both bytecode and xml.

You can also run org.jboss.aop.ant.AnnotationC from the command line, you need

   $ java -cp <all the JBoss AOP jars and the directory containing files we want to AOP> \ 
         org.jboss.aop.annotation.compiler.AnnotationCompiler \ 
         [-xml [-o outputfile ]] [-bytecode]<files>+
         

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 is:

   $ annotationc <classpath> [-verbose] [-xml [-o outputfile]] [-bytecode] <dir_or_file>+
         

The other parameters are the same as above.

There's nothing really to install if you're running outside the JBoss application server. If you are using JDK 1.4.x, use the libraries under the lib/ directory to build your JBoss AOP applications. If you're using JDK 5.0, use the libraries under lib-50/.

To install JBoss AOP in JBoss 4.x Application Server:

JBoss AOP only works with JBoss Application Server 3.2.6RC1+ and only with the precompiler. Load-time AOP is not supported at this time for JBoss 3.2.x application server. To install JBoss AOP to JBoss Application Server, copy all jars in the jboss-32-install/ or jboss-32-install-jdk5 directory to the server/<config-name>/lib depending on what version of the JDK you use.

JBoss AOP works by instrumenting the classes you want to run. This means that modifications to the bytecode are made in order to add extra information to the classes to hook into the AOP library. JBoss AOP allows for two types of instrumentation

This chapter describes the steps you need to take to precompile your classes with the aop precompiler.

JBoss AOP comes with an ant task that you can use for precompiling your classes with the aop precompiler. An example build.xml file is the basis for the explanation. (It is quite similar to the one used in the previous chapter.) There will be differences in the build.xml file if you are using JDK 1.4.2 or JDK 5.0, these are outlined below:

<?xml version="1.0" encoding="UTF-8"?>

<project default="compile" name="JBoss/AOP">
   <target name="prepare">
         

Define the source directory, and the directory to compile classes to. If you're not fussy, they can point to the same directory.

         <property name="src.dir" value="PATH TO YOUR SOURCE DIR">
         <property name="classes.dir" value="PATH TO YOUR DIR FOR COMPILED CLASSES">
         

Include the jars AOP depends on, these are common to all JDK's

         <path id="javassist.classpath">
            <pathelement path="../../../javassist.jar"/>
         </path>

         <path id="trove.classpath">
            <pathelement path="../../../trove.jar"/>
         </path>

         <path id="concurrent.classpath">
            <pathelement path="../../../concurrent.jar"/>
         </path>

         <path id="jboss.common.classpath">
            <pathelement path="../../../jboss-common.jar"/>
         </path>

         <path id="lib.classpath">
            <path refid="javassist.classpath"/>
            <path refid="trove.classpath"/>
            <path refid="jboss.aop.classpath"/>
            <path refid="jboss.common.classpath"/>
            <path refid="concurrent.classpath"/>
         </path>
         

This snippet shows what to do for JDK 1.4. It will also work with JDK 5.0 if your classes do not use JDK 5.0 style annotations and enums:

         <!--                  JDK version 1.4.2                         -->
         <!-- Do not include this if using JDK 1.5 with annotations!!!!  -->

         <path id="jboss.aop.classpath">
            <pathelement path="../../../jboss-aop.jar"/>
         </path>

         <!--            JDK version 1.4.2 - END                         -->
         

This snippet shows what to do for JDK 5.0 if you are using JDK 5.0 annotations:

         <!--            JDK version 1.5                                 -->
         <!-- Do not include this if using JDK 1.4.2!!!!                 -->

         <path id="jboss.aop.classpath">
            <pathelement path="../../../jboss-aop-jdk15.jar"/>
         </path>

         <!--            JDK version 1.5 - END                           -->
         

(You should only use one of the two previous snippets for setting up jboss.aop.classpath)

Now we set up the full classpath of all the needed libraries:

         <path id="classpath">
            <path refid="lib.classpath"/>
            <path refid="jboss.aop.classpath"/>
         </path id="classpath">
         

Define the org.jboss.aop.ant.AopC ant aop precompiler task:

         <taskdef name="aopc" classname="org.jboss.aop.ant.AopC"
               classpathref="jboss.aop.classpath"/>
         </target>
         

>
            <target name="compile" depends="prepare">
         

Compile the files (from the source directory to the compiled classes directory:

         <javac srcdir="${src.dir}"
                destdir="${classes.dir}"
                debug="on"
                deprecation="on"
                optimize="off"
                includes="**">
            <classpath refid="classpath"/>
         </javac>
         

Now use the ant aop precompiler task, it reads the files from the

         <aopc compilerclasspathref="classpath" verbose="true">
            <classpath path="${classes.dir}"/>
            <src path="${classes.dir}"/>
            <include name="**/*.class"/>
            <aoppath path="jboss-aop.xml"/>
            <aopclasspath path="aspects.jar"/>
         </aopc>
         

If you are using JDK 1.4.2 and wish to use annotations, you need to define the org.jboss.aop.ant.AnnotationC ant task, and run that BEFORE you invoke the org.jboss.aop.ant.AopC task. How to do this is shown in the previous chapter.

The org.jboss.aop.ant.AopC ant task takes several parameters.

To run the aop precompiler from the command line you need all the aop jars on your classpath, and the class files you are instrumenting must have everything they would need to run in the java classpath, including themselves, or the precompiler will not be able to run.

The jboss.aop.path optional system property points to XML files that contain your pointcut, advice bindings, and metadata definitions that the precompiler will use to instrument the .class files. The property can have one or files it points to delimited by the operating systems specific classpath delimiter (';' on windows, ':' on unix). Files or Directories can be specified. If it is a directory, JBoss AOP will take all aop.xml files from that directory.

The jboss.aop.class.path optional system property points to all JARs or directories that may have classes that are annotated as @Aspect (See Chapter "Annotated Bindings"). JBoss AOP will browse all classes in this path to see if they are annotated. The property can have one or files it points to delimited by the operating systems specific classpath delimiter (';' on windows, ':' on unix). Note for this to have effect with JDK 1.4, you first have to run the annotation compiler with bytecode=true.

It is invoked as:

$java -classpath ... [-Djboss.aop.path=...] [-Djboss.aop.class.path=...] \
                     org.jboss.aop.standalone.Compiler <class files or directories>
         

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:

$ aopc <classpath> [-aoppath ...] [-aopclasspath ...] [-report] [-verbose] \
      <class files or directories>+
         

And for JDK 1.5:

$ aopc15 <classpath> [-aoppath ...] [-aopclasspath ...] [-report] [-verbose] \
      <class files or directories>+
         

The other parameters are the same as above.

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.

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

JBoss AOP is integrated with JBoss 4.0 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.

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

                  <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>
    

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

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

                  <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>
    

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

               <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>
      

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.

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.

To address the issues with interceptors not being invoked when you use reflection, we have provided a reflection aspect. You bind it to a set of caller pointcuts, and it mounts the pre-defined interceptor/aspect chains. The jboss-aop.xml entries are:

    
   <aspect class="org.jboss.aop.reflection.ReflectionAspect" scope="PER_VM"/>

   <bind pointcut="call(* java.lang.Class->newInstance())">
      <advice name="interceptNewInstance" \
         aspect="org.jboss.aop.reflection.ReflectionAspect"/>
   </bind>

   <bind pointcut="call(* java.lang.reflect.Constructor->newInstance(java.lang.Object[]))">
      <advice name="interceptNewInstance" \
         aspect="org.jboss.aop.reflection.ReflectionAspect"/>
   </bind>

   <bind pointcut="call(* java.lang.reflect.Method->invoke(java.lang.Object, java.lang.Object[]))">
      <advice name="interceptMethodInvoke" \
         aspect="org.jboss.aop.reflection.ReflectionAspect"/>
   </bind>

   <bind pointcut="call(* java.lang.reflect.Field->get*(..))">
      <advice name="interceptFieldGet" \
         aspect="org.jboss.aop.reflection.ReflectionAspect"/>
   </bind>

   <bind pointcut="call(* java.lang.reflect.Field->set*(..))">
      <advice name="interceptFieldSet" \
         aspect="org.jboss.aop.reflection.ReflectionAspect"/>
   </bind>   

         

The ReflectionAspect class provides a few hooks for you to override from a subclass if you like. These methods described below.

   protected Object interceptConstructor(
		Invocation invocation,
		Constructor constructor,
		Object[] args)
		throws Throwable;
         

Calls to Class.newInstance() and Constructor.newInstance() end up here. The default behavior is to mount any constructor execution or caller interceptor chains. If you want to override the behaviour, the parameters are:

   protected Object interceptFieldRead(
      Invocation invocation,
      Field field,
      Object instance)
      throws Throwable;
         

Calls to Field.getXXX() end up here. The default behavior is to mount any field read interceptor chains. If you want to override the behaviour, the parameters are:

   protected Object interceptFieldWrite(
      Invocation invocation,
      Field field,
      Object instance,
      Object arg)
      throws Throwable;
         

Calls to Field.setXXX() end up here. The default behavior is to mount any field write interceptor chains. If you want to override the behaviour, the parameters are:

   protected Object interceptMethod(
		Invocation invocation,
		Method method,
		Object instance,
		Object[] args)
		throws Throwable;
         

Calls to Method.invoke() end up here. The default behavior is to mount any method caller interceptor chains (method execution chains are handled correctly by default). If you want to override the behaviour, the parameters are:

The ReflectionAspect also helps with getting rid of the JBoss AOP "plumbing" information. You bind it to a set of caller pointcuts, using the followingjboss-aop.xml entries :

   
   <bind pointcut="call(* java.lang.Class->getInterfaces())">
      <advice name="interceptGetInterfaces" \
         aspect="org.jboss.test.aop.reflection.ReflectionAspectTester"/>
   </bind>

   <bind pointcut="call(* java.lang.Class->getDeclaredMethods())">
      <advice name="interceptGetDeclaredMethods" \
         aspect="org.jboss.test.aop.reflection.ReflectionAspectTester"/>
   </bind>

   <bind pointcut="call(* java.lang.Class->getDeclaredMethod(..))">
      <advice name="interceptGetDeclaredMethod" \
         aspect="org.jboss.test.aop.reflection.ReflectionAspectTester"/>
   </bind>

   <bind pointcut="call(* java.lang.Class->getMethods())">
      <advice name="interceptGetMethods" \
         aspect="org.jboss.test.aop.reflection.ReflectionAspectTester"/>
   </bind>

   <bind pointcut="call(* java.lang.Class->getMethod(..))">
      <advice name="interceptGetMethod" \
         aspect="org.jboss.test.aop.reflection.ReflectionAspectTester"/>
   </bind>

   <bind pointcut="call(* java.lang.Class->getDeclaredFields())">
      <advice name="interceptGetDeclaredFields" \
         aspect="org.jboss.test.aop.reflection.ReflectionAspectTester"/>
   </bind>

   <bind pointcut="call(* java.lang.Class->getDeclaredClasses())">
      <advice name="interceptGetDeclaredClasses" \
         aspect="org.jboss.test.aop.reflection.ReflectionAspectTester"/>
   </bind>

   <bind pointcut="call(* java.lang.Class->getDeclaredField(..))">
      <advice name="interceptGetDeclaredField" \
         aspect="org.jboss.test.aop.reflection.ReflectionAspectTester"/>
   </bind>

         

This way the calls to Class.getMethods() etc. only return information that is present in the "raw" class, by filtering out the stuff added to the class by JBoss AOP.

JBoss AOP comes with an Eclipse plugin that helps you define interceptors to an eclipse project via a GUI, and to run the appication from within Eclipse. This is a new project, and expect the feature set to grow quickly!

You install the JBoss AOP IDE in the same way as any other Eclipse plugin.