updates for 1.5.0 M1

5 files changed, 504 insertions, 266 deletions

diff --git a/docs/adk15ProgGuideDB/annotations.xml b/docs/adk15ProgGuideDB/annotations.xml
index 979d8b9c3..dab312c43 100644
--- a/docs/adk15ProgGuideDB/annotations.xml
+++ b/docs/adk15ProgGuideDB/annotations.xml
@@ -282,98 +282,115 @@
       <para>
           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.
+          on the annotated element. Annotation patterns are defined by the following
+          grammar.
       </para>
       
       <programlisting><![CDATA[
-		AnnotationPattern := AnnotationName |
-  		                     '!' AnnotationPattern |
-  		                     '(' AnnotationPatern '&&' AnnotationPattern ')' |
-  		                     '(' AnnotationPattern '||' AnnotationPattern ')' |
-  		                     '(' AnnotationPattern ')'
+		AnnotationPattern := '@' AnnotationTypePattern AnnotationPattern* |
+  		                     '!' AnnotationPattern
+        
+        AnnotationTypePattern := FullyQualifiedName |
+                                 '(' TypePattern ')'
   		                     
-  		AnnotationName := '@' JavaIdentifierCharacter+ ('.' JavaIdentifierCharacter+)*      
+  		FullyQualifiedName := JavaIdentifierCharacter+ ('.' JavaIdentifierCharacter+)*  		
       ]]></programlisting>
         
-      <para>For example:</para>  
+      <para>In simple terms, an annotation pattern element has one of two basic
+      forms:</para>  
+    
+      <itemizedlist>
+          <listitem>@&lt;qualified-name&gt;, for example, @Foo, or 
+          @org.xyz.Foo.</listitem>
+          <listitem>@(&lt;type-pattern&gt;), for example, @(org.xzy..*), or
+          @(Foo || Boo)</listitem>
+      </itemizedlist>
+
+      <para>These simple elements may be negated using <literal>!</literal>, and
+      combined by simple concatentation. The pattern <literal>@Foo @Boo</literal>
+      matches an annotated element that has both an annotation of type <literal>Foo</literal>
+      and an annotation of type <literal>Boo</literal>.</para>
+      
+      <para>Some examples of annotation patterns follow:</para>    
 
       <programlisting><![CDATA[
       @Immutable
       ]]></programlisting>
 
-      <para>Matches any annotated element which has an annotation of type <literal>@Immutable</literal>.</para>
+      <para>Matches any annotated element which has an annotation of 
+      type <literal>Immutable</literal>.</para>
 
       <programlisting><![CDATA[
       !@Persistent
       ]]></programlisting>
 
-      <para>Matches any annotated element which does not have an annotation of type <literal>@Persistent</literal>.</para>
+      <para>Matches any annotated element which does not have an annotation of 
+      type <literal>Persistent</literal>.</para>
 
       <programlisting><![CDATA[
-      (@Foo && @Goo)
+      @Foo @Goo
       ]]></programlisting>
 
-      <para>Matches any annotated element which has both an annotation of type <literal>@Foo</literal> and
-      an annotation of type <literal>@Goo</literal>. (The parenthesis are required in this example).</para>
+      <para>Matches any annotated element which has both an annotation of type <literal>Foo</literal> and
+      an annotation of type <literal>Goo</literal>.</para>
 
       <programlisting><![CDATA[
-      (@Foo || @Goo)
+      @(Foo || Goo)
       ]]></programlisting>
 
-      <para>Matches any annotated element which has either an annotation of type <literal>@Foo</literal> or
-      an annotation of type <literal>@Goo</literal> (or both). (The parenthesis are required in this example).</para>
+      <para>Matches any annotated element which has either an annotation of a type matching
+      the type pattern <literal>(Foo || Goo)</literal>. 
+      In other words, an annotated element with either an
+      annotation of type <literal>Foo</literal> or
+      an annotation of type <literal>Goo</literal> (or both). (The parenthesis are required in this example).
+      </para>
+
+      <programlisting><![CDATA[
+      @(org.xyz..*)
+      ]]></programlisting>
+
+      <para>Matches any annotated element which has either an annotation of a type matching
+      the type pattern <literal>(org.xyz..*)</literal>. 
+      In other words, an annotated element with an annotation that is declared in the
+      org.xyz package or a sub-package. (The parenthesis are required in this example).</para>
 
   </sect2>
   
   <sect2>
   	<title>Type Patterns</title>
   	
-  	<para>In AspectJ 1.2, type patterns have the following form:</para>
-  	
-  	<programlisting><![CDATA[  	
-  		TypePattern := IdPattern |
-  		               '!' TypePattern |
-  		               TypePattern '&&' TypePattern |
-  		               TypePattern '||' TypePattern |
-  		               TypePattern '+' |
-  		               TypePattern ('[]')* |
-  		               '(' TypePattern ')'
-  		               
-		IdPattern := SimpleNamePattern |
-		             SimpleNamePattern '.' SimpleNamePattern |
-		             SimpleNamePattern '..' SimpleNamePattern
-					 
-		SimpleNamePattern := ('*' | JavaIdentifierCharacter)+							 				  		             
-	]]></programlisting>
-
 	<para>AspectJ 1.5 extends type patterns to allow an optional <literal>AnnotationPattern</literal>
