For a call join point where a call is made to a method m(parameter_types) on a target type T (where T is the static type of the target):

		T t = new T(); 
		t.m("hello");  <= call join point occurs when this line is executed
		

Then the signature R(T) T.m(parameter_types) is a signature of the call join point, where R(T) is the return type of id in T, and parameter_types are the parameter types of m. If T itself does not declare a definition of m(parameter_types), then R(T) is the return type in the definition of m that T inherits. Given the call above, and the definition of T.m:

        interface Q {
          R m(String s);
        }
        
        class P implements Q {
          R m(String s) {...}        
        }
        
        class S extends P {
          R' m(String s) {...}
        }
        
        class T extends S {} 
		
		

Then R' T.m(String) is a signature of the call join point for t.m("hello").

For each ancestor (super-type) A of T, if m(parameter_types) is defined for that super-type, then R(A) A.m(parameter_types) is a signature of the call join point, where R(A) is the return type of m(parameter_types) as defined in A, or as inherited by A if A itself does not provide a definition of m(parameter_types).

Continuing the example from above,we can deduce that

        R' S.m(String)
        R  P.m(String)
        R  Q.m(String)
		

are all additional signatures for the call join point arising from the call t.m("hello"). Thus this call join point has four signatures in total. Every signature has the same id and parameter types, and a different declaring type.

Join point signatures for execution join points are defined in a similar manner to signatures for call join points. Given the hierarchy:

        interface Q {
          R m(String s);
        }
        
        class P implements Q {
          R m(String s) {...}        
        }
        
        class S extends P {
          R' m(String s) {...}
        }
        
        class T extends S { }
        
        class U extends T {
          R' m(String s) {...}
        }
		
		

Then the execution join point signatures arising as a result of the call to u.m("hello") are:

        R' U.m(String)
        R' S.m(String)
        R  P.m(String)
        R  Q.m(String)
		

Each signature has the same id and parameter types, and a different declaring type. There is one signature for each type that provides its own declaration of the method. Hence in this example there is no signature R' T.m(String) as T does not provide its own declaration of the method.

For a field get join point where an access is made to a field f of type F on a object with declared type T, then F T.f is a signature of the get join point.

If T does not directly declare a member f, then for each super type S of T, up to and including the most specific super type of T that does declare the member f, F S.f is a signature of the join point. For example, given the hierarchy:

        
        class P  {
          F f;        
        }
        
        class S extends P {
          F f;
        }
        
        class T extends S { }                
		

Then the join point signatures for a field get join point of the field f on an object with declared type T are:

        F S.f
        F T.f
		

The signatures for a field set join point are derived in an identical manner.

Java 5 introduces annotation types which can be used to express metadata relating to program members in the form of annotations. Annotations in Java 5 can be applied to package and type declarations (classes, interfaces, enums, and annotations), constructors, methods, fields, parameters, and variables. Annotations are specified in the program source by using the @ symbol. For example, the following piece of code uses the @Deprecated annotation to indicate that the obsoleteMethod() has been deprecated:

		@Deprecated
		public void obsoleteMethod() { ... }
		

Annotations may be marker annotations, single-valued annotations, or multi-valued annotations. Annotation types with no members or that provide default values for all members may be used simply as marker annotations, as in the deprecation example above. Single-value annotation types have a single member, and the annotation may be written in one of two equivalent forms:

		@SuppressWarnings({"unchecked"})
		public void someMethod() {...}
		

or

		@SuppressWarnings(value={"unchecked"})
		public void someMethod() {...}
		

Multi-value annotations must use the member-name=value syntax to specify annotation values. For example:

		@Authenticated(role="supervisor",clearanceLevel=5)
		public void someMethod() {...}
		

Annotations can have one of three retention policies:

Local variable annotations are not retained in class files (or at runtime) regardless of the retention policy set on the annotation type. See JLS 9.6.1.2.

Java 5 supports a new interface, java.lang.reflect.AnnotatedElement, that is implemented by the reflection classes in Java (Class, Constructor, Field, Method, and Package). This interface gives you access to annotations that have runtime retention via the getAnnotation, getAnnotations, and isAnnotationPresent. Because annotation types are just regular Java classes, the annotations returned by these methods can be queried just like any regular Java object.

It is important to understand the rules relating to inheritance of annotations, as these have a bearing on join point matching based on the presence or absence of annotations.

By default annotations are not inherited. Given the following program

			@MyAnnotation
			class Super {
			  @Oneway public void foo() {}
			}
			
			class Sub extends Super {
			  public void foo() {}
			}
			

