The AspectJ^TM 5 Development Kit Developer's Notebook

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 m 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.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:

AspectJ 1.5 extends type patterns to allow an optional AnnotationPattern prefix.

  	  	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 within or handler pointcut expression), the parenthesis are optional:

        OptionalParensTypePattern := AnnotationPattern? TypePattern
      

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

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() == TxPolicy.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);
	

In addition to accessing annotation information at runtime through context binding, access to AnnotatedElement information is also 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();
	

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 Signature interfaces are extended with additional operations that provide access to the java.lang.reflect Method, Field and Constructor objects on which annnotations can be queried. 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 MethodSignature) {
  	  // this must be a call or execution join point
  	  Method method = ((MethodSignature)sig).getMethod();
  	}
	

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.

Matching on package annotations is not supported in AspectJ. Support for this capability may be considered in a future release.

Parameter annotation matching is being added in AspectJ1.6. Initially only matching is supported but binding will be implemented at some point. Whether the annotation specified in a pointcut should be considered to be an annotation on the parameter type or an annotation on the parameter itself is determined through the use of parentheses around the parameter type. Consider the following:

    @SomeAnnotation
    class AnnotatedType {}

    class C {
      public void foo(AnnotatedType a) {}
      public void goo(@SomeAnnotation String s) {}
    }
    
	

The method foo has a parameter of an annotated type, and can be matched by this pointcut:

    pointcut p(): execution(* *(@SomeAnnotation *));
	

When there is a single annotation specified like this, it is considered to be part of the type pattern in the match against the parameter: 'a parameter of any type that has the annotation @SomeAnnotation'.

To match the parameter annotation case, the method goo, this is the pointcut:

    pointcut p(): execution(* *(@SomeAnnotation (*)));
	

The use of parentheses around the wildcard is effectively indicating that the annotation should be considered separately to the type pattern for the parameter type: 'a parameter of any type that has a parameter annotation of @SomeAnnotation'.

To match when there is a parameter annotation and an annotation on the type as well:

      pointcut p(): execution(* *(@SomeAnnotation (@SomeOtherAnnotation *)));
	

The parentheses are grouping @SomeOtherAnnotation with the * to form the type pattern for the parameter, then the type @SomeAnnotation will be treated as a parameter annotation pattern.

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 annotatedC2MethodCall() : 
  	    call(@SomeAnnotation * C2.aMethod());
  	
  	  pointcut annotatedMethodCall() :
  	    call(@SomeAnnotation * aMethod());
  	}
	

The pointcut annotatedC2MethodCall will not match anything since the definition of aMethod in C2 does not have the annotation.

The pointcut annotatedMethodCall matches c1.aMethod() but not c2.aMethod(). The call to c2.aMethod is not matched because join point matching for modifiers (the visibility modifiers, annotations, and throws clause) is based on the subject of the join point (the method actually being called).

The if pointcut designator can be used to write pointcuts that match based on the values annotation members. For example:

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

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 generic type is declared with one or more type parameters following the type name. By convention formal type parameters are named using a single letter, though this is not required. A simple generic list type (that can contain elements of any type E) could be declared:

		interface List<E> {
		   Iterator<E> iterator();
		   void add(E anItem);
		   E remove(E anItem);  
		}
		

It is important to understand that unlike template mechanisms there will only be one type, and one class file, corresponding to the List interface, regardless of how many different instantiations of the List interface a program has (each potentially providing a different value for the type parameter E). A consequence of this is that you cannot refer to the type parameters of a type declaration in a static method or initializer, or in the declaration or initializer of a static variable.

A parameterized type is an invocation of a generic type with concrete values supplied for all of its type parameters (for example, List<String> or List<Food>).

A generic type may be declared with multiple type parameters. In addition to simple type parameter names, type parameter declarations can also constrain the set of types allowed by using the extends keyword. Some examples follow:

You declare a variable (or a method/constructor argument) of a parameterized type by specifying a concrete type specfication for each type parameter in the generic type. The following example declares a list of strings and a list of numbers:

        List<String> strings;
        List<Number> numbers;
		

It is also possible to declare a variable of a generic type without specifying any values for the type parameters (a raw type). For example, List strings. In this case, unchecked warnings may be issued by the compiler when the referenced object is passed as a parameter to a method expecting a parameterized type such as a List<String>. New code written in the Java 5 language would not be expected to use raw types.