-	prefix.</para>
+	prefix. (Extensions to this definition for generics are shown in the next chapter).</para>
 
   	<programlisting><![CDATA[
-  	    TypePattern := PlainTypePattern |
+  	    TypePattern := SimpleTypePattern |
   	                   '!' TypePattern |
-  	                   '(' AnnotationPattern PlainTypePattern ')'|
+  	                   '(' AnnotationPattern? TypePattern ')'
   	                   TypePattern '&&' TypePattern |
   	                   TypePattern '||' TypePattern |
-  	                   '(' TypePattern ')'
   	  	
-  	  	OptionalParensTypePattern := TypePattern |
-  	  	                             AnnotationPattern PlainTypePattern
-  	  		
-  		PlainTypePattern := IdPattern |
-  		               '!' PlainTypePattern |
-  		               PlainTypePattern '&&' TypePattern |
-  		               PlainTypePattern '||' TypePattern |
-  		               PlainTypePattern '+' |
-  		               PlainTypePattern ('[]')* |
-  		               '(' PlainTypePattern ')' 
-  		               
-		IdPattern := SimpleNamePattern |
-		             SimpleNamePattern '.' SimpleNamePattern |
-		             SimpleNamePattern '..' SimpleNamePattern
-					 
-		SimpleNamePattern := ('*' | JavaIdentifierCharacter)+							 				  		             
+  	  	SimpleTypePattern := DottedNamePattern '+'? '[]'*
+  	  	
+  		DottedNamePattern := FullyQualifiedName RestOfNamePattern? |
+  		                     '*' NotStarNamePattern?
+  		
+  		RestOfNamePattern := '..' DottedNamePattern |
+  		                     '*' NotStarNamePattern?
+  		                     
+  		NotStarNamePattern := FullyQualifiedName RestOfNamePattern? |
+  		                      '..' DottedNamePattern               
+
+  		FullyQualifiedName := JavaIdentifierCharacter+ ('.' JavaIdentifierCharacter+)*  				  		  		  		               									 				  		             
 	]]></programlisting>
+
+    <para>Note that in most cases when annotations are used as part of a type pattern,
+        the parenthesis are required (as in <literal>(@Foo Hello+)</literal>). In
+        some cases (such as a type pattern used within a <literal>this</literal>
+        pointcut expression, the parenthesis are optional:</para>
+
+      <programlisting><![CDATA[
+        OptionalParensTypePattern := AnnotationPattern? TypePattern
+      ]]></programlisting>
     
 	<para>
 		The following examples illustrate the use of annotations in type
@@ -384,13 +401,13 @@
      (@Immutable *)
      ]]></programlisting>
 
-     <para>Matches any type with the <literal>@Immutable</literal> annotation.</para>
+     <para>Matches any type with an <literal>@Immutable</literal> annotation.</para>
 
      <programlisting><![CDATA[
      (!@Immutable *)
      ]]></programlisting>
 
