updated for new annotations style

3 files changed, 108 insertions, 4 deletions

diff --git a/docs/adk15ProgGuideDB/adk15notebook.xml b/docs/adk15ProgGuideDB/adk15notebook.xml
index 401fc3d9b..232002dc0 100644
--- a/docs/adk15ProgGuideDB/adk15notebook.xml
+++ b/docs/adk15ProgGuideDB/adk15notebook.xml
@@ -9,6 +9,7 @@
 <!ENTITY autoboxing         SYSTEM "autoboxing.xml">
 <!ENTITY covariance         SYSTEM "covariance.xml">
 <!ENTITY varargs            SYSTEM "varargs.xml">
+<!ENTITY pointcutexp        SYSTEM "pointcutexp.xml">
 <!ENTITY pertypewithin      SYSTEM "pertypewithin.xml">
 <!ENTITY getthistargetobj   SYSTEM "getthistargetobj.xml">
 <!ENTITY declaresoft        SYSTEM "declaresoft.xml">
@@ -39,6 +40,16 @@
         If you are new to AspectJ, we recommend you start 
         by reading the programming guide.
       </para>
+      
+      <para>
+         This is a draft document and is <emphasis>subject to change</emphasis> before
+         the design and implementation is complete. There is also no guarantee that all
+         of the features in this document will be implemented in a 1.5.0 release - some
+         may be deferred until 1.5.1 or even later. In general, features in which we
+         have more confidence in the design will be implemented earlier, providing a 
+         framework for user feedback and direction setting on features for which the
+         use cases are less obvious at time of writing.
+      </para>
 
     </abstract>
   </bookinfo>
@@ -49,6 +60,7 @@
   &autoboxing;
   &covariance;
   &varargs;
+  &pointcutexp;
   &pertypewithin;
   &getthistargetobj;
   &declaresoft;
diff --git a/docs/adk15ProgGuideDB/annotations.xml b/docs/adk15ProgGuideDB/annotations.xml
index 872e7fa10..285746a64 100644
--- a/docs/adk15ProgGuideDB/annotations.xml
+++ b/docs/adk15ProgGuideDB/annotations.xml
@@ -641,6 +641,18 @@
 
   <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,
@@ -855,10 +867,76 @@
   	    @args(*,*,untrustedDataSource);
 	]]></programlisting>
 
-    <para>TODO: We need to extend org.aspectj.lang.JoinPoint too. It would be
-    nice to use the <literal>AnnotatedElement</literal> interface, but this would
-    create a hard 1.5 dependency in our runtime library and I don't think we want
-    to do that (or certainly not do it lightly).</para>
+    <para>
+        <emphasis>Note: an alternative design would be to allow both annotation
+        patterns and type patterns to be specified in the existing args pcd.
+        This works well for matching, but is more awkward when it comes to
+        exposing context.</emphasis>
+    </para>
+
+    <para>Access to <literal>AnnotatedElement</literal> information is available
+    reflectively with the body of advice through the <literal>thisJoinPoint</literal>,
+    <literal>thisJoinPointStaticPart</literal>, and 
+    <literal>thisEnclosingJoinPointStaticPart</literal> variables. To access 
+    annotations on the arguments, or object bound to this or target at a join
+    point you can use the following code fragments:</para>
+
+  	<programlisting><![CDATA[
+  	Annotation[] thisAnnotations = thisJoinPoint.getThis().getClass().getAnnotations();
+  	Annotation[] targetAnnotations = thisJoinPoint.getTarget().getClass().getAnnotations();
+  	Annotation[] firstParamAnnotations = thisJoinPoint.getArgs()[0].getClass().getAnnotations();
+	]]></programlisting>
+
+    <para>
+        <emphasis>Note: it would be nicer to provide direct helper methods in
+        the JoinPoint interface or a sub-interface that provide the annotations
+        directly, something like "AnnotatedElement getThisAnnotationInfo()".
+        The problem here is that the "AnnotatedElement" type is only in the
+        Java 5 runtime libraries, and we don't want to tie the AspectJ runtime
+        library to Java 5. A sub-interface and downcast solution could be used
+        if these helpers were felt to be sufficiently important.</emphasis>
+    </para>
+    
+    <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>
+      and <literal>JoinPoint.StaticPart</literal> interfaces. The <literal>MemberSignature</literal>
+      interface is extended with the additional operation 
+      <literal>java.lang.reflect.Member getMember()</literal>. The following fragment
+      illustrates an example use of this interface to access annotation information.
+    </para>
+
+  	<programlisting><![CDATA[
+  	Signature sig = thisJoinPointStaticPart.getSignature();
+  	AnnotatedElement declaringTypeAnnotationInfo = sig.getDeclaringType();
+  	if (sig instanceof MemberSignature) {
+  	  // this must be an initialization, pre-initialization, call, execution, get, or
+  	  // set join point.
+  	  Member member = ((MemberSignature)sig).getMember();
+  	  // unfortunately, Member does not extend AnnotatedElement, so a further cast is
+  	  // needed:
+  	  if (member instanceof Field) { // a set or get join point...
+  	      AnnotatedElement fieldAnnotationInfo = ((Field)member);
+  	  }
+  	}
+	]]></programlisting>
+    
+    <para>
+        <emphasis>Note again that it would be nicer to add the method getAnnotationInfo
+        directly to MemberSignature, but this would once more couple the runtime library
+        to Java 5.</emphasis>
+    </para>
+    
+    <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>
+    </para>
   </sect2>
 
   <sect2>
diff --git a/docs/adk15ProgGuideDB/pointcutexp.xml b/docs/adk15ProgGuideDB/pointcutexp.xml
new file mode 100644
index 000000000..be0bddcee
--- /dev/null
+++ b/docs/adk15ProgGuideDB/pointcutexp.xml
@@ -0,0 +1,14 @@
+<chapter id="pointcutexp" xreflabel="Pointcut Expressions">
+
+  <title>Pointcut Expressions</title>
+  
+  <para>
+    Discuss detection of common errors -> warning/error, eg. conjunction of more than one
+    kind of join point. Differing numbers of args in method signature / args / @args /
+    @parameters. Binding of formals (cannot bind same formal more than once in a conjunction, 
+    can bind exactly once in each branch of a disjunction, iff the branches are mutually
+    exclusive based on e.g. join point kind).     
+  </para>
+  
+</chapter>
+