path: root/docs/adk15ProgGuideDB/generics.xml

<!--<!DOCTYPE chapter SYSTEM "file:/C:/Documents%20and%20Settings/colyer/My%20Documents/projects/aspectjdev/lib/docbook/docbook-dtd/docbookx.dtd">
-->
<chapter id="generics" xreflabel="Generics">

  <title>Generics</title>
  
  <sect1 id="generics-inJava5">
    <title>Generics in Java 5</title>

	<para>
		This section provides the essential information about generics in
		Java 5 needed to understand how generics are treated in AspectJ 5.
		For a full introduction to generics in Java, please see the
		documentation for the Java 5 SDK.
	</para>

	<sect2>
		<title>Declaring Generic Types</title>
		
        <para>
            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 <literal>E</literal>) could be declared:
        </para>
        
        <programlisting><![CDATA[
		interface List<E> {
		   Iterator<E> iterator();
		   void add(E anItem);
		   E remove(E anItem);  
		}
		]]></programlisting>
        		
        		
        <para>
            It is important to understand that unlike template mechanisms there will only be one type, and one class file, corresponding to 
            the <literal>List</literal> interface, regardless of how many different instantiations of the <literal>List</literal> interface a program
            has (each potentially providing a different value for the type parameter <literal>E</literal>). 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. 
        </para>    
         <para>
             A <emphasis>parameterized type</emphasis> 
            is an invocation of a generic type with concrete values supplied for
            all of its type parameters (for example, <literal>List&lt;String></literal> or <literal>List&lt;Food></literal>).
        </para>
        
        <para>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 <literal>extends</literal> 
        keyword. Some examples follow:</para>
        
        <variablelist>

        <varlistentry>
          <term>class Foo&lt;T> {...}</term>
          <listitem>
            <para>A class <literal>Foo</literal> with one type parameter, <literal>T</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>class Foo&lt;T,S> {...}</term>
          <listitem>
            <para>A class <literal>Foo</literal> with two type parameters, <literal>T</literal> and <literal>S</literal>.
            </para>
          </listitem>
        </varlistentry>
                
        <varlistentry>
          <term>class Foo&lt;T extends Number> {...}</term>
          <listitem>
            <para>A class <literal>Foo</literal> with one type parameter <literal>T</literal>, where <literal>T</literal> must be
            instantiated as the type <literal>Number</literal> or a subtype of <literal>Number</literal>.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term>class Foo&lt;T, S extends T> {...}</term>
          <listitem>
            <para>A class <literal>Foo</literal> with two type parameters, <literal>T</literal> and <literal>S</literal>. <literal>Foo</literal>
            must be instantiated with a type <literal>S</literal> that is a subtype of the type specified for parameter <literal>T</literal>.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term>class Foo&lt;T extends Number &amp; Comparable> {...}</term>
          <listitem>
            <para>A class <literal>Foo</literal> with one type parameter, <literal>T</literal>. <literal>Foo</literal>
            must be instantiated with a type that is a subtype of <literal>Number</literal> and that implements <literal>Comparable</literal>.
            </para>
          </listitem>
        </varlistentry>
                        
       </variablelist>
                
	</sect2>
	
	<sect2>
	    <title>Using Generic and Parameterized Types</title>
	    
	    <para>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:</para>
	        
        <programlisting><![CDATA[
        List<String> strings;
        List<Number> numbers;
		]]></programlisting>
	        
	    <para>It is also possible to declare a variable of a generic type without specifying any values for the type
	        parameters (a <emphasis>raw</emphasis> type). For example, <literal>List strings</literal>. 
	        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 
	        <literal>List&lt;String></literal>. New code written in the Java 5 language would not be expected to use
	        raw types.</para>
	        
	    <para>Parameterized types are instantiated by specifying type parameter values in the constructor call expression as in
	    the following examples:</para>    

        <programlisting><![CDATA[
        List<String> strings = new MyListImpl<String>();
        List<Number> numbers = new MyListImpl<Number>();
		]]></programlisting>

	    <para>
	     When declaring parameterized types, the <literal>?</literal> wildcard may be used, which stands for "some type".
	     The <literal>extends</literal> and <literal>super</literal> 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:
	    </para>    

        <variablelist>

        <varlistentry>
          <term>List&lt;?&gt;</term>
          <listitem>
            <para>A list containing elements of some type, the type of the elements in the list is unknown.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>List&lt;? extends Number&gt;</term>
          <listitem>
            <para>A list containing elements of some type that extends Number, the exact type of the elements in the list is unknown.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>List&lt;? super Double&gt;</term>
          <listitem>
            <para>A list containing elements of some type that is a super-type of Double, the exact type of the elements in the list is unknown.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>
      	        
      	<para>
      	  A generic type may be extended as any other type. Given a generic type <literal>Foo&lt;T&gt;</literal> then
      	  a subtype <literal>Goo</literal> may be declared in one of the following ways:      	
      	</para>        

        <variablelist>

        <varlistentry>
          <term>class Goo extends Foo</term>
          <listitem>
            <para>Here <literal>Foo</literal> is used as a raw type, and the appropriate warning messages will be
            issued by the compiler on attempting to invoke methods in <literal>Foo</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>class Goo&lt;E&gt; extends Foo</term>
          <listitem>
            <para><literal>Goo</literal> is a generic type, but the super-type <literal>Foo</literal> is used as a raw
            type and the appropriate warning messages will be
            issued by the compiler on attempting to invoke methods defined by <literal>Foo</literal>.            
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>class Goo&lt;E&gt; extends Foo&lt;E&gt;</term>
          <listitem>
            <para>This is the most usual form. <literal>Goo</literal> is a generic type with one parameter that extends
            the generic type <literal>Foo</literal> with that same parameter. So <literal>Goo&lt;String&lt;</literal> is 
            a subclass of <literal>Foo&lt;String&gt;</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>class Goo&lt;E,F&gt; extends Foo&lt;E&gt;</term>
          <listitem>
            <para><literal>Goo</literal> is a generic type with two parameters that extends
            the generic type <literal>Foo</literal> with the first type parameter of <literal>Goo</literal> being used
            to parameterize <literal>Foo</literal>. So <literal>Goo&lt;String,Integer&lt;</literal> is 
            a subclass of <literal>Foo&lt;String&gt;</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>class Goo extends Foo&lt;String&gt;</term>
          <listitem>
            <para><literal>Goo</literal> is a type that extends
            the parameterized type <literal>Foo&lt;String&gt;</literal>.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>
      	        
	    <para>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,
	    <literal>class X implements List&lt;String&gt;</literal>, however a type may not at the same time
	    be a subtype of two interface types which are different parameterizations of the same interface.</para>
	</sect2>
	
	<sect2>
	    <title>Subtypes, Supertypes, and Assignability</title>
	    
	    <para>
	      The supertype of a generic type <literal>C</literal> is the type given in the extends clause of
	      <literal>C</literal>, or <literal>Object</literal> if no extends clause is present. Given the type declaration
	    </para>

        <programlisting><![CDATA[
        public interface List<E> extends Collection<E> {... }
		]]></programlisting>
	    
	    <para>
	      then the supertype of <literal>List&lt;E&gt;</literal> is <literal>Collection&lt;E&gt;</literal>.
	    </para>
	    
	    <para>
	      The supertype of a parameterized type <literal>P</literal> is the type given in the extends clause of
	      <literal>P</literal>, or <literal>Object</literal> if no extends clause is present. Any type parameters in
	      the supertype are substituted in accordance with the parameterization of <literal>P</literal>. An example
	      will make this much clearer: Given the type <literal>List&lt;Double&gt;</literal> and the definition of
	      the <literal>List</literal> given above, the direct supertype is
	      <literal>Collection&lt;Double&gt;</literal>. <literal>List&lt;Double&gt;</literal> is <emphasis>not</emphasis>
	      considered to be a subtype of <literal>List&lt;Number&gt;</literal>.
	    </para>
	    
	    <para>
	      An instance of a parameterized type <literal>P&lt;T1,T2,...Tn&gt;</literal>may be assigned to a variable of 
	      the same type or a supertype
	      without casting. In addition it may be assigned to a variable <literal>R&lt;S1,S2,...Sm&gt;</literal> where
	      <literal>R</literal> is a supertype of <literal>P</literal> (the supertype relationship is reflexive), 
	      <literal>m &lt;= n</literal>, and for all type parameters <literal>S1..m</literal>, <literal>Tm</literal> equals
	      <literal>Sm</literal> <emphasis>or</emphasis> <literal>Sm</literal> is a wildcard type specification and 
	      <literal>Tm</literal> falls within the bounds of the wildcard. For example, <literal>List&lt;String&gt;</literal>
	      can be assigned to a variable of type <literal>Collection&lt;?&gt;</literal>, and <literal>List&lt;Double&gt;</literal>
	      can be assigned to a variable of type <literal>List&lt;? extends Number&gt;</literal>. 	      
	    </para>
	    
	</sect2>
	
	<sect2>
	    <title>Generic Methods and Constructors</title>
	    <para>
	      A static method may be declared with one or more type parameters as in the following declaration:
	    </para>

        <programlisting><![CDATA[
          static <T> T first(List<T> ts) { ... }
		]]></programlisting>
	    
	    <para>
	        Such a definition can appear in any type, the type parameter <literal>T</literal> does not need to
	        be declared as a type parameter of the enclosing type.
	    </para>
	    
	    <para>
	      Non-static methods may also be declared with one or more type parameters in a similar fashion:
	    </para>
	    
        <programlisting><![CDATA[
          <T extends Number> T max(T t1, T t2) { ... }
		]]></programlisting>
	    
	    <para>The same technique can be used to declare a generic constructor.</para>
	    	    
	</sect2>
	
	<sect2>
	  <title>Erasure</title>
	  <para>Generics in Java are implemented using a technique called <emphasis>erasure</emphasis>. 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. <literal>List</literal> for an object
	  declared to be of type <literal>List&lt;String&gt;</literal>. A consequence of this is that you cannot at
	  runtime ask if an object is an <literal>instanceof</literal> a parameterized type.</para>
	</sect2>
  </sect1>

