From: acolyer Date: Tue, 16 Nov 2004 21:09:38 +0000 (+0000) Subject: updated for new annotations style X-Git-Tag: Root_AspectJ5_Development~249 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=5b313c381fdf2800b31a52b0e14819a2f5c74488;p=aspectj.git updated for new annotations style --- 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 @@ + @@ -39,6 +40,16 @@ If you are new to AspectJ, we recommend you start by reading the programming guide. + + + This is a draft document and is subject to change 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. + @@ -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 @@ Package and Parameter Annotations + + + 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. + Java 5 allows both packages and parameters to be annotated. To allow matching on package and parameter annotations, @@ -855,10 +867,76 @@ @args(*,*,untrustedDataSource); ]]> - TODO: We need to extend org.aspectj.lang.JoinPoint too. It would be - nice to use the AnnotatedElement 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). + + 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. + + + Access to AnnotatedElement information is available + reflectively with the body of advice through the thisJoinPoint, + thisJoinPointStaticPart, and + thisEnclosingJoinPointStaticPart variables. To access + annotations on the arguments, or object bound to this or target at a join + point you can use the following code fragments: + + + + + 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. + + + + Access to annotation information on members at a matched join point is available + through the getSignature method of the JoinPoint + and JoinPoint.StaticPart interfaces. The MemberSignature + interface is extended with the additional operation + java.lang.reflect.Member getMember(). The following fragment + illustrates an example use of this interface to access annotation information. + + + + + + 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. + + + + 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? + + 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 @@ + + + Pointcut Expressions + + + 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). + + + +