-     <para>Matches any type which does not have the <literal>@Immutable</literal> annotation.</para>
+     <para>Matches any type which does not have an <literal>@Immutable</literal> annotation.</para>
 
      <programlisting><![CDATA[
      (@Immutable (org.xyz.* || org.abc.*))
@@ -400,16 +417,14 @@
      packages with the <literal>@Immutable</literal> annotation.</para>
 
      <programlisting><![CDATA[
-     (@Immutable Foo+ || Goo)
+     ((@Immutable Foo+) || Goo)
      ]]></programlisting>
 
      <para>Matches a type <literal>Foo</literal> or any of its subtypes, which have the <literal>@Immutable</literal>
-     annotation, or a type <literal>Goo</literal>. An <literal>AnnotationPattern</literal> has higher
-     precedence than <literal>&amp;&amp;</literal> or <literal>||</literal>, so the previous expression
-     is equivalent to <literal>((@Immutable Foo+) || Goo)</literal>.</para>
+     annotation, or a type <literal>Goo</literal>.</para>
      
      <programlisting><![CDATA[
-     ((@Immutable || @NonPersistent) org.xyz..*)
+     ((@(Immutable || NonPersistent) org.xyz..*)
      ]]></programlisting>
 
      <para>
@@ -418,6 +433,28 @@
      <literal>@NonPersistent</literal> annotation.
      </para>
 
+     <programlisting><![CDATA[
+     (@Immutable @NonPersistent org.xyz..*)
+     ]]></programlisting>
+
+     <para>
+     Matches any type in a package beginning with the prefix <literal>org.xyz</literal>,
+     which has both an <literal>@Immutable</literal> annotation and an
+     <literal>@NonPersistent</literal> annotation.
+     </para>
+     
+     <programlisting><![CDATA[
+     (@(@Inherited *) org.xyz..*)
+     ]]></programlisting>
+
+     <para>
+     Matches any type in a package beginning with the prefix <literal>org.xyz</literal>,
+     which has an inheritable annotation. The annotation pattern 
+     <literal>@(@Inherited *)</literal> matches any annotation of a type matching the
+     type pattern <literal>@Inherited *</literal>, which in turn matches any type with the
+     <literal>@Inherited</literal> annotation.
+     </para>
+     
   </sect2>
   
   <sect2 id="signaturePatterns" xreflabel="Signature Patterns">
@@ -429,13 +466,16 @@
   	<programlisting><![CDATA[  	
   		FieldPattern := 
   		    AnnotationPattern? FieldModifiersPattern? 
-  		    TypePattern (TypePattern '.')? SimpleNamePattern
+  		    TypePattern (TypePattern DotOrDotDot)? SimpleNamePattern
 
-		FieldModifiersPattern := FieldModifier*
-		
+		FieldModifiersPattern := '!'? FieldModifier FieldModifiersPattern*
+		                         		
 		FieldModifier := 'public' | 'private' | 'protected' | 'static' | 
 		                 'transient' | 'final' 
-		            					            
+
+        DotOrDotDot := '.' | '..'		            		      
+		            		      		            			
+		SimpleNamePattern := JavaIdentifierChar+ ('*' SimpleNamePattern)?		            
 	]]></programlisting>
   	
   	<para>
@@ -487,26 +527,39 @@
           </listitem>
         </varlistentry>
 
+        <varlistentry>
+          <term>@Persisted @Classified * *</term>
+          <listitem>
+            <para>
+            	Matches a field with an annotation <literal>@Persisted</literal> and
+            	an annotation <literal>@Classified</literal>.
+            </para>
+          </listitem>
+        </varlistentry>
+
     </variablelist>
   	
   	<para>A <literal>MethodPattern</literal> is of the form</para>
 
   	<programlisting><![CDATA[  	
   		MethodPattern := 
-  		    AnnotationPattern? ModifiersPattern? TypePattern 
-  		                       (TypePattern '.')? SimpleNamePattern '(' FormalsPattern ')'
-  		                       ThrowsPattern?
+  		    AnnotationPattern? MethodModifiersPattern? TypePattern 
+  		                       (TypePattern DotOrDotDot)? SimpleNamePattern 
+  		                       '(' FormalsPattern ')'ThrowsPattern?
 
-		ModifiersPattern := Modifier*
+		MethodModifiersPattern := '!'? MethodModifier MethodModifiersPattern*
 		
-		Modifier := 'public' | 'private' | 'protected' | 'static' | 
-		            'synchronized' | 'final' 
+		MethodModifier := 'public' | 'private' | 'protected' | 'static' | 
+		                  'synchronized' | 'final' 
 		            		      
 		FormalsPattern := '..' (',' FormalsPatternAfterDotDot)* |
-		                  OptionalParensTypePattern (',' FormalsPattern)*
-		                  
-		FormalsPatternAfterDotDot := OptionalParensTypePattern (',' FormalsPatternAfterDotDot)*                  
+		                  OptionalParensTypePattern (',' FormalsPattern)* |
+		                  TypePattern '...'
 		                  
+		FormalsPatternAfterDotDot := 
+		        OptionalParensTypePattern (',' FormalsPatternAfterDotDot)* |
+		        TypePattern '...'
+		                                               		                  
 		ThrowsPattern := 'throws' TypePatternList
 		
 		TypePatternList := TypePattern (',' TypePattern)*
@@ -520,14 +573,19 @@
 
   	<programlisting><![CDATA[  	
   		ConstructorPattern := 
-  		    AnnotationPattern? ModifiersPattern?  
-  		                       (TypePattern '.')? 'new' '(' FormalsPattern ')'
+  		    AnnotationPattern? ConstructorModifiersPattern?  
+  		                       (TypePattern DotOrDotDot)? 'new' '(' FormalsPattern ')'
   		                       ThrowsPattern?
+	
+		ConstructorModifiersPattern := '!'? ConstructorModifier ConstructorModifiersPattern*
+		
+		ConstructorModifier := 'public' | 'private' | 'protected'
+		
 	]]></programlisting>
       	
   	<para>
   	    The optional <literal>AnnotationPattern</literal> at the beginning of a 
-  	    method or constructor patterns restricts matches to methods/constructors with
+  	    method or constructor pattern restricts matches to methods/constructors with
   	    annotations that match the pattern. For example:
   	</para>
 
@@ -563,7 +621,6 @@
             </para>
           </listitem>
         </varlistentry>
-
     </variablelist>
 
   </sect2>
@@ -577,7 +634,8 @@
           <term>within(@Secure *)</term>
           <listitem>
             <para>
-            	Matches any join point occuring in a type with an <literal>@Secure</literal>
+            	Matches any join point where the code executing is declared in a 
+            	type with an <literal>@Secure</literal>
             	annotation. The format of the <literal>within</literal> pointcut designator
             	in AspectJ 5 is <literal>'within' '(' OptionalParensTypePattern ')'</literal>.
             </para>
@@ -647,8 +705,7 @@
     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 <literal>@args, @this, @target,
-    @within, @withincode, @call, @execution, @adviceexecution, @get, @set, 
-    @staticinitialization, @initialization,</literal>, and <literal>@preinitialization</literal>
+    @within, @withincode</literal>, and <literal>@annotation</literal>
     </para>
     
     <para>It is a compilation error to attempt to match on an annotation type 
@@ -670,21 +727,23 @@
     </para>
     
   	<programlisting><![CDATA[  	
-  		ThisAnnotation := '@this' '(' AnnotationNameOrVar ')'
-  		
-  		TargetAnnotation := '@target' '(' AnnotationNameOrVar ')'
-  		
-  		ArgsAnnotation := '@args' '(' ArgsAnnotationPattern ')'
-  		
-  		ArgsAnnotationPattern := AnnotationNameOrVar (',' ArgsAnnotationPattern)? |
-  		                         '*' (',' ArgsAnnotationPattern)? |
-  		                         '..' (',' SingleArgsAnnotationPattern)* 
-  		
-  		SingleArgsAnnotationPattern := AnnotationNameOrVar (',' SingleArgsAnnotationPattern)? |
-  		                               '*' (',' SingleArgsAnnotationPattern)?
-  		
-  		AnnotationNameOrVar := AnnotationName |
-  		                       JavaIdentifierCharacter+
+  	    AtThis := '@this' '(' AnnotationOrIdentifer ')'
+    
+        AtTarget := '@target' '(' AnnotationOrIdentifier ')'
+  	
+  	    AnnotationOrIdentifier := '@' FullyQualifiedName | Identifier
+        
+        AtArgs := '@args' '(' AnnotationsOrIdentifiersPattern ')'
+        
+        AnnotationsOrIdentifiersPattern :=
+                          '..' (',' AnnotationsOrIdentifiersPatternAfterDotDot)? |
+		                  AnnotationOrIdentifier (',' AnnotationsOrIdentifiersPattern)* |
+		                  '*' (',' AnnotationsOrIdentifiersPattern)*
+		                  
+		AnnotationsOrIdentifiersPatternAfterDotDot := 
+		                  AnnotationOrIdentifier (',' AnnotationsOrIdentifiersPatternAfterDotDot)* |
+		                  '*' (',' AnnotationsOrIdentifiersPatternAfterDotDot)*
+  	
 	]]></programlisting>
 
     <para>
@@ -791,15 +850,14 @@
 
     <para>
     The <literal>@within</literal> and <literal>@withincode</literal> pointcut designators
-    match any join point where the enclosing type (<literal>@within</literal>), or
-    method/constructor (<literal>@withincode</literal>) has an annotation of the specified 
+    match any join point where the executing code is defined within a type (<literal>@within</literal>),
+     or a method/constructor (<literal>@withincode</literal>) that has an annotation of the specified 
     type. The form of these designators is:
     </para>
     
   	<programlisting><![CDATA[  	
-  		WithinAnnotation := '@within' '(' AnnotationNameOrVar ')'
-  		
-  		WithinCodeAnnotation := '@withincode' '(' AnnotationNameOrVar ')'
+        AtWithin := '@within' '(' AnnotationOrIdentifier ')'
+        AtWithinCode := '@withincode' '(' AnnotationOrIdentifier ')'        
     ]]></programlisting>  		
 
     <para>Some examples of using these designators follow:</para>
@@ -810,8 +868,8 @@
           <term>@within(@Foo)</term>
           <listitem>
             <para>
-            	Matches any join point where the enclosing type
-            	has an annotation of type <literal>Foo</literal>.
+            	Matches any join point where the executing code is defined 
+            	within a type which has an annotation of type <literal>Foo</literal>.
             </para>
           </listitem>
         </varlistentry>
@@ -821,8 +879,8 @@
                   @withincode(c);</term>
           <listitem>
             <para>
-            	Matches any join point whose shadow is lexically enclosed
-            	in a method which has an annotation of type <literal>@Critical</literal>,
+            	Matches any join point where the executing code is defined
+            	in a method or constructor which has an annotation of type <literal>@Critical</literal>,
             	and exposes the value of the annotation in the parameter 
             	<literal>c</literal>.
             </para>
@@ -831,111 +889,17 @@
 
     </variablelist>
     
-    <para>The remaining annotation-based pointcut designators are defined in a 
-    similar fashion:</para>
+    <para>The <literal>@annotation</literal> pointcut designator matches any
+    join point where the <emphasis>subject</emphasis> of the join point has 
+    an annotation of the given type. Like the other @pcds, it can also be
+    used for context exposure.</para>
 
   	<programlisting><![CDATA[  	
-  		CallAnnotation := '@call' '(' AnnotationNameOrVar ')'
-  		
-  		ExecutionAnnotation := '@execution' '(' AnnotationNameOrVar ')'
-  		
-  		AdviceExecution := '@adviceexecution' '(' AnnotationNameOrVar ')'
-
-  		GetAnnotation := '@set' '(' AnnotationNameOrVar ')'
-  		
-  		SetAnnotation := '@get' '(' AnnotationNameOrVar ')'
-  		
-  		InitializationAnnotation := '@initialization' '(' AnnotationNameOrVar ')'
-
-  		PreInitializationAnnotation := '@preinitialization' '(' AnnotationNameOrVar ')'
-        
-  		StaticInitializationAnnotation := '@staticinitialization' '(' AnnotationNameOrVar ')'
-        
-    ]]></programlisting>  		
-
-   <variablelist>
-
-        <varlistentry>
-          <term>@call(@Foo)</term>
-          <listitem>
-            <para>
-            	Matches any call join point where the most specific join point
-            	signature has an annotation of type <literal>@Foo</literal>.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>@execution(@Foo)</term>
-          <listitem>
-            <para>
-            	Matches any execution join point where the most specific join point
-            	signature has an annotation of type <literal>@Foo</literal>.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>@adviceexecution(@Foo)</term>
-          <listitem>
-            <para>
-            	Matches any advice execution join point where the advice 
-            	has an annotation of type <literal>@Foo</literal>.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>@get(@Foo)</term>
-          <listitem>
-            <para>
-            	Matches any get join point where the target field
-            	has an annotation of type <literal>@Foo</literal>.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>@set(@Foo)</term>
-          <listitem>
-            <para>
-            	Matches any set join point where the target field
-            	has an annotation of type <literal>@Foo</literal>.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>@initialization(@Foo)</term>
-          <listitem>
-            <para>
-            	Matches any initialization join point where the initiating
-            	constructor has an annotation of type <literal>@Foo</literal>.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>@preinitialization(@Foo)</term>
-          <listitem>
-            <para>
-            	Matches any preinitialization join point where the initiating
-            	constructor has an annotation of type <literal>@Foo</literal>.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>@staticinitialization(@Foo)</term>
-          <listitem>
-            <para>
-            	Matches any staticinitialization join point where the type being
-            	initialized has an annotation of type <literal>@Foo</literal>.
-            </para>
-          </listitem>
-        </varlistentry>
-
-    </variablelist>
+        AtAnnotation := '@annotation' '(' AnnotationOrIdentifier ')'
+    ]]></programlisting>
+    
+    <para>The subject of a join point is defined in the table in chapter one of
+    this guide.</para>  		
 
     <para>
       Access to annotation information on members at a matched join point is also available
@@ -962,6 +926,15 @@
         to Java 5.</emphasis>
     </para>
     
+    <para>
+        The <literal>@this,@target</literal> and <literal>@args</literal> 
+        pointcut designators can only be used to match against annotations 
+        that have runtime retention. The <literal>@within, @withincode</literal>
+        and <literal>@annotation</literal> 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. 
+    </para>
+    
   </sect2>
 
   <sect2>
@@ -979,6 +952,8 @@
           expressions before commiting to any one approach.</emphasis>
       </para>
 
+<!-- @withinpackage ??? -->
+
 <!--
       <para>
           Java 5 allows both packages and parameters to be annotated. To allow matching on package and parameter annotations,
@@ -1145,9 +1120,6 @@
   
   <sect2>
     <title>Limitations</title>
-    <para>AspectJ 5 allows you to annotate advice, but there is no way to qualify advice execution 
-    join point matching based on the presence of annotations.</para>
-    
     <para>
         It would be useful to be able to match join points based on  
         annotation values, rather than merely the presence of a
@@ -1184,7 +1156,7 @@
 
   	<programlisting><![CDATA[
   	declare error : call(* org.xyz.model.*.*(..)) &&
-  	                @package(@Untrusted)
+  	                !@within(@Trusted *)
   	                : "Untrusted code should not call the model classes directly";
 	]]></programlisting>
     
diff --git a/docs/adk15ProgGuideDB/generics.xml b/docs/adk15ProgGuideDB/generics.xml
index 834951d70..57ea7ae2d 100644
--- a/docs/adk15ProgGuideDB/generics.xml
+++ b/docs/adk15ProgGuideDB/generics.xml
@@ -2,5 +2,53 @@
 
   <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 Parameterized Types</title>
+		
+	</sect2>
+	
+	<sect2>
+	    <title>Using Parameterized Types</title>
+	</sect2>
+	
+	<sect2>
+	    <title>Assignments and Wildcards</title>
+	</sect2>
+	
+	<sect2>
+	    <title>Generic Methods</title>
+	</sect2>
+  </sect1>
+	
+  <sect1 id="generics-inAspectJ5">
+      
+      <sect2>
+          <title>Parameterized Aspect Types</title>
+      </sect2>
+      
+      <sect2>
+          <title></title>
+      </sect2>
+
+      <sect2>
+          <title></title>
+      </sect2>
+
+      <sect2>
+          <title></title>
+      </sect2>
+      
+  </sect1>
+  
 </chapter>
 
diff --git a/docs/adk15ProgGuideDB/grammar.xml b/docs/adk15ProgGuideDB/grammar.xml
index 42a7065d4..42ed65644 100644
--- a/docs/adk15ProgGuideDB/grammar.xml
+++ b/docs/adk15ProgGuideDB/grammar.xml
@@ -2,8 +2,191 @@
 
   <title>A Grammar for the AspectJ 5 Language</title>
   
-  Collect together all the grammar fragments scattered throughout this documented
-  and present them as a coherent whole...
-  
+      <programlisting><![CDATA[
+        === type patterns ===
+      
+   	    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+)*  				  		  		  		               									 				  		             
+ 
+        === annotation patterns ===
+ 
+		AnnotationPattern := '@' AnnotationTypePattern AnnotationPattern* |
+  		                     '!' AnnotationPattern
+        
+        AnnotationTypePattern := FullyQualifiedName |
+                                 '(' TypePattern ')'
+ 
+        === signature patterns ===
+        
+        -- field --
+        
+        FieldPattern := 
+  		    AnnotationPattern? FieldModifiersPattern? 
+  		    TypePattern (TypePattern DotOrDotDot)? SimpleNamePattern
+
+		FieldModifiersPattern := '!'? FieldModifier FieldModifiersPattern*
+		                         		
+		FieldModifier := 'public' | 'private' | 'protected' | 'static' | 
+		                 'transient' | 'final' 
+		            			
+		DotOrDotDot := '.' | '..'
+		
+		SimpleNamePattern := JavaIdentifierChar+ ('*' SimpleNamePattern)?		            
+        
+        -- method --
+        
+        MethodPattern := 
+  		    AnnotationPattern? MethodModifiersPattern? TypePattern 
+  		                       (TypePattern DotOrDotDot)? SimpleNamePattern 
+  		                       '(' FormalsPattern ')' ThrowsPattern?
+
+		MethodModifiersPattern := '!'? MethodModifier MethodModifiersPattern*
+		
+		MethodModifier := 'public' | 'private' | 'protected' | 'static' | 
+		                  'synchronized' | 'final' 
+		            		      
+		FormalsPattern := '..' (',' FormalsPatternAfterDotDot)? |
+		                  OptionalParensTypePattern (',' FormalsPattern)* |
+		                  TypePattern '...'
+		                  
+		FormalsPatternAfterDotDot := 
+		        OptionalParensTypePattern (',' FormalsPatternAfterDotDot)* |
+		        TypePattern '...'
+		                  
+		ThrowsPattern := 'throws' TypePatternList
+		
+		TypePatternList := TypePattern (',' TypePattern)*
+		
+		-- constructor --
+		            					            
+        ConstructorPattern := 
+  		    AnnotationPattern? ConstructorModifiersPattern?  
+  		                       (TypePattern DotOrDotDot)? 'new' '(' FormalsPattern ')'
+  		                       ThrowsPattern?
+	
+		ConstructorModifiersPattern := '!'? ConstructorModifier ConstructorModifiersPattern*
+		
+		ConstructorModifier := 'public' | 'private' | 'protected'
+        
+        === Pointcuts ===
+        
+        PointcutPrimitive := 
+                    Call | Execution | Get | Set | Handler | 
+                    Initialization | PreInitialization |
+                    StaticInitialization | AdviceExecution |
+                    This | Target | Args | CFlow | CFlowBelow |
+                    Within | WithinCode | If |
+                    AnnotationPointcut
+                    
+        AnnotationPointcut := AtAnnotation | AtThis | AtTarget |
+                              AtWithin | AtWithinCode | AtArgs
+                    
+        
+        Call := 'call' '(' MethodOrConstructorPattern ')'
+        
+        MethodOrConstructorPattern := MethodPattern | ConstructorPattern
+        
+        Execution := 'execution' '(' MethodOrConstructorPattern ')'
+        
+        Get := 'get' '(' FieldPattern ')'        
+        Set := 'set' '(' FieldPattern ')'
+        Handler := 'handler' '(' OptionalParensTypePattern ')'
+        Initialization := 'initialization' '(' ConstructorPattern ')'
+        PreInitialization := 'preinitialization' '(' ConstructorPattern ')'
+        StaticInitialization := 'staticinitialization' '(' OptionalParensTypePattern ')'
+        AdviceExecution := 'adviceexecution' '(' ')'
+        This := 'this' '(' TypeOrIdentifier ')'
+        Target := 'target' '(' TypeOrIdentifier ')'
+        Args := 'args' '(' FormalsOrIdentifiersPattern ')'
+        CFlow := 'cflow' '(' Pointcut ')'
+        CFlowBelow := 'cflowbelow' '(' Pointcut ')'
+        Within := 'within' '(' OptionalParensTypePattern ')'
+        WithinCode := 'withincode' '(' OptionalParensTypePattern ')'
+        If := 'if' '(' BooleanJavaExpression ')'
+        
+        TypeOrIdentifier := FullyQualifiedName ('[' ']')* | Identifier
+        Identifier := JavaIdentifierChar+
+        
+        FormalsOrIdentifiersPattern :=
+                          '..' (',' FormalsOrIdentifiersPatternAfterDotDot)? |
+		                  TypeOrIdentifier (',' FormalsOrIdentifiersPattern)* |
+		                  '*' (',' FormalsOrIdentifiersPattern)* 
+		                  
+		FormalsOrIdentifiersPatternAfterDotDot := 
+		                  TypeOrIdentifier (',' FormalsOrIdentifiersPatternAfterDotDot)* |
+		                  '*' (',' FormalsOrIdentifiersPatternAfterDotDot)*
+        
+        AtAnnotation := '@annotation' '(' AnnotationOrIdentifier ')'
+        AtThis := '@this' '(' AnnotationOrIdentifer ')'
+        AtTarget := '@target' '(' AnnotationOrIdentifier ')'
+        AtWithin := '@within' '(' AnnotationOrIdentifier ')'
+        AtWithinCode := '@withincode' '(' AnnotationOrIdentifier ')'        
+        
+        AnnotationOrIdentifier := '@' FullyQualifiedName | Identifier
+        
+        AtArgs := '@args' '(' AnnotationsOrIdentifiersPattern ')'
+        
+        AnnotationsOrIdentifiersPattern :=
+                          '..' (',' AnnotationsOrIdentifiersPatternAfterDotDot)? |
+		                  AnnotationOrIdentifier (',' AnnotationsOrIdentifiersPattern)* |
+		                  '*' (',' AnnotationsOrIdentifiersPattern)*
+		                  
+		AnnotationsOrIdentifiersPatternAfterDotDot := 
+		                  AnnotationOrIdentifier (',' AnnotationsOrIdentifiersPatternAfterDotDot)* |
+		                  '*' (',' AnnotationsOrIdentifiersPatternAfterDotDot)*
+        
+        PointcutDeclaration := PointcutModifiers? 'pointcut' Identifier Formals
+                               ':' PointcutExpression
+                               
+        PointcutModifiers := PointcutModifier*
+        
+        PointcutModifier :=  'public' | 'private' | 'protected' | 'abstract'
+        
+        Formals := '(' ParamList? ')'        
+        ParamList := FullyQualifiedName Identifier (',' ParamList)*
+        
+        ReferencePointcut := (FullyQualifiedName '.')? Identifier Formals
+        
+        PointcutExpression := (PointcutPrimitive | ReferencePointcut) |
+                              '!' PointcutExpression |
+                              '(' PointcutExpression ')' |
+                              PointcutExpression '&&' PointcutExpression |
+                              PointcutExpression '||' PointcutExpression 
+        
+        === Advice ===
+        
+        to be written...
+        
+        === Inter-type Declarations ===
+        
+        to be written...
+        
+        === Declare Statements ===
+        
+        to be written...
+        
+        === Aspects ===
+        
+        to be written...
+        
+      ]]></programlisting>
+
+
 </appendix>
 
diff --git a/docs/adk15ProgGuideDB/joinpointsignatures.xml b/docs/adk15ProgGuideDB/joinpointsignatures.xml
index bded66390..ea702a2f8 100644
--- a/docs/adk15ProgGuideDB/joinpointsignatures.xml
+++ b/docs/adk15ProgGuideDB/joinpointsignatures.xml
@@ -50,20 +50,20 @@
 		    <listitem>The signature pattern (exactly) matches at least one 
 		    signature of the join point</listitem>
 		    <listitem>The modifiers pattern matches the modifiers of the
-		    join point</listitem>
+		    subject of the join point</listitem>
 		</orderedlist>
         
         <para>These rules make it very easily to quickly determine whether a 
         given pointcut matches a given join point. In the next two sections,
         we describe what the signature(s) of a join point are, and what the
-        modifiers of a join point are.</para>
+        subjects of join points are.</para>
         
     </sect1>
   
       <sect1 id="join-point-signatures">
         <title>Join Point Signatures</title>
         
-        <para>Call and execution join points may potentially have multiple
+        <para>Call, execution, get, and set join points may potentially have multiple
         signatures. All other join points have exactly one signature. The
         following table summarizes the constituent parts of a join point
         signature for the different kinds of join point.</para>
@@ -192,14 +192,16 @@
         signature.</para>
         
         <para>The signatures for most of the join point kinds should be
-        self-explanatory, except for method call and execution
+        self-explanatory, except for field get and set, and method call and execution
         join points, which can have multiple signatures. Each signature of 
         a method call or execution join point has the same id and parameter
         types, but the declaring type and return type (with covariance) may vary.
+        Each signature of a field get or set join point has the same id and field
+        type, but the declaring type may vary.
         </para>
         
-        <para>The following sections examine signatures for method call and
-        execution join points in more detail.</para>
+        <para>The following sections examine signatures for these join points 
+        in more detail.</para>
         
         <sect2>
             <title>Method call join point signatures</title>
@@ -322,7 +324,54 @@
         the method.</para>
 
       </sect2>
-      
+
+       <sect2>
+            <title>Field get and set join point signatures</title>
+
+        <para>
+            For a field get join point where an access is made to a field
+            <literal>f</literal> of type <literal>F</literal> 
+            on a object with declared type <literal>T</literal>, then
+            <literal>F T.f</literal> is a signature of the get join point.  
+        </para>
+        
+        <para>
+            If <literal>T</literal> does not directly declare a member
+            <literal>f</literal>, then for each super type <literal>S</literal>
+            of <literal>T</literal>, up to and including the most specific
+            super type of <literal>T</literal> that does declare the member
+            <literal>f</literal>, <literal>F S.f</literal> is a signature
+            of the join point. For example, given the hierarchy:
+        </para>
+
+        <programlisting><![CDATA[        
+        class P  {
+          F f;        
+        }
+        
+        class S extends P {
+          F f;
+        }
+        
+        class T extends S { }                
+		]]></programlisting>
+		
+		<para>
+		    Then the join point signatures for a field get join point of
+		    the field <literal>f</literal> on an object with declared type
+		    <literal>T</literal> are:
+		</para>
+
+        <programlisting><![CDATA[
+        F S.f
+        F T.f
+		]]></programlisting>
+
+        <para>The signatures for a field set join point are derived in an
+            identical manner.</para>
+            
+       </sect2>
+             
       </sect1>
       
       <sect1 id="join-point-modifiers">
@@ -331,73 +380,76 @@
           <para>Every join point has a single set of modifiers - these include
           the standard Java modifiers such as <literal>public, private,
           static, abstract</literal> etc., any annotations, and the throws
-          clauses of methods and constructors.</para>
+          clauses of methods and constructors. These modifiers are the
+          modifiers of the <emphasis>subject</emphasis> of the join point.</para>
           
           <para>
-          For the different join point kinds, the modifiers are:
+          The following table defines the join point subject for each kind
+          of join point.
           </para>
 
-          <informaltable>
+             <informaltable>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Join Point Kind</entry>
-                       <entry>Join Point Modifiers</entry>
+                       <entry>Subject</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>Method call</entry>
-                       <entry>The modifiers of the method picked out by Java as
+                       <entry>The method picked out by Java as
                        the static target of the method call.</entry>
                    </row>
                    <row>
                        <entry>Method execution</entry>
-                       <entry>The modifiers of the method that is executing.</entry>
+                       <entry>The method that is executing.</entry>
                    </row>
                    <row>
                        <entry>Constructor call</entry>
-                       <entry>The modifiers of the constructor being called.</entry>
+                       <entry>The constructor being called.</entry>
                    </row>
                    <row>
                        <entry>Constructor execution</entry>
-                       <entry>The modifiers of the constructor executing.</entry>
+                       <entry>The constructor executing.</entry>
                    </row>
                    <row>
                        <entry>Field get</entry>
-                       <entry>The modifiers of the field being accessed.</entry>
+                       <entry>The field being accessed.</entry>
                    </row>
                    <row>
                        <entry>Field set</entry>
-                       <entry>The modifiers of the field being set.</entry>
+                       <entry>The field being set.</entry>
                    </row>
                    <row>
                        <entry>Pre-initialization</entry>
-                       <entry>The modifiers of the first constructor executing in
+                       <entry>The first constructor executing in
                        this constructor chain.</entry>
                    </row>
                    <row>
                        <entry>Initialization</entry>
-                       <entry>The modifiers of the first constructor executing in
+                       <entry>The first constructor executing in
                        this constructor chain.</entry>
                    </row>
                    <row>
                        <entry>Static initialization</entry>
-                       <entry>The modifiers of the type being initialized.</entry>
+                       <entry>The type being initialized.</entry>
                    </row>
                    <row>
                        <entry>Handler</entry>
-                       <entry>No modifiers.</entry>
+                       <entry>The declared type of the
+                       exception being handled.</entry>
                    </row>
                    <row>
                        <entry>Advice execution</entry>
-                       <entry>The modifiers of the advice being executed.</entry>
+                       <entry>The advice being executed.</entry>
                    </row>
                </tbody>
            </tgroup>
           </informaltable>          
-          
-          <para>For example, given the following types</para>
+
+             <para>For example, given the following types</para>
 
         <programlisting><![CDATA[
         public class X {        
@@ -431,7 +483,7 @@
 		    <listitem>The signature pattern (exactly) matches at least one 
 		    signature of the join point</listitem>
 		    <listitem>The modifiers pattern matches the modifiers of the
-		    join point</listitem>
+		    subject of the join point</listitem>
 		</orderedlist>
 
         <para>Given the hierarchy</para>
diff --git a/docs/adk15ProgGuideDB/varargs.xml b/docs/adk15ProgGuideDB/varargs.xml
index 0fca71dbb..38d0fe24d 100644
--- a/docs/adk15ProgGuideDB/varargs.xml
+++ b/docs/adk15ProgGuideDB/varargs.xml
@@ -75,38 +75,21 @@
             <title>Matching signatures based on variable length argument types</title>
             
             <para>
-            Building on the definition of signature patterns given in the chapter on
-            annotations (<xref linkend="signaturePatterns"/>), <literal>MethodPattern</literal>
+            Recall from the definition of signature patterns given in the chapter on
+            annotations (<xref linkend="signaturePatterns"/>), that <literal>MethodPattern</literal>
             and <literal>ConstructorPattern</literal> are extended to allow a <literal>varargs</literal>
             pattern in the last argument position of a method or constructor signature.
             </para>
             
        	<programlisting><![CDATA[  	
-  		MethodPattern := 
-  		    AnnotationPattern? ModifiersPattern? TypePattern 
-  		                       (TypePattern '.')? SimpleNamePattern '(' FormalsPattern ')'
-  		                       ThrowsPattern?
-
-  		ConstructorPattern := 
-  		    AnnotationPattern? ModifiersPattern?  
-  		                       (TypePattern '.')? 'new' '(' FormalsPattern ')'
-  		                       ThrowsPattern?
-
-		ModifiersPattern := Modifier*
-		
-		Modifier := 'public' | 'private' | 'protected' | 'static' | 
-		            'synchronized' | 'final' 
-		            		      
-		FormalsPattern := TypePattern '...' |
-		                  '..' (',' FormalsPatternAfterDotDot)* |
-		                  OptionalParensTypePattern (',' FormalsPattern)*
+ 		FormalsPattern := '..' (',' FormalsPatternAfterDotDot)? |
+		                  OptionalParensTypePattern (',' FormalsPattern)* |
+		                  TypePattern '...'
 		                  
-		FormalsPatternAfterDotDot := OptionalParensTypePattern (',' FormalsPatternAfterDotDot)*                  
-		                  
-		ThrowsPattern := 'throws' TypePatternList
-		
-		TypePatternList := TypePattern (',' TypePattern)*
-		            					            
+		FormalsPatternAfterDotDot := 
+		        OptionalParensTypePattern (',' FormalsPatternAfterDotDot)* |
+		        TypePattern '...'
+
     	]]></programlisting>
     
             <para>