Then Sub does not have the MyAnnotation annotation, and Sub.foo() is not an @Oneway method, despite the fact that it overrides Super.foo() which is.

If an annotation type has the meta-annotation @Inherited then an annotation of that type on a class will cause the annotation to be inherited by sub-classes. So, in the example above, if the MyAnnotation type had the @Inherited attribute, then Sub would have the MyAnnotation annotation.

@Inherited annotations are not inherited when used to annotate anything other than a type. A type that implements one or more interfaces never inherits any annotations from the interfaces it implements.

For any kind of annotated element (type, method, constructor, package, etc.), an annotation pattern can be used to match against the set of annotations on the annotated element. Annotation patterns are defined by the following grammar.

		AnnotationPattern := '!'? '@' AnnotationTypePattern AnnotationPattern* 
        
		AnnotationTypePattern := FullyQualifiedName |
		                         '(' TypePattern ')'
  		                     
  		FullyQualifiedName := JavaIdentifierCharacter+ ('.' JavaIdentifierCharacter+)*  		
      

In simple terms, an annotation pattern element has one of two basic forms:

These simple elements may be negated using !, and combined by simple concatentation. The pattern @Foo @Boo matches an annotated element that has both an annotation of type Foo and an annotation of type Boo.

Some examples of annotation patterns follow:

      @Immutable
      

Matches any annotated element which has an annotation of type Immutable.

      !@Persistent
      

Matches any annotated element which does not have an annotation of type Persistent.

      @Foo @Goo
      

Matches any annotated element which has both an annotation of type Foo and an annotation of type Goo.

      @(Foo || Goo)
      

Matches any annotated element which has either an annotation of a type matching the type pattern (Foo || Goo). In other words, an annotated element with either an annotation of type Foo or an annotation of type Goo (or both). (The parenthesis are required in this example).

      @(org.xyz..*)
      

Matches any annotated element which has either an annotation of a type matching the type pattern (org.xyz..*). In other words, an annotated element with an annotation that is declared in the org.xyz package or a sub-package. (The parenthesis are required in this example).

AspectJ 1.5 extends type patterns to allow an optional AnnotationPattern prefix. (Extensions to this definition for generics are shown in the next chapter).

  	  	TypePattern := SimpleTypePattern |
  	  	               '!' TypePattern |
  	  	               '(' AnnotationPattern? TypePattern ')'
  	  	               TypePattern '&&' TypePattern |
  	  	               TypePattern '||' TypePattern |
  	  	
  	  	SimpleTypePattern := DottedNamePattern '+'? '[]'*
  	  	
  		DottedNamePattern := FullyQualifiedName RestOfNamePattern? |
  		                     '*' NotStarNamePattern?
  		
  		RestOfNamePattern := '..' DottedNamePattern |
  		                     '*' NotStarNamePattern?
  		                     
  		NotStarNamePattern := FullyQualifiedName RestOfNamePattern? |
  		                      '..' DottedNamePattern               

  		FullyQualifiedName := JavaIdentifierCharacter+ ('.' JavaIdentifierCharacter+)*  				  		  		  		               									 				  		             
	