<!-- ===================================================================== -->
	
  <sect1 id="generics-inAspectJ5">
      <title>Generics in AspectJ 5</title>
      
      <para>
        AspectJ 5 provides full support for all of the Java 5 language features, including generics. Any legal Java 5 program is a 
        legal AspectJ 5 progam. In addition, AspectJ 5 provides support for generic and parameterized types in pointcuts, inter-type
        declarations, and declare statements.  Parameterized types may freely be used within aspect members, and support is 
        also provided for generic <emphasis>abstract</emphasis> aspects.
      </para>
      
      <sect2>
       <title>Matching generic and parameterized types in type patterns</title>
      
      <para>
        The foundation of AspectJ's support for generic and parameterized types in aspect declarations is the extension of type
        pattern matching to allow matching against generic and parameterized types.
      </para>
      
      <para>
           The type pattern <literal>"Foo"</literal> matches all types named <literal>Foo</literal>, whether they
           be simple types, generic types, or parameterized types. So for example, <literal>Foo</literal>, 
           <literal>Foo&lt;T&gt;</literal>, and <literal>Foo&lt;String&gt;</literal>will all be matched. 
      </para>
      
      <para>
          AspectJ 5 also extends the specification of type patterns to allow explicit matching of generic and parameterized
          types by including one or more type parameter patterns inside angle braces (<literal>&lt; &gt;</literal>) immediately
          after the type pattern. For example, <literal>List&lt;String&gt;</literal>
      </para>
      
      	<programlisting><![CDATA[
  	  	TypePattern := SimpleTypePattern |
  	  	               '!' TypePattern |
  	  	               '(' AnnotationPattern? TypePattern ')'
  	  	               TypePattern '&&' TypePattern |
  	  	               TypePattern '||' TypePattern |
  	  	               TypePattern '<' TypeParameterPatternList '>'
  	  	               
  	  	TypeParameterPatternList ::= TypeParameterPattern (',' TypeParameterPattern)*
  	  	
  	  	TypeParameterPattern ::= TypePattern |
  	  	                                    '?' TypeBoundPattern?
  	  	                                    
  	  	TypeBoundPattern ::= 'extends' TypePattern AdditionalBoundPatternList? |
  	  	                               'super' TypePattern AdditionalBoundPatternList?
  	  	                     
  	  	AdditionalBoundPatternList ::= AdditionalBoundPattern AdditionalBoundPatternList |
  	  	                                         AdditionalBoundPattern
  	  	                               
  	  	AdditionalBoundPattern ::= '&' TypePattern 
  	  	
		]]></programlisting>
  	  	
  	  	<para>
  	  	    A simple identifier (such as <literal>String</literal>) occuring in a type parameter list will be treated as a type name unless
  	  	    a type variable of that name is in scope (declaring type variables is covered later). The type pattern <literal>List&lt;E&gt;</literal>
  	  	    will result in an "invalid absolute type name" warning if no type <literal>E</literal> is in scope (declared in the default package, or
  	  	    imported in the compilation unit) and no declaration of <literal>E</literal> as a type variable is in scope either. 
  	  	</para>
  	  	
  	  	<para>Some simple examples of type patterns follow:</para>
  	  	
    <variablelist>

        <varlistentry>
          <term>List&lt;String&gt;</term>
          <listitem>
            <para>Matches the parameterized type <literal>List&lt;String&gt;</literal>
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>List&lt;? extends Number&gt;</term>
          <listitem>
            <para>Matches the parameterized type <literal>List&lt;? extends Number&gt;</literal>
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>List&lt;E&gt;</term>
          <listitem>
            <para>Outside of a scope in which <literal>E</literal>is defined as a type variable, this pattern matches the 
            parameterized type <literal>List&lt;E&gt;</literal>. If <literal>E</literal> is not
            a type then an <literal>invalidAbsoluteTypeName</literal> xlint warning will be issued. 
            </para>
            <para>In a scope in which
            <literal>E</literal> is defined as a type variable, this pattern matches the generic type <literal>List&lt;E&gt;</literal>.
            The type parameter name does not have to match the name used in the declaration of <literal>List</literal>, 
            but the bounds must match. This pattern <emphasis>also</emphasis> matches any parameterization of <literal>List</literal> 
            that satisfies the bounds of the type variable (for example, <literal>List&lt;String&gt;</literal>).
            </para>
          </listitem>
        </varlistentry>
        
       </variablelist>
  	  	
  	  <para>
  	    The <literal>*</literal>, <literal>+</literal>, and <literal>..</literal> wildcards may be used in type patterns
  	    matching against generic and parameterized types (just as in any other type pattern). The <literal>+</literal>
  	    wildcard matches all subtypes. Recalling the discussion on subtypes and supertypes in the previous section, note
  	    that the pattern <literal>List&lt;Number&gt;+</literal> will match <literal>List&lt;Number&gt;</literal> and
  	    <literal>LinkedList&lt;Number&gt;</literal>, but not <literal>List&lt;Double&gt;</literal>. To match lists of
  	    any number type use the pattern <literal>List&lt;Number+&gt;</literal> which will match 
  	    <literal>List&lt;Number&gt;</literal>, <literal>List&lt;Double&gt;</literal>, <literal>List&lt;Float&gt;</literal>
  	    and so on.  
  	  </para>	
  	  
  	  <para>
  	      The generics wildcard <literal>?</literal> is considered part of the signature of a parameterized type, and
  	      is <emphasis>not</emphasis> used as an AspectJ wildcard in type matching. For example:
  	  </para>
  	  	
    <variablelist>

        <varlistentry>
          <term>List&lt;*&gt;</term>
          <listitem>
            <para>Matches any generic or parameterized <literal>List</literal>type (<literal>List&lt;String&gt;</literal>,
              <literal>List&lt;Integer&gt;</literal> and so on) with a single type parameter.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>List&lt;?&gt;</term>
          <listitem>
            <para>Matches the parameterized type <literal>List&lt;?&gt;</literal> (and does 
              <emphasis>not</emphasis> match <literal>List&lt;String&gt;</literal>,
              <literal>List&lt;Integer&gt;</literal> and so on)
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>List&lt;? extends Number+&gt;</term>
          <listitem>
            <para>Matches <literal>List&lt;? extends Number&gt;</literal>, <literal>List&lt;? extends Double&gt;</literal>,
              and so on, but does not match <literal>List&lt;Double&gt;</literal>.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      </sect2>
      
      <sect2>
          <title>Signature patterns</title>
          
          <para>
              Now that we understand how to write type patterns that match generic and parameterized types, it is time to look at
              how these can be utilized to match member declarations by using signature patterns.
           </para>
                    
          <para>To match members declared in generic types and making use of type variables defined in those types (for
          example <literal>interface  Foo&lt;T&gt; { public T doSomething(); }</literal> use a signature pattern of the form:</para>

      	<programlisting><![CDATA[
      	X Foo<X>.doSomething()
		]]></programlisting>

          <para>
            This assumes a scope in which <literal>X</literal> is declared as a type variable. As with type patterns, the name
            of the type variable does not have to match the name used in the member declaration, but the bounds must match.
            For example, if the interface was declared as <literal>Foo&lt;T extends Number&gt;</literal> then the signature 
            pattern would be: <literal>X Foo&lt;X extends Number&gt;.doSomething()</literal>.
          </para>    
          
      <variablelist>

        <varlistentry>
          <term>T Util&lt;T extends Number,S&gt;.someFunction(List&lt;S&gt;)</term>
          <listitem>
            <para>Matches the method <literal>someFunction</literal> in a generic type <literal>Util</literal> with
            two type parameters, the first type parameter having an upper bound of <literal>Number</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>LinkedList&lt;E&gt;.new()</term>
          <listitem>
            <para>Matches the no-argument constructor of the generic type <literal>LinkedList</literal>. 
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

          <para>
            Matching a field with a generic type works in the same way. For example:
          </para>

      	<programlisting><![CDATA[
      	T *<T>.*
		]]></programlisting>

            <para>Matches a field of the type of type parameter <literal>T</literal> in any generic type with a single
            unbounded type parameter (the pattern<literal>*&lt;T&gt;</literal>). The field may be of any name.
            </para>
          
     <para>Matching of members of parameterized types is straightforward. For example, 
          <literal>void List&lt;String&gt;.add(String)</literal> matches the add method in the 
          parameterized type <literal>List&lt;String&gt;</literal>.     
     </para>
          
          <para>
            To match a generic <emphasis>method</emphasis> the generic method type variable
            declarations become part of the signature pattern. For example:          
          </para>

        <programlisting><![CDATA[
          <T> List<T> *.favourites(List<T>)
		]]></programlisting>
		
		<para>matches a generic method <literal>favourites</literal> declared in any type. To match a 
		static generic method simply include the <literal>static</literal> modifier in the type pattern.</para>
          
      </sect2>
  	  	
      <sect2>
          <title>Pointcuts</title>

        <para>
            In this section we discuss how type patterns and signature patterns matching on generic and 
            parameterized types, methods, and constructors can be used in pointcut expressions.  
            We distinguish between pointcuts that match based on static type information, and pointcuts 
            that match based on runtime type information (<literal>this, target, args</literal>).
        </para>
        
        <para>
            First however we need to address the notion of type variables and scopes. There is a 
            convention in Java, but no requirement, that type variables are named with a single letter. 
            Likewise it is rare, but perfectly legal, to declare a type with a single character name. Given the
            type pattern <literal>List&lt;Strng&gt;</literal>, is this a mis-spelling of the 
            parameterized type pattern <literal>List&lt;String&gt;</literal> or is it a generic type pattern
            with one unbounded type variable <literal>Strng</literal>?. Alternatively, given the
            type pattern <literal>List&lt;E&gt;</literal>, if  the type <literal>E</literal> cannot be found,
            is this a missing import statement or an implied type variable? There is no way for AspectJ
            to disambiguate in these situations without an explicit declaration of type variable names. If 
            <literal>E</literal> is defined as a type variable, and <literal>Strng</literal> is not, then both
            declarations can be correctly interpreted.
         </para>

        <sect3>
            <title>Type Variables in Pointcut Expressions</title>
         
         <para>The type variables in scope for a pointcut primitive are declared in a type variable
         list immediately following the pointcut desginator keyword. For example:</para>
         
        <programlisting><![CDATA[
          call<T>(* Foo<T>.*(T))
		]]></programlisting>
         
        <para>matches a call to a method with any name (<literal>*</literal>) declared 
        by a generic type <literal>Foo</literal> with one unbounded type parameter. The method
        takes one argument which is of the type of the type variable.</para>
        
        <para>In contrast, the pointcut</para>
        
        <programlisting><![CDATA[
          call(* Foo<T>.*(T))
		]]></programlisting>
        
        <para>matches a call to a method with any name that takes an argument of
        type <literal>T</literal>, where the target of the call is declared as the parameterized
        type <literal>Foo&lt;T&gt;</literal>. If there is no type <literal>T</literal> in scope, an 
        "invalid absolute type name (T)" warning will be issued.</para>
        
        <para>
            The type variables declaration following a pointcut designator permits only simple identifiers 
            (e.g. <literal>&lt;S,T&gt;</literal> and not <literal>&lt;S extends Number&gt;</literal>).
        </para>
        
        <para>A type variable declaration list can appear following any pointcut designator except
        for <literal>handler</literal> (Java 5 does
        not permit a generic class to be a direct or indirect subtype of <literal>Throwable</literal>
         - see JLS 8.1.2), the dynamic pointcuts <literal>this, target, args, if, cflow, cflowbelow</literal>, 
         and the annotation pointcut designators 
        (<literal>@args, @this, @within</literal> and so on).</para>
        
    </sect3>

    <sect3>
        <title>Initialization and execution pointcuts</title>
        
        <para>
         Recall that there is only ever one type for a generic type (e.g. <literal>List&lt;E&gt;</literal>)
         regardless of how many different parameterizations of that type (e.g. 
         <literal>List&lt;String&gt;</literal>, <literal>List&lt;Double&gt;</literal>) are used within a
         program. For join points that occur within a type, such as execution join points, it therefore only
         makes sense to talk about execution join points for the generic type. Given the generic type 
         </para>

        <programlisting><![CDATA[
        public class Foo<T> {
            
          T doSomething(T toSomeT) {
             return T;
          }  
          
        }
		]]></programlisting>
         
         <para>
             then 
         </para>

      <variablelist>

        <varlistentry>
          <term>execution&lt;T&gt;(T Foo&lt;T&gt;.doSomething(..))</term>
          <listitem>
            <para>matches the execution of the <literal>doSomething</literal> method in
            <literal>Foo</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>execution(* Foo.doSomething(..))</term>
          <listitem>
            <para>also matches the execution of the <literal>doSomething</literal> method in
            <literal>Foo</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>execution(T Foo.doSomething(..))</term>
          <listitem>
            <para>results in an "invalid absolute type name (T)" warning since <literal>T</literal> is 
            interpreted as a type, not a type variable.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>execution(String Foo&lt;String&gt;.doSomething(..))</term>
          <listitem>
            <para>results in a compilation error "no execution join points for parameterized type
                Foo&lt;String&gt;, use a generic signature instead".
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <para>
          Given the type declaration
       </para>

        <programlisting><![CDATA[
        public class Bar<N extends Number> {
            
          N doSomething(N toSomeN) {
             return N;
          }  
          
        }
		]]></programlisting>
         
         <para>
             then 
         </para>

      <variablelist>

        <varlistentry>
          <term>execution&lt;T&gt;(T Bar&lt;T&gt;.doSomething(..))</term>
          <listitem>
            <para>does not match the execution of <literal>Bar.doSomething</literal> since
            the bounds of the type parameter <literal>T</literal> in the pointcut expression do
            not match the bounds of the type parameter <literal>N</literal> in the type declaration.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>execution&lt;T&gt;(T Bar&lt;T extends Number&gt;.doSomething(..))</term>
          <listitem>
            <para>matches the execution of the <literal>doSomething</literal> method in
            <literal>Bar</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>execution&lt;T extends Number&gt;(T Bar&lt;T&gt;.doSomething(..))</term>
          <listitem>
            <para>results in a compilation error, since type variable bounds must be specified as part
                of the declaring type pattern, and not in the type variable list.
            </para>
          </listitem>
        </varlistentry>

    </variablelist>
         
      <para>
          If a type implements a <emphasis>parameterized</emphasis> interface, then
          execution join points exist and can be matched for the parameterized interface operations within
          the implementing type. For example, given the pair of types:   
       </para>
       
        <programlisting><![CDATA[
        public interface Greatest<T> {
            T greatest(List<T> ts);  
        }
        
        public class  NumberOperations implements Greatest<Number> {
             public Number greatest(List<Number> numbers) {
                //...
             }
        }
		]]></programlisting>
       
      <para>
          then
       </para>

        <programlisting><![CDATA[
        execution(* Greatest<Number>.*(..))
		]]></programlisting>

      <para>
          will match the execution of the <literal>greatest</literal> method declared in 
          <literal>NumberOperations</literal>. However, it <emphasis>does not</emphasis>
          match the execution of <literal>greatest</literal> in the program below:
       </para>

        <programlisting><![CDATA[
        public interface Greatest<T> {
            T greatest(List<T> ts);  
        }
        
        public class  NumberOperations<N extends Number> implements Greatest<N> {
             public N greatest(List<N> numbers) {
                //...
             }
        }
        
        // in some fragment of code...
        NumberOperations<Number> numOps = new NumberOperations<Number>();
        numOps.greatest(numList);
		]]></programlisting>

        <para>Since there is only one generic type, <literal>NumberOperations</literal>,
        which implements a generic interface. Either of the pointcut expressions
        <literal>execution&lt;T&gt;(* Greatest&lt;T&gt;>.*(..))</literal> or 
        <literal>execution&lt;T&gt;(* Greatest&lt;T extends Number&gt;>.*(..))</literal> will
        match the execution of <literal>greatest</literal> in this example.  Recall from 
        chapter <xref linkend="jpsigs"/> that a kinded pointcut primitive matches a join point if
        it exactly matches one of the signatures of the join point. The signatures of the
        execution join point for <literal>greatest</literal> in the example above are:</para>
        
      <variablelist>

        <varlistentry>
          <term>public N Greatest&lt;N&gt;.greatest(List&lt;N&gt;)</term>
          <listitem>
            <para>from the declaration in the <literal>Greatest</literal> interface, and
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>public N Greatest&lt;N extends Number&gt;.greatest(List&lt;N&gt;)</term>
          <listitem>
            <para>from the additional bounds restriction of <literal>N</literal> in the
            declaration of <literal>NumberOperations</literal>
            </para>
          </listitem>
        </varlistentry>

    </variablelist>
    
    <para>
        Join points for <literal>staticinitialization</literal>,<literal>initialization</literal> and 
        <literal>preinitialization</literal> 
        only ever exist on a generic type (an interface cannot define a constructor). The expression
        <literal>initialization&lt;T&gt;(Foo&lt;T&gt;.new(..))</literal> which match any initialization 
        join point for the generic type <literal>Foo&lt;T&gt;</literal>, and 
        <literal>staticinitialization&lt;T&gt;(Foo&lt;T&gt;)</literal> matches the static initialization 
        of that same type. 
     </para>
     
     <para>
         The expression <literal>staticinitialization(List&lt;String&gt;)</literal> will result in a 
         compilation error: there is no static initialization join point for the parameterized type
         <literal>List&lt;String&gt;</literal>. However, the expression 
         <literal>staticinitialization(List&lt;String&gt;+)</literal> <emphasis>is</emphasis>
         legal, and will match the static initialization of any type that 
         <literal>implements List&lt;String&gt;</literal>.  The expression
         <literal>staticinitialization&lt;T&gt;(List&lt;T&gt;+)</literal> will match the static
         initialization join point of any type that either extends or implements the generic
         type <literal>List&lt;T&gt;</literal> or implements any parameterization of that
         interface. 
      </para>
         
    </sect3>

     <sect3>
         <title>Static scoping: within and withincode</title>
         
         <para>The <literal>within</literal> and <literal>withincode</literal> 
         pointcut designators both match the
         execution of join points that occur within a type or a member of a type respectively. Therefore
         the same considerations with respect to there only being <literal>one</literal> type for
         a generic type regardless of how many parameterizations of that type are used in a program 
         apply.
         </para>
         
         <para>The <literal>within</literal> pointcut designator can never be used in conjunction
         with a simple parameterized type. So
         </para>

      <variablelist>

        <varlistentry>
          <term>within&lt;T&gt;(Foo&lt;T&gt;)</term>
          <listitem>
            <para>matches all join points occurring within the generic type <literal>Foo&lt;T&gt;</literal>,
            and
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>within(Foo&lt;String&gt;)</term>
          <listitem>
            <para>results in a compilation error since there is no concept of a join point within a 
            parameterized type, but 
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>within(Foo&lt;String&gt;+)</term>
          <listitem>
            <para>matches any join point occurring within a type that 
            <literal>implements Foo&lt;String&gt;</literal>.
            </para>
          </listitem>
        </varlistentry>

    </variablelist>
         
         <para>The <literal>withincode</literal> designator is likewise normally used with a 
         generic type, but can be used with a parameterized interface type to match join points
         arising from code lexically within the implementation of the interface methods in a type
         that implements the parameterized interface.
         </para> 

      <variablelist>

        <varlistentry>
          <term>withincode&lt;T&gt;(* Foo&lt;T&gt;.*(..))</term>
          <listitem>
            <para>matches all join points arising from code lexically within a method of the 
            generic type <literal>Foo&lt;T&gt;</literal>
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>withincode(* Foo&lt;String&gt;.*(..))</term>
          <listitem>
            <para>results in a compilation error if <literal>Foo</literal> is not an interface. If 
            <literal>Foo</literal> is an interface then it matches all join points arising from
            code lexically within the implementation of the interface methods in a type that
            implements <literal>Foo&lt;String&gt;</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>withincode(* Foo&lt;String&gt;+.*(..))</term>
          <listitem>
            <para>matches any join point occurring within a method of a type that 
            <literal>implements Foo&lt;String&gt;</literal>.
            </para>
          </listitem>
        </varlistentry>

    </variablelist>
         
     </sect3>
     
     <sect3>
        <title>Call, get and set pointcuts</title>
     
     <para>
         The <literal>call, get,</literal> and <literal>set</literal> join points can occur on the client
         side (ie. outside of the type owning the member being called, accessed, or updated) or 
         within the type that owns the target member. The following short program demonstrates this:
     </para>

        <programlisting><![CDATA[
        public class Foo<T> {
        
          public T timeFor;  
          
          public Foo<T>(T aCuppa) {
                timeFor = aCuppa;      // set-site A
          }
        
          public void doThis(T t) {
            doThat(t);  // call-site A
          }    
          
          public void doThat(T t) {
             return;
          }
            
        }
        
        public class Main {
          public static void main(String[] args) {
            Foo<String> foos = new Foo<String>();
            foos.doThis("b");  //call-site B  
            foos.doThat("c");  // call-site C
            foos.timeFor = "a cuppa"; // set-site B
          }
        }
		]]></programlisting>

        <para>
            We have annotated the three method call sites as call-site A, call-site B, and call-site C. 
            Call-site A is situated within the generic type <literal>Foo&lt;T&gt;</literal> and the call
            join point has signature <literal>public void Foo&lt;T&gt;doThat(T)</literal>. The join point
            arising from call-site B is a client-side call join point and has the signatures
            <literal>public void Foo&lt;String&gt;doThis(String)</literal> (from the static type of 
            <literal>foos</literal>) <emphasis>and</emphasis>  
            <literal>public void Foo&lt;T&gt;doThis(T)</literal>. Likewise the call join point arising from
            call-site C has the signatures 
            <literal>public void Foo&lt;String&gt;doThat(String)</literal> (from the static type of 
            <literal>foos</literal>) <emphasis>and</emphasis>  
            <literal>public void Foo&lt;T&gt;doThat(T)</literal>. A call pointcut expression matches if the
            signature pattern exactly matches one of the signatures of the call join point.
        </para>
        
        <para>
            The signatures for get and set join points works in a similar fashion. At set-site A in the above
            example, the set join point has signature <literal>public T Foo&lt;T&gt;.timeFor</literal>. At 
            set-site B the set join point has signatures <literal>public T Foo&lt;T&gt;.timeFor</literal> and
            <literal>public String Foo&lt;String&gt;.timeFor</literal>. A get or set pointcut expression
            matches if the signature pattern exactly matches one of the signatures of the join point.
         </para>
         
         Some examples follow:

      <variablelist>

        <varlistentry>
          <term>call(* List&lt;?&gt;.*(..))</term>
          <listitem>
            <para>matches a call to any method of a <literal>List&lt;?&gt;</literal> (a call where the
            target is declared to be a <literal>List&lt;?&gt;</literal>). For example:
            </para>
        <programlisting><![CDATA[
        int countItems(List<?> anyList) {
          return anyList.size();   // matched by call(* List<?>.*(..))
        }
		]]></programlisting>

          </listitem>
        </varlistentry>

        <varlistentry>
          <term>call&lt;T&gt;(* List&lt;T&gt;.*(..))</term>
          <listitem>
            <para>matches any call to an operation defined in the generic type 
            <literal>List&lt;E&gt;</literal>. This includes calls made to <literal>List&lt;String&gt;</literal>,
            <literal>List&lt;Number&gt;</literal>, <literal>List&lt;? super Foo&gt;</literal> and so on.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>get&lt;T&gt;(T *&lt;T extends Account&gt;.*)</term>
          <listitem>
            <para>matches the get of any field defined in a generic type with one type parameter that has 
                an upper bound of <literal>Account</literal>. The field has the type of the type parameter, and
                can be of any name. This pointcut expression matches both gets of the field within the
                declaring type, and also gets on parameterized instances of the type.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>set(Account Foo&lt;Account&gt;.*Account)</term>
          <listitem>
            <para>matches the set of a field of type <literal>Account</literal>  where the target
            is of type <literal>Foo&lt;Account&gt;</literal> and the field name ends with "Account". Does not
            match sets of any "*Account" field occurring within the <literal>Foo</literal> type itself.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>call(* List&lt;? extends Number&gt;.add(..))</term>
          <listitem>
            <para>matches any call to add an element to a list of type <literal>List&lt;? extends Number&gt;</literal>.
            Does not match calls to add elements to lists of type <literal>List&lt;Number&gt;</literal> or 
            <literal>List&lt;Double&gt;</literal> as these are distinct types.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>call(* List&lt;Number+&gt;.add(..))</term>
          <listitem>
            <para>matches any call to add an element to a list of type <literal> Number</literal> or
            any subclass of <literal>Number</literal>. For example, <literal>List&lt;Number&gt;, 
            List&lt;Double&gt; List&lt;Float&gt;</literal>.
            Does not match calls to add elements to lists of type <literal>List&lt;? extends Number&gt;</literal> 
            as this is a distinct type.
            </para>
          </listitem>
        </varlistentry>

    </variablelist>
     </sect3>
         
     <sect3>
        <title>Handler</title>

      <para>
          The Java Language Specification states that a generic class may not be a direct or indirect
          subclass of <literal>Throwable</literal>. Therefore it is a compilation error to use a generic
          or parameterized type pattern in a <literal>handler</literal> pointcut expression.
      </para>

     </sect3>
     
     <sect3>
        <title>Runtime type matching: this, target and args</title>
     
     <para>
         Java 5 generics are implemented using a technique known an <emphasis>erasure</emphasis>.
         In particular, what gets "erased" is the ability to find out the parameterized runtime type
         of an instance of a generic type. You can ask if something is an <literal>instanceof List</literal>,
         but not if something is an <literal>instanceof List&lt;String&gt;</literal>
     </para>
     
     <para>
         The <literal>this, target</literal> and <literal>args</literal> pointcut designators all match
         based on the runtime type of the appropriate object (this, target, or argument) at a join point. 
         To match any parameterization of a generic type, simply use the raw type (type variables are
         not permitted with these designators).  For example:
      </para>
     
      <variablelist>

        <varlistentry>
          <term>target(List)</term>
          <listitem>
            <para>matches any call to an instance of <literal>List</literal> (including 
            <literal>List&lt;String&gt;, List&lt;Number&gt;</literal>, and so on.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>args (List)</term>
          <listitem>
            <para>matches any join point with a single argument that is an instance of 
            <literal>List</literal>. 
            </para>
          </listitem>
        </varlistentry>
        
       </variablelist>
       
     <para>
         To match specific parameterizations of a generic type, simply use the type that you require
         the relevant object to be an instance of inside the pointcut expression. For example:
         <literal>target(List&lt;String&gt;)</literal>. 
     </para>
     <para>
         Recall that runtime tests to determine whether an object is an instance of a parameterized
         type are not possible due to erasure. Therefore AspectJ matching behaviour with 
         parameterized types for <literal>this, target</literal> and <literal>args</literal> is as follows. 
     </para>
     
     <simplelist>
         <member>If it can be statically determined that a given object will always be an instance
         of the required type, then the pointcut expressions matches. For example, given a variable
         <literal>bankAccounts</literal>
         of type <literal>Set&lt;BankAccount&gt;</literal> and the pointcut expression
         <literal>target(Set&lt;BankAccount&gt;)</literal> then any call made to
         <literal>bankAccounts</literal> will be matched.</member>
         <member>If it can be statically determined that a given object can never be an 
         instance of the required type, then the pointcut expression does not match. The
         expression <literal>target(List&lt;String&gt;)</literal>will never match a call made 
         using a variable of type <literal>List&lt;Number&gt;</literal> (it is not possible for
         a type to implement two different parameterizations of the same interface).</member>
         <member>If an object <emphasis>might</emphasis> be an instance of the required
         type in some circumstances but not in others, then since it is not possible to perform
         the runtime test, AspectJ deems the pointcut expression to match, but issues an
         unchecked warning. This is analogous to the behaviour of the Java compiler when
         converting between raw and parameterized types. Given a variable of type
         <literal>List&lt;? extends Number&gt;</literal> and a call join point with 
         target pointcut expression <literal>target(List&lt;Double&gt;)</literal> then 
         the expression matches but with an unchecked warning. The warning can be suppressed
         by annotating the associated advice with either <literal>@SuppressAjWarnings</literal>
         or <literal>@SuppressAjWarnings("unchecked")</literal>.</member>
     </simplelist>
     
      <para>   
         When using a parameterized type with the
         <literal>this</literal> pointcut designator then a joinpoint is unambiguously 
         matched if and only if one or more of the following conditions hold:
     </para>
     
     <simplelist>
         <member>the runtime type of the <literal>this</literal> object extends or
         implements the parameterized type. For example, 
         <literal>class Foo implements List&lt;String&gt;</literal> will match
         <literal>this(List&lt;String&gt;)</literal>.</member>
         <member>
           The parameterized "this" type is given using a generics wildcard in the pointcut 
           expression, and the bounds of
           the generic runtime type of <literal>this</literal> are such that all valid parameterizations
           are matched by the wildcard. For example, the pointcut expression 
           <literal>this(List&lt;? extends Number&gt;)</literal> will match a <literal>this</literal>
           object of type <literal>class Foo&lt;N extends Number&gt; implements List&lt;N&gt;</literal>,
           but not an object of type  <literal>class Foo&lt;N&gt; implements List&lt;N&gt;</literal>.
         </member>
     </simplelist>

      <para>
       You've already seen some examples of using the generic wildcard <literal>?</literal>
        in parameterized type patterns. Since <literal>this, target</literal> and 
       <literal>args</literal> match using an instance of test, the generic wildcard can be useful in
       specifying an acceptable range of parameterized types to match. When used in the binding
       form, the same restrictions on operations permitted on the bound variable apply as when a 
       method declares a parameter with a wildcard type. For example, in the advice below, it is
       a compilation error to attemp to add an element into the list <literal>aList</literal>. 
      </para>

        <programlisting><![CDATA[
        before(List<? extends Number> aList) : 
          execution(* org.xyz.Foo.*(..)) && args(aList) {
           aList.add(new Double(5.0d));  // Compilation error on this line
        }
		]]></programlisting>

     </sect3>
     
    <sect3>
        <title>Declaring pointcuts in generic classes</title>

    <para>
        AspectJ permits pointcuts to be declared in classes as well as aspects. A pointcut defined
        inside a generic class may not use the type variables of the class in the pointcut expression
        (just as static members of a generic class may not use type variables). 
        For example:        
     </para>

        <programlisting><![CDATA[
        public class Foo<T extends Number> {
          
          ...
          
          // Not allowed - uses T in the pointcut expression
          public pointcut fooOperationCall(T t) : 
             call(* Foo<T>.*(T)) && args(t);   
            
            
          // permitted, but recommended to use an alternate variable name in the local 
          // type variable declaration - e.g. execution<S>(...)
          public pointcut fooExecution(Number n) :
             execution<T>(* Foo<T>.*(T)) && args(n); 
        }
		]]></programlisting>

    </sect3>

      </sect2>
      
      <sect2>
          <title>Inter-type Declarations</title>
          
          <para>
            AspectJ 5 allows type parameters to be used in inter-type declarations - either for declaring generic
            methods and constructors, or for declaring members on generic types. The syntax for declaring generic
            methods and constructors follows the regular AspectJ convention of simply qualifying the member name with
            the target type.
          </para>
          
        <variablelist>

        <varlistentry>
          <term>&lt;T extends Number&gt; T Utils.max(T first, T second) {...}</term>
          <listitem>
            <para>Declares a generic instance method <literal>max</literal> on the class <literal>Util</literal>.
            The <literal>max</literal> method takes two arguments, <literal>first</literal> and <literal>second</literal> which must
            both be of the same type (and that type must be Number or a subtype of Number) and returns an instance
            of that type.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>static &lt;E&gt; E Utils.first(List&lt;E&gt; elements) {...}</term>
          <listitem>
            <para>Declares a static generic method <literal>first</literal> on the class <literal>Util</literal>.
            The <literal>first</literal> method takes a list of elements of some type, and returns an instance
            of that type.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>&lt;T&gt; Sorter.new(List&lt;T&gt; elements,Comparator&lt;? super T&gt; comparator) {...}</term>
          <listitem>
            <para>Declares a constructor on the class <literal>Sorter</literal>.
            The constructor takes a list of elements of some type, and a comparator that can compare instances
            of the element type.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>
         
      <para>
         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 <emphasis>names</emphasis> do not have to match.
         For example, given the generic type <literal>Foo&lt;T,S extends Number&gt;</literal> then:      
      </para>    
      
        <variablelist>

        <varlistentry>
          <term>String Foo.getName() {...}</term>
          <listitem>
            <para>Declares a <literal>getName</literal> method on behalf of the raw type <literal>Foo</literal>. It is
            not possible to refer to the type parameters of Foo in such a declaration.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>R Foo&lt;Q, R&gt;.getMagnitude() {...}</term>
          <listitem>
            <para>Declares a method <literal>getMagnitude</literal> on the generic class <literal>Foo</literal>.
            The method returns an instance of the type substituted for the second type parameter in an invocation
            of <literal>Foo</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>R Foo&lt;Q, R extends Number&gt;.getMagnitude() {...}</term>
          <listitem>
            <para>Results in a compilation error since a bounds specification is not allowed in this
                form of an inter-type declaration (the bounds are determined from the declaration of the
                target type).
            </para>
          </listitem>
        </varlistentry>

      </variablelist>
      
      <para>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) <literal>Foo&lt;String&gt;</literal>, you can only declare members on the generic
      type <literal>Foo&lt;T&gt;</literal>. 
      </para>
      
      <para>
        If an inter-type member is declared inside a generic aspect, then the type parameter names from the
        aspect declaration may be used in the signature specification of the inter-type declaration, but 
        <emphasis>not</emphasis> as type parameter names for a generic target type. In other words the example
        that follows is legal:
      </para>

        <programlisting><![CDATA[
            public abstract aspect A<T> {
              
              private T Foo.data;
              
              public T Foo.getData(T defaultValue) {
                return (this.data != null ? data : defaultValue);
              }   
                
            }
		]]></programlisting>
      
      <para>
       Whereas the following example is not allowed and will report an error that a parameterized type may not be the
       target of an inter-type declaration (since when the type parameter <literal>T</literal> in the aspect is subsituted with
       say, <literal>String</literal>, then the target of the inter-type declaration becomes <literal>Goo&lt;String&gt;</literal>).  
      </para>

        <programlisting><![CDATA[
            public abstract aspect A<T> {
              
              private T Goo<T>.data;
              
              public T Goo<T>.getData(T defaultValue) {
                return (this.data != null ? data : defaultValue);
              }   
                
            }
		]]></programlisting>
            
      </sect2>

      <sect2>
          <title>Declare Parents</title>
          
          <para>Both generic and parameterized types can be used as the parent type in a <literal>declare parents</literal>
          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 <literal>declare parents</literal> statement: 
          a type variable list follows the <literal>parents</literal> keyword in these cases to declare the
          type variables in scope.
          Some examples follow:</para>

        <variablelist>

        <varlistentry>
          <term>declare parents: Foo implements List&lt;String&gt;</term>
          <listitem>
            <para>The <literal>Foo</literal> type implements the <literal>List&lt;String&gt;</literal> interface. If
            <literal>Foo</literal> already implements some other parameterization of the <literal>List</literal>
            interface (for example, <literal>List&lt;Integer&gt;</literal> then a compilation error will result since a 
            type cannot implement multiple parameterizations of the same generic interface type. 
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>declare parents &lt;T&gt;:  org.xyz..*&lt;T&gt; extends Base&lt;T&gt;</term>
          <listitem>
            <para>All generic types declared in a package beginning with <literal>org.xyz</literal> and with a 
            single unbounded type parameter, extend the generic type <literal>Base&lt;T&gt;</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>declare parents &lt;T&gt;:  org.xyz..*&lt;T&gt; extends Base&lt;S&gt;</term>
          <listitem>
            <para>Results in a compilation error (unless <literal>S</literal> is a type) since <literal>S</literal> is
            not bound in the type pattern.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      </sect2>
      
      <sect2>
          <title>Declare Soft</title>
          <para>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 <literal>Throwable</literal> (JLS 8.1.2).</para>
      </sect2>

      <sect2>
          <title>Parameterized Aspects</title>
          
          <para>
            AspectJ 5 allows an <emphasis>abstract</emphasis> 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.     
          </para>
      
          <para>Given the aspect declaration:</para>
          
        <programlisting><![CDATA[
            public abstract aspect ParentChildRelationship<P,C> {
                ...
            }
		]]></programlisting>
           
           <para>then</para>

       <variablelist>

        <varlistentry>
          <term>public aspect FilesInFolders extends ParentChildRelationship&lt;Folder,File&gt; {...</term>
          <listitem>
            <para>declares a concrete sub-aspect, <literal>FilesInFolders</literal> which extends the
            parameterized abstract aspect <literal>ParentChildRelationship&lt;Folder,File&gt;</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>public aspect FilesInFolders extends ParentChildRelationship {...</term>
          <listitem>
            <para>results in a compilation error since the <literal>ParentChildRelationship</literal> aspect must
            be fully parameterized.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>public aspect ThingsInFolders&lt;T&gt; extends ParentChildRelationship&lt;Folder,T&gt;</term>
          <listitem>
            <para>results in a compilation error since concrete aspects may not have type parameters.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>public abstract aspect ThingsInFolders&lt;T&gt; extends ParentChildRelationship&lt;Folder,T&gt;</term>
          <listitem>
            <para>declares a sub-aspect of <literal>ParentChildRelationship</literal> in which <literal>Folder</literal>
            plays the role of parent (is bound to the type variable <literal>P</literal>).
            </para>
          </listitem>
        </varlistentry>

      </variablelist>
      
       <para>An exception to the rule that concrete aspects may not be generic is a pertypewithin aspect, which
       may be declared with a single unbounded type parameter. This is discussed in the chapter on <xref
      linkend="pertypewithin" />.</para>
            
        <para>The type parameter variables from a generic aspect declaration may be used in place of a type within any
        member of the aspect. For example, we can declare a <literal>ParentChildRelationship</literal> aspect to
        manage the bi-directional relationship between parent and child nodes as follows:
        </para>

        <programlisting><![CDATA[
            public abstract aspect ParentChildRelationship<P,C> {
                
                /**
                 * Parents contain a list of children
                 */
                private List<C> P.children;
                    
                /**
                 * Each child has a parent
                 */
                private P C.parent;

                /**
                  * Parents provide access to their children
                  */
                public List<C> P.getChildren() {
                    return Collections.unmodifiableList(children);  
                }
                
                /**
                 * A child provides access to its parent
                 */
                 public P C.getParent() {
                   return parent;
                 }
                
                /**
                 * ensure bi-directional navigation on adding a child
                 */
                public void P.addChild(C child) {
                   if (child.parent != null) {
                     child.parent.removeChild(child);
                   }
                   children.add(child);
                   child.parent = this;
                }

                /**
                 * ensure bi-directional navigation on removing a child
                 */
                public void P.removeChild(C child) {
                   if (children.remove(child)) {
                     child.parent = null;
                   }
                }

               /**
                 * ensure bi-directional navigation on setting parent
                 */
                public void C.setParent(P parent) {
                   parent.addChild(this);
                }
                
                public pointcut addingChild(P p, C c) :
                  execution(* P.addChild(C)) && this(p) && args(c);
                  
                public pointcut removingChild(P p, C c) :
                  execution(* P.removeChild(C)) && this(p) && args(c);
            }
		]]></programlisting>

        <para>
          Note in the above example how the type parameters <literal>P</literal> and <literal>C</literal> can be
          used in inter-type declarations, pointcut expressions, and any other member of the aspect type. 
        </para>
        
        <para>
          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:
        </para>

        <programlisting><![CDATA[
            public aspect ASTNodeContainment extends ParentChildRelationship<ASTNode,ASTNode> {
                
                before(ASTNode parent, ASTNode child) : addingChild(parent, child) {
                  ...
                }
                
            }
		]]></programlisting>
            
         <para>
           As a result of this declaration, <literal>ASTNode</literal> gains members:
         </para>

        <simplelist>
            <member><literal>List&lt;ASTNode&gt; children</literal></member>
            <member><literal>ASTNode parent</literal></member>
            <member><literal>List&lt;ASTNode&gt;getChildren()</literal></member>
            <member><literal>ASTNode getParent()</literal></member>
            <member><literal>void addChild(ASTNode child)</literal></member>
            <member><literal>void removeChild(ASTNode child)</literal></member>
            <member><literal>void setParent(ASTNode parent)</literal></member>
        </simplelist>         
         
         <para>
           In a system managing files and folders, we could declare the concrete aspect:
         </para>

        <programlisting><![CDATA[
            public aspect FilesInFolders extends ParentChildRelationship<Folder,File> {
                                
            }
		]]></programlisting>

         <para>
           As a result of this declaration, <literal>Folder</literal> gains members:
         </para>

        <simplelist>
            <member><literal>List&lt;File&gt; children</literal></member>
            <member><literal>List&lt;File&gt; getChildren()</literal></member>
            <member><literal>void addChild(File child)</literal></member>
            <member><literal>void removeChild(File child)</literal></member>
        </simplelist>         

        <para>and <literal>File</literal> gains members:</para>
        
        <simplelist>
            <member><literal>Folder parent</literal></member>
            <member><literal>Folder getParent()</literal></member>
            <member><literal>void setParent(Folder parent)</literal></member>
        </simplelist>         
         
        <para>When used in this way, the type parameters in a generic abstract aspect declare
        <emphasis>roles</emphasis>, and the parameterization of the abstract aspect in the <literal>extends</literal>
        clause binds types to those roles. This is a case where you may consider departing from the standard practice 
        of using a single letter to represent a type parameter, and instead use a role name. It makes no difference
        to the compiler which option you choose of course.</para>

        <programlisting><![CDATA[
            public abstract aspect ParentChildRelationship<Parent,Child> {
                
                /**
                 * Parents contain a list of children
                 */
                private List<Child> Parent.children;
                    
                /**
                 * Each child has a parent
                 */
                private Parent Child.parent;
                
                /**
                  * Parents provide access to their children
                  */
                public List<Children> Parent.getChildren() {
                    return Collections.unmodifiableList(children);  
                }
                
                /**
                 * A child provides access to its parent
                 */
                 public Parent Children.getParent() {
                   return parent;
                 }
                                
                /**
                 * ensure bi-directional navigation on adding a child
                 */
                public void Parent.addChild(Child child) {
                   if (child.parent != null) {
                     child.parent.removeChild(child);
                   }
                   children.add(child);
                   child.parent = this;
                }
         
                ...
		]]></programlisting>
      </sect2>
      
  </sect1>
  
</chapter>