Parameterized types are instantiated by specifying type parameter values in the constructor call expression as in the following examples:

        List<String> strings = new MyListImpl<String>();
        List<Number> numbers = new MyListImpl<Number>();
		

When declaring parameterized types, the ? wildcard may be used, which stands for "some type". The extends and super keywords may be used in conjunction with the wildcard to provide upper and lower bounds on the types that may satisfy the type constraints. For example:

A generic type may be extended as any other type. Given a generic type Foo<T> then a subtype Goo may be declared in one of the following ways:

A generic type may implement one or more generic interfaces, following the type binding rules given above. A type may also implement one or more parameterized interfaces (for example, class X implements List<String>, however a type may not at the same time be a subtype of two interface types which are different parameterizations of the same interface.

The supertype of a generic type C is the type given in the extends clause of C, or Object if no extends clause is present. Given the type declaration

        public interface List<E> extends Collection<E> {... }
		

then the supertype of List<E> is Collection<E>.

The supertype of a parameterized type P is the type given in the extends clause of P, or Object if no extends clause is present. Any type parameters in the supertype are substituted in accordance with the parameterization of P. An example will make this much clearer: Given the type List<Double> and the definition of the List given above, the direct supertype is Collection<Double>. List<Double> is not considered to be a subtype of List<Number>.

An instance of a parameterized type P<T1,T2,...Tn>may be assigned to a variable of the same type or a supertype without casting. In addition it may be assigned to a variable R<S1,S2,...Sm> where R is a supertype of P (the supertype relationship is reflexive), m <= n, and for all type parameters S1..m, Tm equals Sm or Sm is a wildcard type specification and Tm falls within the bounds of the wildcard. For example, List<String> can be assigned to a variable of type Collection<?>, and List<Double> can be assigned to a variable of type List<? extends Number>.

A static method may be declared with one or more type parameters as in the following declaration:

          static <T> T first(List<T> ts) { ... }
		

Such a definition can appear in any type, the type parameter T does not need to be declared as a type parameter of the enclosing type.

Non-static methods may also be declared with one or more type parameters in a similar fashion:

          <T extends Number> T max(T t1, T t2) { ... }
		

The same technique can be used to declare a generic constructor.

Generics in Java are implemented using a technique called erasure. All type parameter information is erased from the run-time type system. Asking an object of a parameterized type for its class will return the class object for the raw type (eg. List for an object declared to be of type List<String>. A consequence of this is that you cannot at runtime ask if an object is an instanceof a parameterized type.

The simplest way to work with generic and parameterized types in pointcut expressions and type patterns is simply to use the raw type name. For example, the type pattern List will match the generic type List<E> and any parameterization of that type (List<String>, List<?>, List<? extends Number> and so on. This ensures that pointcuts written in existing code that is not generics-aware will continue to work as expected in AspectJ 5. It is also the recommended way to match against generic and parameterized types in AspectJ 5 unless you explicitly wish to narrow matches to certain parameterizations of a generic type.

Generic methods and constructors, and members defined in generic types, may use type variables as part of their signature. For example:

          public class Utils {
            
            /** static generic method */
            static <T> T first(List<T> ts) { ... }
            
            /** instance generic method */
            <T extends Number> T max(T t1, T t2) { ... }
                
          }
          
          public class G<T> {
           
             // field with parameterized type
             T myData;
             
             // method with parameterized return type
             public List<T> getAllDataItems() {...}
              
          }
		

AspectJ 5 does not allow the use of type variables in pointcut expressions and type patterns. Instead, members that use type parameters as part of their signature are matched by their erasure. Java 5 defines the rules for determing the erasure of a type as follows.

Let |T| represent the erasure of some type T. Then:

Applying these rules to the earlier examples, we find that the methods defined in Utils can be matched by a signature pattern matching static Object Utils.first(List) and Number Utils.max(Number, Number) respectively. The members of the generic type G can be matched by a signature pattern matching Object G.myData and public List G.getAllDataItems() respectively.

          public class Foo {
            
            List<String> myStrings;
            List<Float>  myFloats;
                
            public List<String> getStrings() { return myStrings; }
            public List<Float> getFloats() { return myFloats; }
                
            public void addStrings(List<String> evenMoreStrings) {
               myStrings.addAll(evenMoreStrings);   
            }
                
          }
		

          class G<T> {
  	
	        List<T> foo(List<String> ls) { return null; }
	
          }
		

          class C {

            public void foo(List<? extends Number> listOfSomeNumberType) {}
            
            public void bar(List<?> listOfSomeType) {}
            
            public void goo(List<Double> listOfDoubles) {}	
	
          }
		

          class Generic<T> {
	
        	public T foo(T someObject) {
	        	return someObject;
	        }
	
          }

          class SubGeneric<N extends Number> extends Generic<N> {
	
	        public N foo(N someNumber) {
		      return someNumber;
	        }
		
          }
		

	        public Object foo(Object arg) {
	          Number n = (Number) arg; // "bridge" to the signature defined in this type
		      return foo(n);
	        }
		

           SubGeneric rawType = new SubGeneric();
           rawType.foo("hi");  // call to bridge method (will result in a runtime failure in this case)
           Object n = new Integer(5);
           rawType.foo(n);     // call to bridge method that would succeed at runtime
		

         public class C {
           
           public void foo(List<String> listOfStrings) {}
               
           public void bar(List<Double> listOfDoubles) {}
               
           public void goo(List<? extends Number> listOfSomeNumberType) {}
         
         }
		

         public aspect A {

            before(List<Double> listOfDoubles) : execution(* C.*(..)) && args(listOfDoubles) {
               for (Double d : listOfDoubles) {
                  // do something
               }
            }           
         
         }
		

         import org.aspectj.lang.annotation.SuppressAjWarnings
         public aspect A {

            @SuppressAjWarnings   // will not see *any* lint warnings for this advice
            before(List<Double> listOfDoubles) : execution(* C.*(..)) && args(listOfDoubles) {
               for (Double d : listOfDoubles) {
                  // do something
               }
            }           
            
            @SuppressAjWarnings("uncheckedArgument")   // will not see *any* lint warnings for this advice
            before(List<Double> listOfDoubles) : execution(* C.*(..)) && args(listOfDoubles) {
               for (Double d : listOfDoubles) {
                  // do something
               }
            }       
         
         }
		

         public aspect A {

            before(List<Double> listOfDoubles) : execution(* C.*(List<Double>)) && args(listOfDoubles) {
               for (Double d : listOfDoubles) {
                  // do something
               }
            }           
         
         }
		

         public class C {
         
            public static void main(String[] args) {
               C c = new C();
               List<String> ls = new ArrayList<String>();
               List<Double> ld = new ArrayList<Double>();
               c.foo("hi");
               c.foo(ls);
               c.foo(ld);
            }
         
            public void foo(Object anObject) {}         
         }
         
         aspect A {
             before(List<? extends Number> aListOfSomeNumberType) 
               : call(* foo(..)) && args(aListOfSomeNumberType) {
                // process list... 
             }
         }
		

         aspect A {
             before(List<? extends Number> aListOfSomeNumberType) 
               : (call(* foo(List<Number+>)) || call(* foo(List<? extends Number+>))) 
                 && args(aListOfSomeNumberType) {
                 // process list... 
             }
         }
		

         public aspect A {

           pointcut executionOfAnyMethodReturningAList() : execution(List *(..));
           
           after() returning(List<?> listOfSomeType) : executionOfAnyMethodReturningAList() {
             for (Object element : listOfSomeType) {
                // process element...
             }
           }
         
         }
		

         public class C {
           
           public List<String> foo(List<String> listOfStrings) {...}
               
           public List<Double> bar(List<Double> listOfDoubles) {...}
               
           public List<? extends Number> goo(List<? extends Number> listOfSomeNumberType) {...}
         
         }
		

         public aspect Returning {
         
           after() returning(List<Double> listOfDoubles) : execution(* C.*(..)) {
              for(Double d : listOfDoubles) {
                 // process double...
              }   
           }
         
         }
		

         public class Generic<T> {
         
            /**
             * matches the execution of any implementation of a method defined for T
             */
            public pointcut foo() : execution(* T.*(..));
         
         }
		

         public aspect A {
         
           // runs before the execution of any implementation of a method defined for MyClass
           before() : Generic<MyClass>.foo() {
              // ...   
           }
           
           // runs before the execution of any implementation of a method defined for YourClass
           before() : Generic<YourClass>.foo() {
               // ...
           }
         
           // results in a compilation error - raw type reference
           before() : Generic.foo() { }
         
         }
		

AspectJ 5 supports the inter-type declaration of generic methods, and of members on generic types. For generic methods, the syntax is exactly as for a regular method declaration, with the addition of the target type specification:

A generic type may be the target of an inter-type declaration, used either in its raw form or with type parameters specified. If type parameters are specified, then the number of type parameters given must match the number of type parameters in the generic type declaration. Type parameter names do not have to match. For example, given the generic type Foo<T,S extends Number> then:

A parameterized type may not be the target of an inter-type declaration. This is because there is only one type (the generic type) regardless of how many different invocations (parameterizations) of that generic type are made in a program. Therefore it does not make sense to try and declare a member on behalf of (say) Bar<String>, you can only declare members on the generic type Bar<T>.

Both generic and parameterized types can be used as the parent type in a declare parents statement (as long as the resulting type hierarchy would be well-formed in accordance with Java's sub-typing rules). Generic types may also be used as the target type of a declare parents statement.

It is an error to use a generic or parameterized type as the softened exception type in a declare soft statement. Java 5 does not permit a generic class to be a direct or indirect subtype of Throwable (JLS 8.1.2).

AspectJ 5 allows an abstract aspect to be declared as a generic type. Any concrete aspect extending a generic abstract aspect must extend a parameterized version of the abstract aspect. Wildcards are not permitted in this parameterization.

Given the aspect declaration:

            public abstract aspect ParentChildRelationship<P,C> {
                ...
            }
		

then

The type parameter variables from a generic aspect declaration may be used in place of a type within any member of the aspect, except for within inter-type declarations. For example, we can declare a ParentChildRelationship aspect to manage the bi-directional relationship between parent and child nodes as follows:

          /** 
           * a generic aspect, we've used descriptive role names for the type variables
           * (Parent and Child) but you could use anything of course
           */
          public abstract aspect ParentChildRelationship<Parent,Child> {

            /** generic interface implemented by parents */   
            interface ParentHasChildren<C extends ChildHasParent>{
              List<C> getChildren();
              void addChild(C child);
              void removeChild(C child);
            }

            /** generic interface implemented by children */
            interface ChildHasParent<P extends ParentHasChildren>{
              P getParent();
              void setParent(P parent);
            }
          
            /** ensure the parent type implements ParentHasChildren<child type> */
            declare parents: Parent implements ParentHasChildren<Child>;
          
            /** ensure the child type implements ChildHasParent<parent type> */
            declare parents: Child implements ChildHasParent<Parent>;
          
            // Inter-type declarations made on the *generic* interface types to provide 
            // default implementations.
          
            /** list of children maintained by parent */
            private List<C> ParentHasChildren<C>.children = new ArrayList<C>();
          
            /** reference to parent maintained by child */        
            private P ChildHasParent<P>.parent;
          
            /** Default implementation of getChildren for the generic type ParentHasChildren */
            public List<C> ParentHasChildren<C>.getChildren() {
                  return Collections.unmodifiableList(children);  
            }
          
            /** Default implementation of getParent for the generic type ChildHasParent */    
            public P ChildHasParent<P>.getParent() {
                 return parent;
            }
          
            /** 
              * Default implementation of addChild, ensures that parent of child is
              * also updated.
              */ 
            public void ParentHasChildren<C>.addChild(C child) {
                 if (child.parent != null) {
                   child.parent.removeChild(child);
                 }
                 children.add(child);
                 child.parent = this;
              }
          
             /**
               * Default implementation of removeChild, ensures that parent of
               * child is also updated.
               */
             public void ParentHasChildren<C>.removeChild(C child) {
                 if (children.remove(child)) {
                   child.parent = null;
                 }
              }
          
              /**
                * Default implementation of setParent for the generic type ChildHasParent.
                * Ensures that this child is added to the children of the parent too.
                */
              public void ChildHasParent<P>.setParent(P parent) {
                 parent.addChild(this);
              }
          
              /**
                * Matches at an addChild join point for the parent type P and child type C
                */    
              public pointcut addingChild(Parent p, Child c) :
                execution(* ParentHasChildren.addChild(ChildHasParent)) && this(p) && args(c);
                
              /**
                * Matches at a removeChild join point for the parent type P and child type C
                */    
              public pointcut removingChild(Parent p, Child c) :
                execution(* ParentHasChildren.removeChild(ChildHasParent)) && this(p) && args(c);

          }
          
		

The example aspect captures the protocol for managing a bi-directional parent-child relationship between any two types playing the role of parent and child. In a compiler implementation managing an abstract syntax tree (AST) in which AST nodes may contain other AST nodes we could declare the concrete aspect:

            public aspect ASTNodeContainment extends ParentChildRelationship<ASTNode,ASTNode> {
                
                before(ASTNode parent, ASTNode child) : addingChild(parent, child) {
                  ...
                }
                
            }
		

As a result of this declaration, ASTNode gains members:

In a system managing orders, we could declare the concrete aspect:

            public aspect OrderItemsInOrders extends ParentChildRelationship<Order,OrderItem> {
                                
            }
		

As a result of this declaration, Order gains members:

and OrderItem gains members:

A second example of an abstract aspect, this time for handling exceptions in a uniform manner, is shown below:

       abstract aspect ExceptionHandling<T extends Throwable> {
	
	        /**
	         * method to be implemented by sub-aspects to handle thrown exceptions
	         */
        	protected abstract void onException(T anException);
        	
        	/**
        	 * to be defined by sub-aspects to specify the scope of exception handling
        	 */
        	protected abstract pointcut inExceptionHandlingScope();
        	
        	/**
        	 * soften T within the scope of the aspect
        	 */
        	declare soft: T : inExceptionHandlingScope();
        	
        	/**
        	 * bind an exception thrown in scope and pass it to the handler
        	 */
        	after() throwing (T anException) : inExceptionHandlingScope() {
        		onException(anException);
        	}
        	
      }
      

Notice how the type variable T extends Throwable allows the components of the aspect to be designed to work together in a type-safe manner. The following concrete sub-aspect shows how the abstract aspect might be extended to handle IOExceptions.

        public aspect IOExceptionHandling extends ExceptionHandling<IOException>{
        	
        	protected pointcut inExceptionHandlingScope() :
        		call(* doIO*(..)) && within(org.xyz..*);
        	
        	/**
        	 * called whenever an IOException is thrown in scope.
        	 */
        	protected void onException(IOException ex) {
        		System.err.println("handled exception: " + ex.getMessage());
        		throw new MyDomainException(ex);
        	}
         }
      

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.

Privileged aspects are not supported by the annotation style.

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.

As a general rule, the @Pointcut annotated method must have an empty method body and must not have any throws clause. If formal are bound (using args(), target(), this(), @args(), @target(), @this(), @annotation()) in the pointcut, then they must appear in the method signature.

The if() pointcut is treated specially and is discussed in a later section.

Here is a simple example of a pointcut declaration in both code and @AspectJ styles:

     @Pointcut("call(* *.*(..))")
     void anyCall() {}
         

is equivalent to...

     pointcut anyCall() : call(* *.*(..));
             

When binding arguments, simply declare the arguments as normal in the annotated method:

     @Pointcut("call(* *.*(int)) && args(i) && target(callee)")
     void anyCall(int i, Foo callee) {}
         

is equivalent to...

     pointcut anyCall(int i, Foo callee) : call(* *.*(int)) && args(i) && target(callee);
             

An example with modifiers (Remember that Java 5 annotations are not inherited, so the @Pointcut annotation must be present on the extending aspect's pointcut declaration too):

     @Pointcut("")
     protected abstract void anyCall();
         

is equivalent to...

     protected abstract pointcut anyCall();
             

     package org.aspectprogrammer.examples;

     import java.util.List;

     public aspect Foo {

       pointcut listOperation() : call(* List.*(..));

       pointcut anyUtilityCall() : call(* java.util..*(..));

     }
             

     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() {}

     }
             

     @Pointcut("call(* *.*(int)) && args(i) && if()")
     public static boolean someCallWithIfTest(int i) {
        return i > 0;
     }
         

     pointcut someCallWithIfTest(int i) : call(* *.*(int)) && args(i) && if(i > 0);
             

     static int COUNT = 0;

     @Pointcut("call(* *.*(int)) && args(i) && if()")
     public static boolean someCallWithIfTest(int i, JoinPoint jp, JoinPoint.EnclosingStaticPart esjp) {
        // any legal Java expression...
        return i > 0
               && jp.getSignature().getName.startsWith("doo")
               && esjp.getSignature().getName().startsWith("test")
               && COUNT++ < 10;
     }

     @Before("someCallWithIfTest(anInt, jp, enc)") 
     public void beforeAdviceWithRuntimeTest(int anInt, JoinPoint jp, JoinPoint.EnclosingStaticPart enc) {
        //...
     }

     // Note that the following is NOT valid
     /*
     @Before("call(* *.*(int)) && args(i) && if()")
     public void advice(int i) {
        // so you were writing an advice or an if body ?
     }
     */
             

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

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

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

is equivalent to...

     before() : call(* org.aspectprogrammer..*(..)) && this(Foo) {
       System.out.println("Call from Foo");
     }
         

If the advice body needs to know which particular Foo instance is making the call, just add a parameter to the advice declaration.

     before(Foo foo) : call(* org.aspectprogrammer..*(..)) && this(foo) {
       System.out.println("Call from Foo: " + foo);
     }
             

can be written as:

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

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

is equivalent to...

     before(Foo foo) : call(* org.aspectprogrammer..*(..)) && this(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:

      @AfterReturning("criticalOperation()")
      public void phew() {
        System.out.println("phew");
      }

      @AfterReturning(pointcut="call(Foo+.new(..))",returning="f")
      public void itsAFoo(Foo f) {
        System.out.println("It's a Foo: " + f);
      }
            

is equivalent to...

      after() returning : criticalOperation() {
        System.out.println("phew");
      }

      after() returning(Foo f) : call(Foo+.new(..)) {
        System.out.println("It's a Foo: " + f);
      }
            

(Note the use of the "pointcut=" 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:

     @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(new Object[]{i*2}); //using Java 5 autoboxing
       }

     }

             

is equivalent to:

     public aspect ProceedAspect {
       pointcut setAge(int i): call(* setAge(..)) && args(i);

       Object around(int i): setAge(i) {
         return proceed(i*2);
       }
     }
            

Note that the ProceedingJoinPoint does not need to be passed to the proceed(..) arguments.

In code style, the proceed method has the same signature as the advice, any reordering of actual arguments to the joinpoint that is done in the advice signature must be respected. Annotation style is different. The proceed(..) call takes, in this order:

Since proceed(..) in this case takes an Object array, AspectJ cannot do as much compile time checking as it can for code style. If the rules above aren't obeyed then it will unfortunately manifest as a runtime error.

Consider the following aspect:

     public aspect MoodIndicator {

        public interface Moody {};

        private Mood Moody.mood = Mood.HAPPY;

        public Mood Moody.getMood() {
          return mood;
        }

        declare parents : org.xyz..* implements Moody;

        before(Moody m) : execution(* *.*(..)) && this(m) {
           System.out.println("I'm feeling " + m.getMood());
        }
     }
         

This declares an interface Moody , and then makes two inter-type declarations on the interface - a field that is private to the aspect, and a method that returns the mood. Within the body of the inter-type declared method getMoody , the type of this is Moody (the target type of the inter-type declaration).

Using the annotation style this aspect can be written:

     @Aspect
     public class MoodIndicator {

        // this interface can be outside of the aspect
        public interface Moody {
          Mood getMood();
        };

        // this implementation can be outside of the aspect
        public static class MoodyImpl implements Moody {
           private Mood mood = Mood.HAPPY;

           public Mood getMood() {
             return mood;
           }
        }

        // the field type must be the introduced interface. It can't be a class.
        @DeclareParents(value="org.xzy..*",defaultImpl=MoodyImpl.class)
        private Moody implementedInterface;

        @Before("execution(* *.*(..)) && this(m)")
        void feelingMoody(Moody m) {
           System.out.println("I'm feeling " + m.getMood());
        }
     }
         

This is very similar to the mixin mechanism supported by AspectWerkz. The effect of the @DeclareParents annotation is equivalent to a declare parents statement that all types matching the type pattern implement the given interface (in this case Moody). Each method declared in the interface is treated as an inter-type declaration. Note how this scheme operates within the constraints of Java type checking and ensures that this has access to the exact same set of members as in the code style example.

Note that it is illegal to use the @DeclareParents annotation on an aspect' field of a non-interface type. The interface type is the inter-type declaration contract that dictates which methods are declared on the target type.

     // this type will be affected by the inter-type declaration as the type pattern matches
     package org.xyz;
     public class MoodTest {

        public void test() {
            // see here the cast to the introduced interface (required)
            Mood mood = ((Moody)this).getMood();
            ...
        }
    }
         

The @DeclareParents annotation can also be used without specifying a defaultImpl value (for example, @DeclareParents("org.xyz..*")). This is equivalent to a declare parents ... implements clause, and does not make any inter-type declarations for default implementation of the interface methods.

Consider the following aspect:

     public aspect SerializableMarker {

        declare parents : org.xyz..* implements Serializable;
     }
         

Using the annotation style this aspect can be written:

     @Aspect
     public class SerializableMarker {

        @DeclareParents("org.xyz..*")
        Serializable implementedInterface;
     }
         

If the interface defines one or more operations, and these are not implemented by the target type, an error will be issued during weaving.

Consider the following aspect:

     public aspect MoodIndicator {

        public interface Moody {};

        private Mood Moody.mood = Mood.HAPPY;

        public Mood Moody.getMood() {
          return mood;
        }

        declare parents : org.xyz..* implements Moody;

        before(Moody m) : execution(* *.*(..)) && this(m) {
           System.out.println("I'm feeling " + m.getMood());
        }
     }
         

This declares an interface Moody, and then makes two inter-type declarations on the interface - a field that is private to the aspect, and a method that returns the mood. Within the body of the inter-type declared method getMoody, the type of this is Moody (the target type of the inter-type declaration).

Using the annotation style this aspect can be written:

     @Aspect
     public class MoodIndicator {

        // this interface can be outside of the aspect
        public interface Moody {
          Mood getMood();
        };

        // this implementation can be outside of the aspect
        public static class MoodyImpl implements Moody {
           private Mood mood = Mood.HAPPY;

           public Mood getMood() {
             return mood;
           }
        }

        // The DeclareMixin annotation is attached to a factory method that can return instances of the delegate
        // which offers an implementation of the mixin interface.  The interface that is mixed in is the
        // return type of the method.
        @DeclareMixin("org.xyz..*")
        public static Moody createMoodyImplementation() {
          return new MoodyImpl();
        }

        @Before("execution(* *.*(..)) && this(m)")
        void feelingMoody(Moody m) {
           System.out.println("I'm feeling " + m.getMood());
        }
     }
         

Basically, the @DeclareMixin annotation is attached to a factory method. The factory method specifies the interface to mixin as its return type, and calling the method should create an instance of a delegate that implements the interface. This is the interface which will be delegated to from any target matching the specified type pattern.

Exploiting this syntax requires the user to obey the rules of pure Java. So references to any targeted type as if it were affected by the Mixin must be made through a cast, like this:

     // this type will be affected by the inter-type declaration as the type pattern matches
     package org.xyz;
     public class MoodTest {

        public void test() {
            // see here the cast to the introduced interface (required)
            Mood mood = ((Moody)this).getMood();
            ...
        }
    }
         

Sometimes the delegate instance may want to perform differently depending upon the type/instance for which it is behaving as a delegate. To support this it is possible for the factory method to specify a parameter. If it does, then when the factory method is called the parameter will be the object instance for which a delegate should be created:

      
      @Aspect
      public class Foo {
      
        @DeclareMixin("org.xyz..*")
        public static SomeInterface createDelegate(Object instance) {
          return new SomeImplementation(instance);
        }
      }
         

It is also possible to make the factory method non-static - and in this case it can then exploit the local state in the surrounding aspect instance, but this is only supported for singleton aspects:

      
      @Aspect
      public class Foo {
        public int maxLimit=35;
        
        @DeclareMixin("org.xyz..*")
        public SomeInterface createDelegate(Object instance) {
          return new SomeImplementation(instance,maxLimit);
        }
      }
         

Although the interface type is usually determined purely from the return type of the factory method, it can be specified in the annotation if necessary. In this example the return type of the method extends multiple other interfaces and only a couple of them (I and J) should be mixed into any matching targets:

        // interfaces is an array of interface classes that should be mixed in
        @DeclareMixin(value="org.xyz..*",interfaces={I.class,J.class})
        public static InterfaceExtendingLotsOfInterfaces createMoodyImplementation() {
          return new MoodyImpl();
        }
         

There are clearly similarities between @DeclareMixin and @DeclareParents but @DeclareMixin is not pretending to offer more than a simple mixin strategy. The flexibility in being able to provide the factory method instead of requiring a no-arg constructor for the implementation also enables delegate instances to make decisions based upon the type for which they are the delegate.

Any annotations defined on the interface methods are also put upon the delegate forwarding methods created in the matched target type.