Note that in most cases when annotations are used as part of a type pattern, the parenthesis are required (as in (@Foo Hello+)). In some cases (such as a type pattern used within a this pointcut expression, the parenthesis are optional:

        OptionalParensTypePattern := AnnotationPattern? TypePattern
      

The following examples illustrate the use of annotations in type patterns:

     (@Immutable *)
     

Matches any type with an @Immutable annotation.

     (!@Immutable *)
     

Matches any type which does not have an @Immutable annotation.

     (@Immutable (org.xyz.* || org.abc.*))
     

Matches any type in the org.xyz or org.abc packages with the @Immutable annotation.

     ((@Immutable Foo+) || Goo)
     

Matches a type Foo or any of its subtypes, which have the @Immutable annotation, or a type Goo.

     ((@(Immutable || NonPersistent) org.xyz..*)
     

Matches any type in a package beginning with the prefix org.xyz, which has either the @Immutable annotation or the @NonPersistent annotation.

     (@Immutable @NonPersistent org.xyz..*)
     

Matches any type in a package beginning with the prefix org.xyz, which has both an @Immutable annotation and an @NonPersistent annotation.

     (@(@Inherited *) org.xyz..*)
     

Matches any type in a package beginning with the prefix org.xyz, which has an inheritable annotation. The annotation pattern @(@Inherited *) matches any annotation of a type matching the type pattern @Inherited *, which in turn matches any type with the @Inherited annotation.

A FieldPattern is described by the following grammar:

  	
  		FieldPattern := 
  		    AnnotationPattern? FieldModifiersPattern? 
  		    TypePattern (TypePattern DotOrDotDot)? SimpleNamePattern

		FieldModifiersPattern := '!'? FieldModifier FieldModifiersPattern*
		                         		
		FieldModifier := 'public' | 'private' | 'protected' | 'static' | 
		                 'transient' | 'final' 

		DotOrDotDot := '.' | '..'		            		      
		            		      		            			
		SimpleNamePattern := JavaIdentifierChar+ ('*' SimpleNamePattern)?		            
	

The optional AnnotationPattern restricts matches to fields with annotations that match the pattern. For example:

A MethodPattern is of the form

  	
  		MethodPattern := 
  		    AnnotationPattern? MethodModifiersPattern? TypePattern 
  		                       (TypePattern DotOrDotDot)? SimpleNamePattern 
  		                       '(' FormalsPattern ')'ThrowsPattern?

		MethodModifiersPattern := '!'? MethodModifier MethodModifiersPattern*
		
		MethodModifier := 'public' | 'private' | 'protected' | 'static' | 
		                  'synchronized' | 'final' 
		            		      
		FormalsPattern := '..' (',' FormalsPatternAfterDotDot)* |
		                  OptionalParensTypePattern (',' FormalsPattern)* |
		                  TypePattern '...'
		                  
		FormalsPatternAfterDotDot := 
		        OptionalParensTypePattern (',' FormalsPatternAfterDotDot)* |
		        TypePattern '...'
		                                               		                  
		ThrowsPattern := 'throws' TypePatternList
		
		TypePatternList := TypePattern (',' TypePattern)*
		            					            
	

Note: compared to the previous version, this definition of MethodPattern does not allow parameter annotation matching (only matching on annotations of parameter types).

A ConstructorPattern has the form

  	
  		ConstructorPattern := 
  		    AnnotationPattern? ConstructorModifiersPattern?  
  		                       (TypePattern DotOrDotDot)? 'new' '(' FormalsPattern ')'
  		                       ThrowsPattern?
	
		ConstructorModifiersPattern := '!'? ConstructorModifier ConstructorModifiersPattern*
		
		ConstructorModifier := 'public' | 'private' | 'protected'
		
	

The optional AnnotationPattern at the beginning of a method or constructor pattern restricts matches to methods/constructors with annotations that match the pattern. For example:

AspectJ 5 supports a set of "@" pointcut designators which can be used both to match based on the presence of an annotation at runtime, and to expose the annotation value as context in a pointcut or advice definition. These designators are @args, @this, @target, @within, @withincode, and @annotation

It is a compilation error to attempt to match on an annotation type that does not have runtime retention using @this, @target or @args. It is a compilation error to attempt to use any of these designators to expose an annotation value that does not have runtime retention.

The this(), target(), and args() pointcut designators allow matching based on the runtime type of an object, as opposed to the statically declared type. In AspectJ 5, these designators are supplemented with three new designators : @this() (read, "this annotation"), @target(), and @args().

Like their counterparts, these pointcut designators can be used both for join point matching, and to expose context. The format of these new designators is:

  	
  	    AtThis := '@this' '(' AnnotationOrIdentifer ')'
    
  	    AtTarget := '@target' '(' AnnotationOrIdentifier ')'
  	
  	    AnnotationOrIdentifier := '@' FullyQualifiedName | Identifier
        
  	    AtArgs := '@args' '(' AnnotationsOrIdentifiersPattern ')'
        
  	    AnnotationsOrIdentifiersPattern :=
  	                      '..' (',' AnnotationsOrIdentifiersPatternAfterDotDot)? |
  	                      AnnotationOrIdentifier (',' AnnotationsOrIdentifiersPattern)* |
  	                      '*' (',' AnnotationsOrIdentifiersPattern)*
		                  
  	    AnnotationsOrIdentifiersPatternAfterDotDot := 
		                  AnnotationOrIdentifier (',' AnnotationsOrIdentifiersPatternAfterDotDot)* |
		                  '*' (',' AnnotationsOrIdentifiersPatternAfterDotDot)*
  	
	

The forms of @this() and @target() that take a single annotation name are analogous to their counterparts that take a single type name. They match at join points where the object bound to this (or target, respectively) has an annotation of the specified type. For example:

Annotations can be exposed as context in the body of advice by using the forms of @this(), @target() and @args() that use bound variables in the place of annotation names. For example:

  	pointcut callToClassifiedObject(Classified classificationInfo) :
  	    call(* *(..)) && @target(classificationInfo);

  	pointcut txRequiredMethod(Tx transactionAnnotation) :
  	    execution(* *(..)) && @this(transactionAnnotation) 
  	    && if(transactionAnnotation.policy == Tx.Policy.REQUIRED);
	

The @args pointcut designator behaves as its args counterpart, matching join points based on number and position of arguments, and supporting the * wildcard and at most one .. wildcard. An annotation at a given position in an @args expression indicates that the runtime type of the argument in that position at a join point must have an annotation of the indicated type. For example:

  	/**
  	 * matches any join point with at least one argument, and where the
  	 * type of the first argument has the @Classified annotation
  	 */
  	pointcut classifiedArgument() : @args(@Classified,..);
  	
  	/**
  	 * matches any join point with three arguments, where the third
  	 * argument has an annotation of type @Untrusted.
  	 */
  	pointcut untrustedData(Untrusted untrustedDataSource) : 
  	    @args(*,*,untrustedDataSource);
	

Note: an alternative design would be to allow both annotation patterns and type patterns to be specified in the existing args pcd. This works well for matching, but is more awkward when it comes to exposing context.

Access to AnnotatedElement information is available reflectively with the body of advice through the thisJoinPoint, thisJoinPointStaticPart, and thisEnclosingJoinPointStaticPart variables. To access annotations on the arguments, or object bound to this or target at a join point you can use the following code fragments:

  	Annotation[] thisAnnotations = thisJoinPoint.getThis().getClass().getAnnotations();
  	Annotation[] targetAnnotations = thisJoinPoint.getTarget().getClass().getAnnotations();
  	Annotation[] firstParamAnnotations = thisJoinPoint.getArgs()[0].getClass().getAnnotations();
	

Note: it would be nicer to provide direct helper methods in the JoinPoint interface or a sub-interface that provide the annotations directly, something like "AnnotatedElement getThisAnnotationInfo()". The problem here is that the "AnnotatedElement" type is only in the Java 5 runtime libraries, and we don't want to tie the AspectJ runtime library to Java 5. A sub-interface and downcast solution could be used if these helpers were felt to be sufficiently important.

The @within and @withincode pointcut designators match any join point where the executing code is defined within a type (@within), or a method/constructor (@withincode) that has an annotation of the specified type. The form of these designators is:

  	
        AtWithin := '@within' '(' AnnotationOrIdentifier ')'
        AtWithinCode := '@withincode' '(' AnnotationOrIdentifier ')'        
    

Some examples of using these designators follow:

The @annotation pointcut designator matches any join point where the subject of the join point has an annotation of the given type. Like the other @pcds, it can also be used for context exposure.

  	
        AtAnnotation := '@annotation' '(' AnnotationOrIdentifier ')'
    

The subject of a join point is defined in the table in chapter one of this guide.

Access to annotation information on members at a matched join point is also available through the getSignature method of the JoinPoint and JoinPoint.StaticPart interfaces. The MemberSignature interface is extended with the additional operation java.lang.reflect.AccessibleObject getAccessibleObject(). The following fragment illustrates an example use of this interface to access annotation information.

  	Signature sig = thisJoinPointStaticPart.getSignature();
  	AnnotatedElement declaringTypeAnnotationInfo = sig.getDeclaringType();
  	if (sig instanceof MemberSignature) {
  	  // this must be an initialization, pre-initialization, call, execution, get, or
  	  // set join point.
  	  AnnotatedElement memberAnnotationInfo = ((MemberSignature)sig).getAccessibleObject();
  	}
	

Note again that it would be nicer to add the method getAnnotationInfo directly to MemberSignature, but this would once more couple the runtime library to Java 5.

The @this,@target and @args pointcut designators can only be used to match against annotations that have runtime retention. The @within, @withincode and @annotation pointcut designators can only be used to match against annotations that have at least class-file retention, and if used in the binding form the annotation must have runtime retention.

Note: A previous design allowed package annotation patterns to be specified directly in type patterns, and parameter annotation patterns to be specified directly in method and constructor signature patterns. Because this made some pointcut expressions hard to read and understand, we moved in favour of the design presented below, which also has its drawbacks. Matching on package and parameter annotations will be deferred until after the 1.5.0 release so that we can gain more understanding of the kinds of uses AspectJ users are making of annotations in pointcut expressions before commiting to any one approach.

According to the Java 5 specification, non-type annotations are not inherited, and annotations on types are only inherited if they have the @Inherited meta-annotation. Given the following program:

  	class C1 {
  	  @SomeAnnotation
  	  public void aMethod() {...}
  	}
  	
  	class C2 extends C1 {
  	  public void aMethod() {...}
  	}
  	
  	class Main {
  	  public static void main(String[] args) {
  	    C1 c1 = new C1();
  	    C2 c2 = new C2();
  	    c1.aMethod();
  	    c2.aMethod();
  	  }
  	}
  	
  	aspect X {
  	
  	  pointcut annotatedMethodCall() : 
  	    call(@SomeAnnotation * C1.aMethod());
  	
  	  pointcut c1MethodCall() :
  	    call(* C1.aMethod());
  	}
	

The pointcut annotatedMethodCall will match the call to c1.aMethod(), but not the call to c2.aMethod().

The pointcut c1MethodCall matches both c1.aMethod() and c2.aMethod().

It would be useful to be able to match join points based on annotation values, rather than merely the presence of a class-file retention annotation of a given type. This facility may be supported in a future version of AspectJ, by expanding the definition of AnnotationPattern. Matching annotation values for annotations with runtime retention can be done by exposing the annotation value as a pointcut parameter and then using an if pointcut expression to test the value.

Since pointcut expressions in AspectJ 5 support join point matching based on annotations, this facility can be exploited when writing declare warning and declare error statements. For example:

  	declare warning : withincode(@PerformanceCritical * *(..)) &&
  	                  call(@ExpensiveOperation * *(..))
  	                : "Expensive operation called from within performance critical section";
	

  	declare error : call(* org.xyz.model.*.*(..)) &&
  	                !@within(@Trusted *)
  	                : "Untrusted code should not call the model classes directly";
	

The general form of a declare parents statement is:

  	declare parents : TypePattern extends Type;
  	declare parents : TypePattern implements TypeList;
	

Since AspectJ 5 supports annotations as part of a type pattern specification, it is now possible to match types based on the presence of annotations with either class-file or runtime retention. For example:

An annotation type may not be used as the target of a declare parents statement. If an annotation type is named explicitly as the target of a declare parents statement, a compilation error will result. If an annotation type is matched by a non-explicit type pattern used in a declare parents statement it will be ignored (and an XLint warning issued).

The general form of a declare precedence statement is:

  	declare precedence : TypePatList;
	

AspectJ 5 allows the type patterns in the list to include annotation information as part of the pattern specification. For example:

A varargs method may be called with zero or more arguments in the variable argument position. For example, given the definition of foo above, the following calls are all legal:

    	foo(5);
    	foo(5,"One String");
    	foo(7,"One String","Two Strings");
    	foo(3,"One String","Two Strings","Three Strings");	
    	

A varargs parameter is treated as an array within the defining member. So in the body of foo we could write for example:

    	public void foo(int i, String... strings) {
    	  String[] someStrings = strings;
    	  // rest of method body
    	}
    	

One consequence of this treatment of a varargs parameter as an array is that you can also call a varargs method with an array:

    	foo(7,new String[] {"One String","Two Strings"});
    	

Recall from the definition of signature patterns given in the chapter on annotations (Signature Patterns), that MethodPattern and ConstructorPattern are extended to allow a varargs pattern in the last argument position of a method or constructor signature.

  	
 		FormalsPattern := '..' (',' FormalsPatternAfterDotDot)? |
		                  OptionalParensTypePattern (',' FormalsPattern)* |
		                  TypePattern '...'
		                  
		FormalsPatternAfterDotDot := 
		        OptionalParensTypePattern (',' FormalsPatternAfterDotDot)* |
		        TypePattern '...'

    	

Method and constructor patterns are used in the call, execution, initialization, preinitialization, and withincode pointcut designators. Some examples of usage follow:

A variable argument parameter and an array parameter are treated as distinct signature elements, so given the method definitions:

    	void foo(String...);
    	void bar(String[]);
    	

The pointcut execution(* *.*(String...)) matches the execution join point for foo, but not bar. The pointcut execution(* *.*(String[])) matches the execution join point for bar but not foo.

When a varargs parameter is used within the body of a method, it has an array type, as discussed in the introduction to this section. We follow the same convention when binding a varargs parameter via the args pointcut designator. Given a method

		public void foo(int i, String... strings) { 
		}
		

The call or execution join points for foo will be matched by the pointcut args(int,String[]). It is not permitted to use the varargs syntax within an args pointcut designator - so you cannot write args(int,String...).

Binding of a varargs parameter in an advice statement is straightforward:

		before(int i, String[] ss) : call(* foo(int,String...)) && args(i,ss) {
		  // varargs String... argument is accessible in advice body through ss
		  // ...
		}
		

Since you cannot use the varargs syntax in the args pointcut designator, you also cannot use the varargs syntax to declare advice parameters.

Note: the proposal in this section does not allow you to distinguish between a join point with a signature (int, String...) and a join point with a signature (int, String[]) based solely on the use of the args pointcut designator. If this distinction is required, args can always be coupled with call or execution.

Pointcuts are specified using the org.aspectj.lang.annotation.Pointcut annotation on a method declaration. The method should have a void return type. The parameters of the method correspond to the parameters of the pointcut. The modifiers of the method correspond to the modifiers of the pointcut. The method body should be empty and there should be no throws clause.

A simple example:

     
     @Pointcut("call(* *.*(..))")
     void anyCall() {}
     
     is equivalent to...
     
     pointcut anyCall() : call(* *.*(..));
      

An example with modifiers:

     @Pointcut("")
     protected abstract void anyCall();
     
     is equivalent to...
     
     protected abstract pointcut anyCall();
      

Using the code style, types referenced in pointcut expressions are resolved with respect to the imported types in the compilation unit. When using the annotation style, types referenced in pointcut expressions are resolved in the absence of any imports and so have to be fully qualified if they are not by default visible to the declaring type (outside of the declaring package and java.lang). This to not apply to type patterns with wildcards, which are always resolved in a global scope.

Consider the following compilation unit:

     package org.aspectprogrammer.examples;
     
     import java.util.List;
     
     public aspect Foo {
     
       pointcut listOperation() : call(* List.*(..));
      
       pointcut anyUtilityCall() : call(* java.util..*(..));
           
     }
      

Using the annotation style this would be written as:

     package org.aspectprogrammer.examples;
     
     import java.util.List; // redundant but harmless
     
     @Aspect
     public class Foo {
     
       @Pointcut("call(* java.util.List.*(..))") // must qualify
       void listOperation() {}
      
       @Pointcut("call(* java.util..*(..))")
       void anyUtilityCall() {}
           
     }
      

The value attribute of the Pointcut declaration may contain any valid AspectJ pointcut declaration.

In this section we first discuss the use of annotations for simple advice declarations. Then we show how thisJoinPoint and its siblings are handled in the body of advice and discuss the treatment of proceed in around advice.

Using the annotation style, an advice declaration is written as a regular Java method with one of the Before, After, AfterReturning, AfterThrowing, or Around annotations. Except in the case of around advice, the method should return void. The method should be declared public.

A method that has an advice annotation is treated exactly as an advice declaration by AspectJ's weaver. This includes the join points that arise when the advice is executed (an adviceexecution join point, not a method execution join point), and the restriction that advice cannot be invoked explicitly (the weaver will issue an error if an advice method is explicitly invoked).

The following example shows a simple before advice declaration in both styles:

     before() : call(* org.aspectprogrammer..*(..)) && this(Foo) {
       System.out.println("Call from Foo");
     }
     
     is equivalent to...
     
     @Before("call(* org.aspectprogrammer..*(..)) && this(Foo)")
     public void callFromFoo() {
       System.out.println("Call from Foo");
     }
      

Notice one slight difference between the two advice declarations: in the annotation style, the advice has a name, "callFromFoo". Even though advice cannot be invoked explicitly, this name is useful in join point matching when advising advice execution. For this reason, and to preserve exact semantic equivalence between the two styles, we also support the org.aspectj.lang.annotation.AdviceName annotation. The exact equivalent declarations are:

     @AdviceName("callFromFoo")
     before() : call(* org.aspectprogrammer..*(..)) && this(Foo) {
       System.out.println("Call from Foo");
     }
     
     is equivalent to...
     
     @Before("call(* org.aspectprogrammer..*(..)) && this(Foo)")
     public void callFromFoo() {
       System.out.println("Call from Foo");
     }
      

If the advice body needs to know which particular Foo was doing the calling, just add a parameter to the advice declaration.

     @AdviceName("callFromFoo")
     before(Foo foo) : call(* org.aspectprogrammer..*(..)) && this(foo) {
       System.out.println("Call from Foo: " + foo);
     }
     
     is equivalent to...
     
     @Before("call(* org.aspectprogrammer..*(..)) && this(foo)")
     public void callFromFoo(Foo foo) {
       System.out.println("Call from Foo: " + foo);
     }
      

If the advice body needs access to thisJoinPoint, thisJoinPointStaticPart, thisEnclosingJoinPointStaticPart then these need to be declared as additional method parameters when using the annotation style. In AspectJ 1.5.0 we require that these parameters be declared first in the parameter list, in later releases we may relax this requirement.

     @AdviceName("callFromFoo")
     before(Foo foo) : call(* org.aspectprogrammer..*(..)) && this(foo) {
       System.out.println("Call from Foo: " + foo + " at " 
                          + thisJoinPoint);
     }
     
     is equivalent to...
     
     @Before("call(* org.aspectprogrammer..*(..)) && this(foo)")
     public void callFromFoo(JoinPoint thisJoinPoint, Foo foo) {
       System.out.println("Call from Foo: " + foo + " at " 
                          + thisJoinPoint);
     }
      

Advice that needs all three variables would be declared:

     @Before("call(* org.aspectprogrammer..*(..)) && this(Foo)")
     public void callFromFoo(JoinPoint thisJoinPoint, 
                             JoinPoint.StaticPart thisJoinPointStaticPart,
                             JoinPoint.EnclosingStaticPart thisEnclosingJoinPointStaticPart) {
         // ...                             
     }
      

JoinPoint.EnclosingStaticPart is a new (empty) sub-interface of JoinPoint.StaticPart which allows the AspectJ weaver to distinguish based on type which of thisJoinPointStaticPart and thisEnclosingJoinPointStaticPart should be passed in a given parameter position.

After advice declarations take exactly the same form as Before, as do the forms of AfterReturning and AfterThrowing that do not expose the return type or thrown exception respectively.

To expose a return value with after returning advice simply declare the returning parameter as a parameter in the method body and bind it with the "returning" attribute:

      
      after() returning : criticalOperation() {
        System.out.println("phew");
      }
      
      after() returning(Foo f) : call(Foo+.new(..)) {
        System.out.println("It's a Foo: " + f);
      }
      
      can be written as...
      
      @AfterReturning("criticalOperation()")
      public void phew() {
        System.out.println("phew");
      }
      
      @AfterReturning(value="call(Foo+.new(..))",returning="f")
      public void itsAFoo(Foo f) {
        System.out.println("It's a Foo: " + f);
      }            
      

(Note the need for the "value=" prefix in front of the pointcut expression in the returning case).

After throwing advice works in a similar fashion, using the throwing attribute when needing to expose a thrown exception.

For around advice, we have to tackle the problem of proceed. One of the design goals for the annotation style is that a large class of AspectJ applications should be compilable with a standard Java 5 compiler. A straight call to proceed inside a method body:

     @Around("call(* org.aspectprogrammer..*(..))")
     public Object doNothing() {
       return proceed(); // CE on this line                            
     }
      

will result in a "No such method" compilation error. For this reason AspectJ 5 defines a new sub-interface of JoinPoint, ProceedingJoinPoint.

     public interface ProceedingJoinPoint extends JoinPoint {
       public Object proceed(Object... args);
     }
      

The around advice given above can now be written as:

     @Around("call(* org.aspectprogrammer..*(..))")
     public Object doNothing(ProceedingJoinPoint thisJoinPoint) {
       return thisJoinPoint.proceed();                             
     }
      

Here's an example that uses parameters for the proceed call:

     public aspect ProceedAspect {
       pointcut setAge(int i): call(* setAge(..)) && args(i);
    
       Object around(int i): setAge(i) {
         return proceed(i*2);
       }
     }
     
     can be written as...
     
     @Aspect
     public class ProceedAspect {
     
       @Pointcut("call(* setAge(..)) && args(i)")
       void setAge(int i) {}
     
       @Around("setAge(i)")
       public Object twiceAsOld(ProceedingJoinPoint thisJoinPoint, int i) {
         return thisJoinPoint.proceed(i*2);
       }
     
     }          
      

Binding of formals (cannot bind same formal more than once in a conjunction, can bind exactly once in each branch of a disjunction, iff the branches are mutually exclusive based on e.g. join point kind).

Discuss detection of common errors -> warning/error, eg. conjunction of more than one kind of join point. Differing numbers of args in method signature / args / @args / @parameters.

By default a class file that has been woven by the AspectJ compiler cannot subsequently be rewoven (passed as input to the weaver). If you are developing AspectJ applications that are to be used in a load-time weaving environment, you need to specify the -Xreweavable compiler option when building them. This causes AspectJ to save additional state in the class files that is used to support subsequent reweaving.

AspectJ 5 supports three different ways of enabling load-time weaving for an application: agents, a command-line launch script, and a set of interfaces for integration of AspectJ load-time weaving in custom environments.

The weaver is configured using one or more META-INF/aop.xml files located on the class loader search path. Each file may define a list of concrete aspects to be used for weaving, type patterns describing which types should woven, and a set of options to be passed to the weaver. In addition AspectJ 5 supports the definition of concrete aspects in XML. Aspects defined in this way must extend an abstract aspect visible to the weaver. The abstract aspect may define abstract pointcuts (but not abstract methods). The following example shows a simple aop.xml file:

          <aspectj>
          
            <aspects>
              <!-- declare two existing aspects to the weaver -->
              <aspect name="com.MyAspect"/>
              <aspect name="com.MyAspect.Inner"/>

              <!-- define a concrete aspect inline -->
              <concrete-aspect name="com.xyz.tracing.MyTracing" extends="tracing.AbstractTracing">
                <pointcut name="tracingScope" expression="within(org.maw.*)"/>
              </concrete-aspect>
		  	  
              <!-- Of the set of aspects known to the weaver, use aspects matching
                   the type pattern "com..*" for weaving. -->
              <include within="com..*"/>
			  
              <!-- Do not use any aspects with the @CoolAspect annotation for weaving -->
              <exclude within="@CoolAspect *"/>    	
			  
            </aspects>

            <weaver options="-verbose -XlazyTjp">
              <!-- Weave types that are within the javax.* or org.aspectj.*
                   packages. Also weave all types in the foo package that do
                   not have the @NoWeave annotation. -->
              <include within="javax.*"/>
              <include within="org.aspectj.*"/>
              <include within="(!@NoWeave foo.*) AND foo.*"/>
            </weaver>
          
          </aspectj>
          
		  

An aop.xml file contains two key sections: "aspects" defines one or more aspects to the weaver and controls which aspects are to be used in the weaving process; "weaver" defines weaver options and which types should be woven.

The simplest way to define an aspect to the weaver is to specify the fully-qualified name of the aspect type in an aspect element. You can also declare (and define to the weaver) aspects inline in the aop.xml file. This is done using the "concrete-aspect" element. A concrete-aspect declaration must provide a pointcut definition for every abstract pointcut in the abstract aspect it extends. This mechanism is a useful way of externalizing configuration for infrastructure and auxiliary aspects where the pointcut definitions themselves can be considered part of the configuration of the service.

The aspects element may optionally contain one or more include and exclude elements (by default, all defined aspects are used for weaving). Specifying include or exclude elements restricts the set of defined aspects to be used for weaving to those that are matched by an include pattern, but not by an exclude pattern. The 'within' attribute accepts a type pattern of the same form as a within pcd, except that && and || are replaced by 'AND' and 'OR'.

The weaver element is used to pass options to the weaver and to specify the set of types that should be woven. If no include elements are specified then all types seen by the weaver will be woven.

When several configuration files are visible from a given weaving class loader their contents are conceptually merged (this applies to both aop.xml files and to aop.properties files as described in the next section). The files are merged in the order they are found on the search path (regular getResourceAsStream lookup) according to the following rules:

It is not an error for the same aspect to be defined to the weaver in more than one visible META-INF/aop.xml file. However, if a declarative concrete aspect is declared in more than aop.xml file then an error will be issued. A concrete aspect defined in this way will be used to weave types loaded by the class loader that loaded the aop.xml file in which it was defined.

A META-INF/aop.xml file will automatically be generated when using the -outjar option of the AspectJ compiler. It will simply contain a (possibly empty) set of aspect elements, one for each concrete aspect included in the JAR.

For memory constrained environments or those without support for XML a simple Java Properties file can be used to configure LTW. Just like XML files, META-INF/aop.properties files are loaded from the class loader search path. Everything that can be configured through XML can be configured using a Properties file, with the exception of declarative concrete aspects. For example:

          aspects.names=com.MyAspect,com.MyAspect.Inner
          aspects.include=com..*
          aspects.exclude=@CoolAspect

          weaver.options=-verbose -XlazyTjp
          weaver.include=javax.* OR org.aspectj.*
		  

The table below lists the AspectJ options supported by LTW. All other options will be ignored and a warning issued.

When using JDK 1.5 the JVMTI agent can be used by starting the JVM with the following option:

			-javaagent=aspectjweaver.jar          
		  

The JRockit agent is configured with the following JVM option:

			-Xmanagement:class=org.aspectj.weaver.tools.JRockitWeavingAgent