more updates to 1.5 design

7 files changed, 669 insertions, 142 deletions

diff --git a/docs/adk15ProgGuideDB/adk15notebook.xml b/docs/adk15ProgGuideDB/adk15notebook.xml
index 62f6ca68a..c3ed62924 100644
--- a/docs/adk15ProgGuideDB/adk15notebook.xml
+++ b/docs/adk15ProgGuideDB/adk15notebook.xml
@@ -3,6 +3,7 @@
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                       "../../lib/docbook/docbook-dtd/docbookx.dtd"
 [
+<!ENTITY jpsigs             SYSTEM "joinpointsignatures.xml">
 <!ENTITY annotations        SYSTEM "annotations.xml">
 <!ENTITY generics		    SYSTEM "generics.xml">
 <!ENTITY enumeratedtypes    SYSTEM "enumeratedtypes.xml">
@@ -55,6 +56,7 @@
     </abstract>
   </bookinfo>
 
+  &jpsigs;
   &annotations;
   &generics;
   &enumeratedtypes;
diff --git a/docs/adk15ProgGuideDB/annotations.xml b/docs/adk15ProgGuideDB/annotations.xml
index 48773ac76..30e495c48 100644
--- a/docs/adk15ProgGuideDB/annotations.xml
+++ b/docs/adk15ProgGuideDB/annotations.xml
@@ -639,132 +639,19 @@
 
   </sect2>
 
-  <sect2>
-      <title>Package and Parameter Annotations</title>
-
-      <para>
-          <emphasis>Note: A previous design allowed package annotation patterns to be specified
-          directly in type patterns, and parameter annotation patterns to be
-          specified directly in method and constructor signature patterns. Because
-          this made some pointcut expressions hard to read and understand, we moved
-          in favour of the design presented below, which also has its drawbacks. 
-          Matching on package and parameter annotations is one feature likely to be
-          deferred until after the 1.5.0 release so that we can gain more understanding
-          of the kinds of uses AspectJ users are making of annotations in pointcut
-          expressions before commiting to any one approach.</emphasis>
-      </para>
-      
-      <para>
-          Java 5 allows both packages and parameters to be annotated. To allow matching on package and parameter annotations,
-          AspectJ 1.5 introduces the <literal>@package</literal> and <literal>@parameters</literal> pointcut designators. 
-          <emphasis>Note: we could consider deferring implementation of these to a dot release after 1.5.0?</emphasis>
-      </para>
-      
-  	<programlisting><![CDATA[  	
-  		PackageAnnotationPointcut := '@package' '(' AnnotationPattern ')'
-	]]></programlisting>
-	
-	<para>The <literal>@package</literal> pointcut matches any join point 
-	occuring within the scope of a package with
-	annotations matching the giving <literal>AnnotationPattern</literal>. For
-	example:
-	 </para>
-    
-  	<programlisting><![CDATA[  	
-  		@package(@Model)
-	]]></programlisting>
-    
-    <para>
-        Matches any join point occuring within the scope of a package with the
-        <literal>@Model</literal> annotation.
-    </para>
-    
-    <para>
-    <emphasis>
-        Note: we added @package as a result of a conscious decision not to allow the
-        specification of package annotation patterns within a general TypePattern. A 
-        consequence of this decision is that we lose the ability to say the following
-        things: "a call to a method defined in a type in a package with annotations
-        matching..." ; "the set of a field defined in a type in a package with annotations
-        matching..." ; "the get of a field defined in a type in a package with annotations
-        matching...". As well as the package of the target at these join points, there is
-        also the package of the runtime type of the target (call/target difference). So
-        there are at least three possible sets of package annotations you could theoretically
-        want to match on at a call, get, or set join point. We have chosen to provide the
-        means to express the simplest of these, and could consider extending the language
-        to allow for the others in the future when we better understanding how users will
-        really use both package annotations and these features.
-    </emphasis>
-    </para>  
-    
-    <para>
-        The <literal>@parameter</literal> pointcut designator acts in a similar manner to
-        <literal>args</literal> in that it matches based on number and position of arguments
-        at a join point (and supports the same wildcard options of <literal>*</literal> and
-        <literal>..</literal>.    
-    </para>
-
-  	<programlisting><![CDATA[  	
-  		ParamsAnnotationPointcut := '@parameters' '(' ParamsAnnotationPattern ')'
-  		
-  		ParamsAnnotationPattern := AnnotationPattern (',' ParamsAnnotationPattern)? |
-  		                         '*' (',' ParamsAnnotationPattern)? |
-  		                         '..' (',' SingleParamsAnnotationPattern)* 
-  		
-  		SingleParamsAnnotationPattern := AnnotationPattern (',' SingleParamsAnnotationPattern)? |
-  		                               '*' (',' SingleParamsAnnotationPattern)?  		
-	]]></programlisting>
-    
-    <para>The <literal>*</literal> wildcard matches a single parameter regardless of its annotations. 
-    The <literal>..</literal> wildcard matches zero or more parameters with any annotations. An
-    annotation pattern in a given parameter position matches a parameter in that position with annotations
-    matching the given annotation pattern. For example, the method signature</para>
-
-  	<programlisting><![CDATA[
-  	    public void foo(@Immutable int i, String s, @Cached Object o);  	
-	]]></programlisting>
-
-    <para>
-    Is matched by:
-    </para>
-
-  	<programlisting><![CDATA[
-  	    @parameters(@Immutable, *, @Cached);
-  	    
-  	    and,
-  	    
-  	    @parameters(..,@Cached);
-  	    
-  	    and,
-  	    
-  	    @parameters(@Immutable, *, *); 	
-	]]></programlisting>
+   <sect2>
+  	<title>Runtime type matching and context exposure</title>
 
-    <para>
-     It is not matched by:
+    <para>AspectJ 1.5 supports a set of "@" pointcut designators which
+    can be used both to match based on the presence of an annotation at
+    runtime, and to expose the annotation value as context in a pointcut or
+    advice definition. These designators are <literal>@args, @this, @target,
+    @within, @withincode, @call, @execution, @adviceexecution, @get, @set, 
+    @staticinitialization, @initialization,</literal>, and <literal>@preinitialization</literal>
     </para>
-
-  	<programlisting><![CDATA[
-  	    @parameters(@Immutable, *);
-  	    
-  	    or,
-  	    
-  	    @parameters(*,@Immutable);
-  	    
-  	    or,
-  	    
-  	    @parameters(*, int, @Cached); 	
-	]]></programlisting>
     
-    <para>
-    This last example will result in a compilation error since <literal>int</literal> is not a 
-    valid annotation pattern.
-    </para>
-    
-  </sect2>
-
-   <sect2>
-  	<title>Runtime type matching and context exposure</title>
+    <para>It is a compilation error to attempt to match on an annotation type 
+    that does not have runtime retention using one of these pointcut designators.</para>
 
     <para>
         The <literal>this()</literal>, <literal>target()</literal>, and
@@ -896,7 +783,154 @@
         library to Java 5. A sub-interface and downcast solution could be used
         if these helpers were felt to be sufficiently important.</emphasis>
     </para>
+
+    <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 
+    type. The form of these designators is:
+    </para>
+    
+  	<programlisting><![CDATA[  	
+  		WithinAnnotation := '@within' '(' AnnotationNameOrVar ')'
+  		
+  		WithinCodeAnnotation := '@withincode' '(' AnnotationNameOrVar ')'
+    ]]></programlisting>  		
+
+    <para>Some examples of using these designators follow:</para>
+
+   <variablelist>
+
+        <varlistentry>
+          <term>@within(@Foo)</term>
+          <listitem>
+            <para>
+            	Matches any join point where the enclosing type
+            	has an annotation of type <literal>Foo</literal>.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>pointcut insideCriticalMethod(Critical c) : 
+                  @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>,
+            	and exposes the value of the annotation in the parameter 
+            	<literal>c</literal>.
+            </para>
+          </listitem>
+        </varlistentry>
+
+    </variablelist>
     
+    <para>The remaining annotation-based pointcut designators are defined in a 
+    similar fashion:</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 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 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>
+
     <para>
       Access to annotation information on members at a matched join point is available
       through the <literal>getSignature</literal> method of the <literal>JoinPoint</literal>
@@ -922,18 +956,134 @@
         to Java 5.</emphasis>
     </para>
     
+  </sect2>
+
+  <sect2>
+      <title>Package and Parameter Annotations</title>
+
+      <para>
+          <emphasis>Note: A previous design allowed package annotation patterns to be specified
+          directly in type patterns, and parameter annotation patterns to be
+          specified directly in method and constructor signature patterns. Because
+          this made some pointcut expressions hard to read and understand, we moved
+          in favour of the design presented below, which also has its drawbacks. 
+          Matching on package and parameter annotations is one feature likely to be
+          deferred until after the 1.5.0 release so that we can gain more understanding
+          of the kinds of uses AspectJ users are making of annotations in pointcut
+          expressions before commiting to any one approach.</emphasis>
+      </para>
+      
+      <para>
+          Java 5 allows both packages and parameters to be annotated. To allow matching on package and parameter annotations,
+          AspectJ 1.5 introduces the <literal>@package</literal> and <literal>@parameters</literal> pointcut designators. 
+          <emphasis>Note: we could consider deferring implementation of these to a dot release after 1.5.0?</emphasis>
+      </para>
+      
+  	<programlisting><![CDATA[  	
+  		PackageAnnotationPointcut := '@package' '(' AnnotationPattern ')'
+	]]></programlisting>
+	
+	<para>The <literal>@package</literal> pointcut matches any join point 
+	occuring within the scope of a package with
+	annotations matching the giving <literal>AnnotationPattern</literal>. For
+	example:
+	 </para>
+    
+  	<programlisting><![CDATA[  	
+  		@package(@Model)
+	]]></programlisting>
+    
+    <para>
+        Matches any join point occuring within the scope of a package with the
+        <literal>@Model</literal> annotation.
+    </para>
+    
+    <para>
+    <emphasis>
+        Note: we added @package as a result of a conscious decision not to allow the
+        specification of package annotation patterns within a general TypePattern. A 
+        consequence of this decision is that we lose the ability to say the following
+        things: "a call to a method defined in a type in a package with annotations
+        matching..." ; "the set of a field defined in a type in a package with annotations
+        matching..." ; "the get of a field defined in a type in a package with annotations
+        matching...". As well as the package of the target at these join points, there is
+        also the package of the runtime type of the target (call/target difference). So
+        there are at least three possible sets of package annotations you could theoretically
+        want to match on at a call, get, or set join point. We have chosen to provide the
+        means to express the simplest of these, and could consider extending the language
+        to allow for the others in the future when we better understanding how users will
+        really use both package annotations and these features.
+    </emphasis>
+    </para>  
+    
+    <para>
+        The <literal>@parameter</literal> pointcut designator acts in a similar manner to
+        <literal>args</literal> in that it matches based on number and position of arguments
+        at a join point (and supports the same wildcard options of <literal>*</literal> and
+        <literal>..</literal>.    
+    </para>
+
+  	<programlisting><![CDATA[  	
+  		ParamsAnnotationPointcut := '@parameters' '(' ParamsAnnotationPattern ')'
+  		
+  		ParamsAnnotationPattern := AnnotationPattern (',' ParamsAnnotationPattern)? |
+  		                         '*' (',' ParamsAnnotationPattern)? |
+  		                         '..' (',' SingleParamsAnnotationPattern)* 
+  		
+  		SingleParamsAnnotationPattern := AnnotationPattern (',' SingleParamsAnnotationPattern)? |
+  		                               '*' (',' SingleParamsAnnotationPattern)?  		
+	]]></programlisting>
+    
+    <para>The <literal>*</literal> wildcard matches a single parameter regardless of its annotations. 
+    The <literal>..</literal> wildcard matches zero or more parameters with any annotations. An
+    annotation pattern in a given parameter position matches a parameter in that position with annotations
+    matching the given annotation pattern. For example, the method signature</para>
+
+  	<programlisting><![CDATA[
+  	    public void foo(@Immutable int i, String s, @Cached Object o);  	
+	]]></programlisting>
+
+    <para>
+    Is matched by:
+    </para>
+
+  	<programlisting><![CDATA[
+  	    @parameters(@Immutable, *, @Cached);
+  	    
+  	    and,
+  	    
+  	    @parameters(..,@Cached);
+  	    
+  	    and,
+  	    
+  	    @parameters(@Immutable, *, *); 	
+	]]></programlisting>
+
+    <para>
+     It is not matched by:
+    </para>
+
+  	<programlisting><![CDATA[
+  	    @parameters(@Immutable, *);
+  	    
+  	    or,
+  	    
+  	    @parameters(*,@Immutable);
+  	    
+  	    or,
+  	    
+  	    @parameters(*, int, @Cached); 	
+	]]></programlisting>
+    
     <para>
-        <emphasis>Note: the use case of matching call/execution/get/set join points based
-        on member annotations is expected to be a common one. If it is also common 
-        practice to want to access the annotation value in the advice body, then the
-        route via thisJoinPointStaticPart and the Signature interface will be too
-        cumbersome. In this case we need to find a form of context-exposing pcd
-        that will allow the annotation value to be directly exposed as an advice
-        parameter. What form should this take, and what join points should it match?
-        </emphasis>
+    This last example will result in a compilation error since <literal>int</literal> is not a 
+    valid annotation pattern.
     </para>
+    
   </sect2>
 
+
+
   <sect2>
   	<title>Annotation Inheritance and pointcut matching</title>
   	
diff --git a/docs/adk15ProgGuideDB/autoboxing.xml b/docs/adk15ProgGuideDB/autoboxing.xml
index 5a3c454ad..ded805fb0 100644
--- a/docs/adk15ProgGuideDB/autoboxing.xml
+++ b/docs/adk15ProgGuideDB/autoboxing.xml
@@ -2,5 +2,26 @@
 
   <title>Autoboxing and Unboxing</title>
   
+      <sect1 id="boxing-inJava5">
+        <title>Autoboxing and Unboxing in Java 5</title>
+        
+        <para>
+          Java 5 (and hence AspectJ 1.5) ... . For example:
+        </para>
+
+		<programlisting><![CDATA[
+		]]></programlisting>
+        
+      </sect1>
+      
+      <sect1>
+          <title>Autoboxing and Join Point matching in AspectJ 1.5</title>
+      </sect1>
+      
+      <sect1>
+          <title>Inter-type method declarations and method dispatch</title>
+      </sect1>
+      
+  
 </chapter>
 
diff --git a/docs/adk15ProgGuideDB/covariance.xml b/docs/adk15ProgGuideDB/covariance.xml
index d182e157e..4e1e2f8de 100644
--- a/docs/adk15ProgGuideDB/covariance.xml
+++ b/docs/adk15ProgGuideDB/covariance.xml
@@ -2,5 +2,179 @@
 
   <title>Covariance</title>
   
+      <sect1 id="covariance-inJava5">
+        <title>Covariance in Java 5</title>
+        
+        <para>
+          Java 5 (and hence AspectJ 1.5) allows you to narrow the return type
+          in an overriding method. For example:
+        </para>
+
+		<programlisting><![CDATA[
+		class A {
+		  public A whoAreYou() {...}
+		}
+		
+		class B extends A {
+		  // override A.whoAreYou *and* narrow the return type.
+		  public B whoAreYou() {...}
+		}
+		]]></programlisting>
+        
+      </sect1>
+      
+      <sect1>
+          <title>Covariant methods and Join Point matching</title>
+          
+          <para>The join point matching rules for <literal>call</literal>
+          and <literal>execution</literal> pointcut designators are extended
+          to match against covariant methods.</para>
+          
+          <para>
+              Given the classes <literal>A</literal> and <literal>B</literal>
+              as defined in the previous section, and the program fragment
+          </para>
+
+		<programlisting><![CDATA[
+		A a = new A();
+		B b = new B();
+		a.whoAreYou();
+		b.whoAreYou();
+		]]></programlisting>
+		
+		<para>Then the call and execution join points for <literal>whoAreYou</literal>
+		are matched as follows:</para>
+		
+		<variablelist>
+
+        <varlistentry>
+          <term>call(* whoAreYou())</term>
+          <listitem>
+            <para>Matches both calls, (since it places no constraint on the
+                return type of the join point signature).
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>call(* A.whoAreYou())</term>
+          <listitem>
+            <para>Matches both calls, (since the original declaring type
+            of <literal>whoAreYou</literal> is <literal>A</literal>).
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>call(A whoAreYou())</term>
+          <listitem>
+            <para>Matches both calls, (since the signature of 
+            <literal>whoAreYou</literal>) in the original declaring type
+            has a return type of <literal>A</literal>).
+            </para>
+          </listitem>
+        </varlistentry>
+		
+        <varlistentry>
+          <term>call(A B.whoAreYou())</term>
+          <listitem>
+            <para>Does not match anything - the signature of <literal>whoAreYou</literal>
+            as overriden in <literal>B</literal> has a return type of
+            <literal>B</literal>, not <literal>A</literal>.  A lint warning is
+            given for the call <literal>a.whoAreYou()</literal> ("does not match
+            because declaring type is A, if match required use target(B)").
+            </para>
+          </listitem>
+        </varlistentry>
+		
+        <varlistentry>
+          <term>call(A+ B.whoAreYou())</term>
+          <listitem>
+            <para>Matches the call to <literal>b.whoAreYou()</literal> since
+            the return type <literal>B</literal> in the method signature
+            is matched by the type pattern <literal>A+</literal>. A lint warning is
+            given for the call <literal>a.whoAreYou()</literal> ("does not match
+            because declaring type is A, if match required use target(B)").
+            </para>
+          </listitem>
+        </varlistentry>
+				
+        <varlistentry>
+          <term>call(B A.whoAreYou())</term>
+          <listitem>
+            <para>Does not match anything - there is no method declared in 
+                <literal>A</literal> with a return type of <literal>B</literal>.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>call(B whoAreYou())</term>
+          <listitem>
+            <para>Matches the call to <literal>b.whoAreYou()</literal> only.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>call(B B.whoAreYou())</term>
+          <listitem>
+            <para>Matches the call to <literal>b.whoAreYou()</literal> only.
+            </para>
+          </listitem>
+        </varlistentry>
+
+		</variablelist>
+		
+		<para>The rule for signature matching at call and execution join points
+		is unchanged from AspectJ 1.2: a call or execution pointcut matches if
+		the signature pattern matches at least one of the signatures of the
+		join point, and if the most-specific matched signature is also matched
+		by any modifier pattern or annotation pattern that may be present.</para>
+		
+		<para>For a call or execution join point, the signatures of a join point
+		for the call or execution of a method <literal>Rtype T.m(params)</literal>
+		are determined as follows:</para>
+		<itemizedlist>
+		    <listitem>
+		    If <literal>m(params)</literal> is defined in <literal>T</literal>, 
+		    then the signature of <literal>m(params)</literal> in <literal>T</literal> is 
+		    a signature of the join point: <literal>Rtype T.m(params)</literal>. 
+		    If <literal>T</literal> does not
+		    provide its own definition of <literal>m</literal>, then the signature 
+		    <literal>Rtype' T.m(params)</literal>
+		    is a signature of the join point, where <literal>Rtype'</literal> is the return type of
+		    the definition of <literal>m</literal> inherited by <literal>T</literal>.
+            </listitem>
+            <listitem>
+            For each super-type <literal>S</literal> of <literal>T</literal> that is a valid receiver
+            for a call to <literal>m</literal>, then the signature of <literal>m(params)</literal> in 
+            <literal>S</literal> is a signature
+            of the join point: <literal>Rtype S.m(params)</literal>. 
+            If <literal>S</literal> does not provide its
+            own definition of <literal>m</literal>, then the signature 
+            <literal>Rtype' S.m(params)</literal> is a 
+            signature of the join point, where <literal>Rtype'</literal> is the return type of the
+            definition of <literal>m</literal> inherited by <literal>S</literal>.
+            </listitem>
+		</itemizedlist>
+		
+        <para>A call to <literal>b.whoAreYou()</literal> has the join point signatures
+        </para>
+        
+        <itemizedlist>           
+            <listitem>B B.whoAreYou()</listitem>
+            <listitem>A A.whoAreYou()</listitem>
+        </itemizedlist>          
+        
+        <para>Following the rule given, it is easy to see why for example
+        <literal>call(B A.whoAreYou())</literal> does not match anything as 
+        this pattern matches neither of the signatures at the join point. In 
+        contrast, the pointcut expression <literal>call(A+ B.whoAreYou())</literal>
+        does match the call to <literal>b.whoAreYou()</literal> because it matches
+        the second of the signatures at the join point.</para>
+      </sect1>
+      
+  
 </chapter>
 
diff --git a/docs/adk15ProgGuideDB/joinpointsignatures.xml b/docs/adk15ProgGuideDB/joinpointsignatures.xml
new file mode 100644
index 000000000..0c3473034
--- /dev/null
+++ b/docs/adk15ProgGuideDB/joinpointsignatures.xml
@@ -0,0 +1,131 @@
+<chapter id="jpsigs" xreflabel="Join Point Signatures">
+
+  <title>Join Point Signatures</title>
+  
+      <para>To understand join point matching for annotations, generics, and
+      covariance, it is first necessary to understand the concepts of
+      join point signatures and join point signature matching, for call and
+      execution join points.</para>
+  
+      <sect1>
+        <title>Join Point Signatures for Call Join Points</title>
+        
+        <para>A call join point can have more than one signature. For a
+        call pointcut expression to match a given call join point, at
+        least one of the join point signatures must be matched by the
+        pointcut's signature pattern.</para>
+        
+        <para>
+          For a call join point where a call is made to a method
+          <literal>m(args)</literal> on a target type <literal>T</literal> (where
+          <literal>T</literal> is the static type of the target):
+        </para>
+
+		<programlisting><![CDATA[
+		T t = new T(); 
+		t.m("hello");  <= call join point occurs when this line is executed
+		]]></programlisting>
+        
+        <para>
+            Then the signature <literal>R(T) T.m(args)</literal> is a signature
+            of the call join point, where <literal>R(T)</literal> is the return
+            type of <literal>m</literal> in <literal>T</literal>, and 
+            <literal>args</literal> represents the types of the arguments to
+            <literal>m</literal>. If <literal>T</literal> itself does not
+            declare a definition of <literal>m(args)</literal>, then 
+            <literal>R(T)</literal> is the return type in the definition of 
+            <literal>m</literal> that <literal>T</literal> inherits. Given the
+            call above, and the definition of <literal>T.m</literal>:                      
+        </para>
+        
+        <programlisting><![CDATA[
+        interface Q {
+          R m(String s);
+        }
+        
+        class P implements Q {
+          R m(String s) {...}        
+        }
+        
+        class S extends P {
+          R' m(String s) {...}
+        }
+        
+		class T extends S { 
+		
+		]]></programlisting>
+        
+        <para>Then <literal>R' T.m(String)</literal> is a signature of the
+        call join point for <literal>t.m("hello")</literal></para>.
+        
+        <para>
+            For each ancestor (super-type) <literal>A</literal> of <literal>T</literal>, 
+            if <literal>m(args)</literal> is defined for that super-type, then
+            <literal>R(A) A.m(args)</literal> is a signature of the call join
+            point, where <literal>R(A)</literal> is the return type of <literal>
+            m(args)</literal> as defined in <literal>A</literal>, or as inherited
+            by <literal>A</literal> if <literal>A</literal> itself does not
+            provide a definition of <literal>m(args)</literal>.            
+        </para>
+        
+        <para>
+            Continuing the example from above,we can deduce that
+        </para>
+
+        <programlisting><![CDATA[
+        R' S.m(String)
+        R  P.m(String)
+        R  Q.m(String)
+		]]></programlisting>
+        
+        <para>are all additional signatures for the call join point arising
+        from the call <literal>t.m("hello")</literal>. Thus the call
+        join point has four signatures in total. Amongst these signatures,
+        we say that the <emphasis>most-specific signature</emphasis> is the
+        signature with the most-specific declaring type - that is, the 
+        signature of the static type of the target of the call 
+        (<literal>R' T.m(String)</literal>) in this case.</para>
+        
+      </sect1>
+      
+      <sect1>
+          <title>Join Point Signatures for Execution Join Points</title>
+          
+          <para>Join point signatures for execution join points are defined
+          in a similar manner to signatures for call join points. Given the
+          same hierarchy as in the call example in the previous section:
+          </para>
+
+
+        <programlisting><![CDATA[
+        interface Q {
+          R m(String s);
+        }
+        
+        class P implements Q {
+          R m(String s) {...}        
+        }
+        
+        class S extends P {
+          R' m(String s) {...}
+        }
+        
+		class T extends S { 
+		
+		]]></programlisting>
+        
+        <para>Then the execution join point signatures arising as a result
+        of the call to <literal>t.m("hello")</literal> are: </para>
+
+
+      </sect1>
+      
+      <sect1>
+          <title>Pointcut matching based on Join Point Signatures</title>
+          
+          <para>Explain signature + modifiers split, plus notion of "most-specific"
+          join point.</para>
+      </sect1>
+      
+  
+</chapter>
diff --git a/docs/adk15ProgGuideDB/pertypewithin.xml b/docs/adk15ProgGuideDB/pertypewithin.xml
index 5f5b8fd66..e870f10e5 100644
--- a/docs/adk15ProgGuideDB/pertypewithin.xml
+++ b/docs/adk15ProgGuideDB/pertypewithin.xml
@@ -2,5 +2,19 @@
 
   <title>The pertypewithin Aspect Instantiation Model</title>
   
+  <para>This is a placeholder to stimulate discussion around a possible new
+  instantiation model : <literal>pertypewithin(OptionalParensTypePattern)</literal>.
+  The semantics of <literal>pertypewithin</literal> are that a new aspect
+  instance will be created at the <literal>staticinitialization</literal>
+  join point of each type matching the given type pattern.</para>
+  
+  <para>Discussion must include motivating use cases. Raise the issue that
+  pertypewithin takes a type pattern, not a pointcut.</para>
+  
+  <para>We will only do this if we believe we can generate an implementation
+  that is significantly more efficient than hand-coded alternatives.</para>
+
+  <para>Need to define aspectOf(Class), hasAspect(Class).</para>
+  
 </chapter>
 
diff --git a/docs/adk15ProgGuideDB/varargs.xml b/docs/adk15ProgGuideDB/varargs.xml
index 91a389b52..ceadfed05 100644
--- a/docs/adk15ProgGuideDB/varargs.xml
+++ b/docs/adk15ProgGuideDB/varargs.xml
@@ -2,7 +2,7 @@
 
   <title>Varargs</title>
   
-    <sect1 id="varargs-inJava5">
+    <sect1 id="varargs-inJava5" xreflabel="Varargs in Java 5">
         <title>Variable-length Argument Lists in Java 5</title>
         
         <para>
@@ -169,21 +169,56 @@
             <literal>execution(* *.*(String[]))</literal> matches the execution join point
             for <literal>bar</literal> but not <literal>foo</literal>.
         </para>
-        
-        <para>
-            The <literal>args</literal> pointcut designator can also now take a <literal>varargs</literal>
-            pattern as the last argument in the list. For example, you can write:
-        </para>
-
-    	<programlisting><![CDATA[
-    	args(int, String...)
-    	]]></programlisting>
-        
+               
         </sect2>
         
         <sect2>
             <title>Exposing variable-length arguments as context in pointcuts and advice</title>
+            
+            <para>
+            When a varargs parameter is used within the body of a method, it has
+            an array type, as discussed in the introduction to this section. We follow the
+            same convention when binding a varargs parameter via the <literal>args</literal>
+            pointcut designator. Given a method
+            </para>
+
+		<programlisting><![CDATA[
+		public void foo(int i, String... strings) { 
+		}
+		]]></programlisting>
+
+            <para>
+            The call or execution join points for <literal>foo</literal> will be matched
+            by the pointcut <literal>args(int,String[])</literal>. It is not permitted
+            to use the varargs syntax within an args pointcut designator - so you
+            <emphasis>cannot</emphasis> write <literal>args(int,String...)</literal>.
+            </para>
+            
+            <para>
+            Binding of a varargs parameter in an advice statement is straightforward:
+            </para>
+            
+		<programlisting><![CDATA[
+		before(int i, String[] ss) : call(* foo(int,String...)) && args(i,ss) {
+		  // varargs String... argument is accessible in advice body through ss
+		  // ...
+		}
+		]]></programlisting>
+         
+             <para>Since you cannot use the varargs syntax in the <literal>args</literal>
+             pointcut designator, you also cannot use the varargs syntax to declare
+             advice parameters.</para>   
+            
+            <para>Note: the proposal in this section does not allow you to 
+            distinguish between a join point with a signature (int, String...)
+            and a join point with a signature (int, String[]) based 
+            <emphasis>solely</emphasis> on the use of the <literal>args</literal>
+            pointcut designator. If this distinction is required, <literal>args</literal>
+            can always be coupled with <literal>call</literal> or 
+            <literal>execution</literal>.</para>
+
         </sect2>
+        
     </sect1>
   
 </chapter>