From 4fe2028e62f2fc77798eab5551f341f6b584dbde Mon Sep 17 00:00:00 2001 From: acolyer Date: Mon, 19 Dec 2005 16:53:15 +0000 Subject: [PATCH] doc updates from RB_V1_5_0 --- docs/adk15ProgGuideDB/adk15notebook.xml | 17 +--- docs/adk15ProgGuideDB/annotations.xml | 98 +++++++++-------------- docs/adk15ProgGuideDB/ataspectj.xml | 100 +++++++++--------------- docs/adk15ProgGuideDB/generics.xml | 4 - docs/adk15ProgGuideDB/ltw.xml | 3 +- docs/adk15ProgGuideDB/miscellaneous.xml | 24 +----- docs/adk15ProgGuideDB/reflection.xml | 19 ++++- docs/devGuideDB/ajc.xml | 6 +- 8 files changed, 100 insertions(+), 171 deletions(-) diff --git a/docs/adk15ProgGuideDB/adk15notebook.xml b/docs/adk15ProgGuideDB/adk15notebook.xml index 42f0b5143..4f8a131b7 100644 --- a/docs/adk15ProgGuideDB/adk15notebook.xml +++ b/docs/adk15ProgGuideDB/adk15notebook.xml @@ -37,23 +37,13 @@ This guide describes the changes to the AspectJ language - and tools in AspectJ 5. These include support for Java 5 (Tiger) features, - enhancements to load-time weaving, an support for an annotation-based - development style for aspects. + in AspectJ 5. These include support for Java 5 (Tiger) features, + support for an annotation-based development style for aspects, + and new reflection and tools APIs. 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. - - @@ -69,6 +59,5 @@ &reflection; &miscellaneous; <w; - &grammar; diff --git a/docs/adk15ProgGuideDB/annotations.xml b/docs/adk15ProgGuideDB/annotations.xml index f0eb7de7d..073312706 100644 --- a/docs/adk15ProgGuideDB/annotations.xml +++ b/docs/adk15ProgGuideDB/annotations.xml @@ -311,21 +311,9 @@ 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. Annotation patterns are defined by the following - grammar. - - - - - In simple terms, an annotation pattern element has one of two basic - forms: + on the annotated element.An annotation pattern element has one of two basic + forms: + @<qualified-name>, for example, @Foo, or @@ -406,7 +394,7 @@ Type Patterns AspectJ 1.5 extends type patterns to allow an optional AnnotationPattern - prefix. (Extensions to this definition for generics are shown in the next chapter). + prefix. Note that in most cases when annotations are used as part of a type pattern, the parenthesis are required (as in (@Foo Hello+)). In - some cases (such as a type pattern used within a this - pointcut expression, the parenthesis are optional: + some cases (such as a type pattern used within a within or + handler + pointcut expression), the parenthesis are optional: Signature Patterns - A FieldPattern is described by the following - grammar: + + Field Patterns + A FieldPattern can optionally specify an annotation-matching + pattern as the first element: + - The optional AnnotationPattern restricts matches to fields with + If present, the AnnotationPattern restricts matches to fields with annotations that match the pattern. For example: @@ -604,7 +596,13 @@ - A MethodPattern is of the form + + + + Method and Constructor Patterns + + A MethodPattern can optionally specify an annotation-matching + pattern as the first element. - Note: compared to the previous version, this definition of MethodPattern does - not allow parameter annotation matching (only matching on annotations of parameter types). A ConstructorPattern has the form @@ -687,6 +683,8 @@ + + @@ -886,14 +884,8 @@ @args(*,*,untrustedDataSource); ]]> - - 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 + In addition to accessing annotation information at runtime through context binding, + access to AnnotatedElement information is also available reflectively with the body of advice through the thisJoinPoint, thisJoinPointStaticPart, and thisEnclosingJoinPointStaticPart variables. To access @@ -906,16 +898,6 @@ Annotation[] firstParamAnnotations = thisJoinPoint.getArgs()[0].getClass().getAnnotations(); ]]> - - 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. - - The @within and @withincode pointcut designators match any join point where the executing code is defined within a type (@within), @@ -1009,15 +991,9 @@ 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 will 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. + Matching on package and parameter annotations is not supported + in AspectJ 1.5.0. Support for this capability may be considered in a future + release. @@ -1189,17 +1165,19 @@ - - Limitations + + Matching based on annotation values - It would be useful to be able to match join points based on - annotation values, rather than merely the presence of a - class-file retention annotation of a given type. This facility may be supported in a future version of AspectJ, by expanding the - definition of AnnotationPattern. Matching annotation values for - annotations with runtime retention can be done by exposing the annotation value - as a pointcut parameter and then using an if pointcut expression - to test the value. + The if pointcut designator can be used to write pointcuts + that match based on the values annotation members. For example: + + + diff --git a/docs/adk15ProgGuideDB/ataspectj.xml b/docs/adk15ProgGuideDB/ataspectj.xml index dc614e3d3..216418f31 100644 --- a/docs/adk15ProgGuideDB/ataspectj.xml +++ b/docs/adk15ProgGuideDB/ataspectj.xml @@ -52,13 +52,6 @@ public aspect Foo {} ]]> - And since issingleton() is the default aspect instantiation model it is equivalent to: - - - To specify an aspect an aspect instantiation model (the default is singleton), provide the perclause as the @Aspect @@ -167,8 +160,9 @@ pointcut anyCall(int i, Foo callee) : call(* *.*(int)) && args(i) && target(callee); ]]> - An example with modifiers (it is also good to remember that Java 5 annotations are not - inherited): + An example with modifiers (Remember that Java 5 annotations are not + inherited, so the @Pointcut annotation must be + present on the extending aspect's pointcut declaration too): - When using the annotation style, it would be really a pain to write a valid Java expression within - the annotation value so the syntax differs sligthly, whilst providing the very same + When using the annotation style, it is not possible to write a full Java expression + within + the annotation value so the syntax differs slightly, whilst providing the very same semantics and runtime behaviour. An if() pointcut expression can be declared in an @Pointcut - , but must either an empty body, or be one - of the expression + , but must have either an empty body (if(), or be one + of the expression forms if(true) or if(false) @@ -634,13 +629,14 @@ Inter-type declarations are challenging to support using an annotation style. - It's very important to preserve the exact same semantics between the code style + It's very important to preserve the same semantics between the code style and the annotation style. We also want to support compilation of a large set - of AspectJ applications using a standard Java 5 compiler. For these reasons, in - the initial release of AspectJ 5 we will only support inter-type declarations - backed by interfaces when using the annotation style - which means it is not possible to - introduce constructors or fields, as it would not be not possible to call those unless already - weaved and available on a binary form. + of @AspectJ applications using a standard Java 5 compiler. For these reasons, + the 1.5.0 release of AspectJ 5 only supports inter-type declarations + backed by interfaces when using the annotation style - + which means it is not possible to + introduce constructors or fields, as it would not be not possible to call + those unless already woven and available on a binary form. @@ -702,11 +698,9 @@ } } - // here is the actual ITD syntax when using @AspectJ - // public static is mandatory // the field type must be the introduced interface. It can't be a class. - @DeclareParents("org.xzy..*") - public static Moody introduced = new MoodyImpl(); + @DeclareParents(value="org.xzy..*",defaultImpl="MoodyImpl") + private Moody implementedInterface; @Before("execution(* *.*(..)) && this(m)") void feelingMoody(Moody m) { @@ -721,50 +715,39 @@ @DeclareParents annotation is equivalent to a declare parents statement that all types matching the type pattern implement - the interface whose @DeclareParents annotated aspect' field is type of (in this case Moody). - Each method declaration of this interface are treated as inter-type declarations. + the given interface (in this case Moody). + Each method declared in the interface is treated as an inter-type declaration. Note how this scheme operates within the constraints of Java type checking and ensures that this has access to the exact same set of members as in the code style example. - - - Note that it is illegal to use the @DeclareParents annotation on an aspect' field whose type - is not an interface. Indeed, the interface is the inter-type declaration contract that dictates - which methods are introduced. - - + - It is important to remember that the @DeclareParents annotated aspect' field that serves as a host - for the inter-type declaration must be public static and initialized by some means. - The weaved code will indeed delegate calls to this field when f.e. invoking: + Note that it is illegal to use the @DeclareParents annotation on an aspect' field of a non-interface type. + The interface type is the inter-type declaration contract that dictates + which methods are declared on the target type. - - It is perfectly possible to use an IoC framework to initialize the @DeclaredParents aspect' field. You must - ensure though that the aspect field will be initialed prior the first inter-type declaration invocation it hosts. - - - - - If you need to only introduce a marker interface which defines no method - such as java.io.Serializable - it is possible to use the following syntax. + The @DeclareParents annotation can also be used without specifying + a defaultImpl value (for example, + @DeclareParents("org.xyz..*")). This is equivalent to a + declare parents ... implements clause, and does not + make any inter-type declarations for default implementation of the interface methods. @@ -785,19 +768,15 @@ @Aspect public class SerializableMarker { - @DeclareImplements("org.xyz..*") - Serializable introducedNoMethods; + @DeclareParents("org.xyz..*") + Serializable implementedInterface; } ]]> - - The @DeclareImplements annotation on the aspect' field dictates the type pattern - on which to introduce the marker interface. - - In that case, as there is no method introduced, it is perfectly possible to have the aspect' field - private, or not initialized. Remember that the field' type must be the introduced interface and cannot be class. + If the interface defines one or more operations, and these are not implemented by + the target type, an error will be issued during weaving. @@ -806,17 +785,14 @@ Declare statements The previous section on inter-type declarations covered the case - of declare parents ... implements. The 1.5.0 release of AspectJ 5 will + of declare parents ... implements. The 1.5.0 release of AspectJ 5 does not support annotation style declarations for declare parents ... extends and declare soft (programs with these declarations would not in general be compilable by a regular Java 5 compiler, reducing the priority of their implementation). These may be supported in a future release. - Declare annotation is not supported neither in the 1.5.0 release of AspectJ 5. Given that Java 5 - compilers enforce the annotation target (@java.lang.annotation.Target) to be respected, this would cause - adding a lot of dummy members in the aspect (such as dummy constructors, methods etc), which would break the - object oriented design of the @AspectJ aspect itself. + Declare annotation is also not supported in the 1.5.0 release of AspectJ 5. Declare precedence is @@ -894,7 +870,7 @@ code style). Declare warning and error declarations are made by annotating a string constant whose value is the message to be issued. - Note that the String must be a constant and not the result of the invocation + Note that the String must be a literal and not the result of the invocation of a static method for example. Declaring pointcuts inside generic types - This language feature will not be supported until AspectJ 5 M4. - Pointcuts can be declared in both classes and aspects. A pointcut declared in a generic type may use the type variables of the type in which it is declared. All references to a pointcut declared in a generic type from outside of that type must be via a parameterized type reference, @@ -1029,8 +1027,6 @@ Generic Aspects - This feature will not be fully implemented until AspectJ5 M4. - AspectJ 5 allows an abstract aspect to be declared as a generic type. Any concrete aspect extending a generic abstract aspect must extend a parameterized version of the abstract aspect. diff --git a/docs/adk15ProgGuideDB/ltw.xml b/docs/adk15ProgGuideDB/ltw.xml index 3c55bbdc8..4f3212fbc 100644 --- a/docs/adk15ProgGuideDB/ltw.xml +++ b/docs/adk15ProgGuideDB/ltw.xml @@ -9,7 +9,8 @@ Introduction - See Developer's Guide. + See Developer's Guide for information on + load-time weaving support in AspectJ 5. diff --git a/docs/adk15ProgGuideDB/miscellaneous.xml b/docs/adk15ProgGuideDB/miscellaneous.xml index 70a630e7d..802f49e73 100644 --- a/docs/adk15ProgGuideDB/miscellaneous.xml +++ b/docs/adk15ProgGuideDB/miscellaneous.xml @@ -5,8 +5,6 @@ Pointcuts - - Binding of formals AspectJ 5 is more liberal than AspectJ 1.2.1 in accepting pointcut expressions that bind context variables in more than one location. For example, AspectJ @@ -26,16 +24,6 @@ are mutually exclusive. - - - - Additional lint warnings - - 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. - - @@ -92,17 +80,7 @@ - - Tools - - - Aspectpath - - AspectJ 5 allows the specification of directories (containing .class files) on the aspectpath in - addition to jar/zip files. - - - + diff --git a/docs/adk15ProgGuideDB/reflection.xml b/docs/adk15ProgGuideDB/reflection.xml index 9afde22c4..3ae05e698 100644 --- a/docs/adk15ProgGuideDB/reflection.xml +++ b/docs/adk15ProgGuideDB/reflection.xml @@ -3,14 +3,25 @@ New Reflection Interfaces - AspectJ 5 provides support for runtime reflection of aspect types. The class Aspect is - analogous to the Java class Class and provides access to the members of an aspect. + AspectJ 5 provides a full set of reflection APIs analogous to the + java.lang.reflect package, but fully aware of the + AspectJ type system. See the javadoc for the runtime and tools APIs + for the full details. The reflection APIs are only supported when + running under Java 5 and for code compiled by the AspectJ 5 compiler + at target level 1.5. - The Aspect Class + Using AjTypeSystem - + The starting point for using the reflection apis is + org.aspectj.lang.reflect.AjTypeSystem which + provides the method getAjType(Class) which will + return the AjType corresponding to a given + Java class. The AjType interface corresponds to + java.lang.Class and gives you access to all of the + method, field, constructor, and also pointcut, advice, declare + statement and inter-type declaration members in the type. diff --git a/docs/devGuideDB/ajc.xml b/docs/devGuideDB/ajc.xml index 0aa7bae93..a9d21962c 100644 --- a/docs/devGuideDB/ajc.xml +++ b/docs/devGuideDB/ajc.xml @@ -80,14 +80,14 @@ - -aspectpath JarList + -aspectpath Path - Weave binary aspects from JarList zip files into all sources. + Weave binary aspects from Jars and directories on path into all sources. The aspects should have been output by the same version of the compiler. To run the output classes requires putting all the aspectpath entries on the run classpath. - JarList, like classpath, is a single argument containing + Path, like classpath, is a single argument containing a list of paths to jar files, delimited by the platform- specific classpath delimiter. -- 2.39.5