From: acolyer Date: Thu, 9 Dec 2004 08:59:22 +0000 (+0000) Subject: updates for 1.5.0 M1 X-Git-Tag: Root_AspectJ5_Development~173 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=a4d5eeba2909a5ba1814b5c21fe6a21747882fcb;p=aspectj.git updates for 1.5.0 M1 --- 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 @@ 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. - For example: + In simple terms, an annotation pattern element has one of two basic + forms: + + + @<qualified-name>, for example, @Foo, or + @org.xyz.Foo. + @(<type-pattern>), for example, @(org.xzy..*), or + @(Foo || Boo) + + + These simple elements may be negated using !, and + combined by simple concatentation. The pattern @Foo @Boo + matches an annotated element that has both an annotation of type Foo + and an annotation of type Boo. + + Some examples of annotation patterns follow: - Matches any annotated element which has an annotation of type @Immutable. + Matches any annotated element which has an annotation of + type Immutable. - Matches any annotated element which does not have an annotation of type @Persistent. + Matches any annotated element which does not have an annotation of + type Persistent. - Matches any annotated element which has both an annotation of type @Foo and - an annotation of type @Goo. (The parenthesis are required in this example). + Matches any annotated element which has both an annotation of type Foo and + an annotation of type Goo. - Matches any annotated element which has either an annotation of type @Foo or - an annotation of type @Goo (or both). (The parenthesis are required in this example). + Matches any annotated element which has either an annotation of a type matching + the type pattern (Foo || Goo). + In other words, an annotated element with either an + annotation of type Foo or + an annotation of type Goo (or both). (The parenthesis are required in this example). + + + + + Matches any annotated element which has either an annotation of a type matching + the type pattern (org.xyz..*). + 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). Type Patterns - In AspectJ 1.2, type patterns have the following form: - - - AspectJ 1.5 extends type patterns to allow an optional AnnotationPattern - prefix. + prefix. (Extensions to this definition for generics are shown in the next chapter). + + 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: + + The following examples illustrate the use of annotations in type @@ -384,13 +401,13 @@ (@Immutable *) ]]> - Matches any type with the @Immutable annotation. + Matches any type with an @Immutable annotation. - Matches any type which does not have the @Immutable annotation. + Matches any type which does not have an @Immutable annotation. @Immutable annotation. Matches a type Foo or any of its subtypes, which have the @Immutable - annotation, or a type Goo. An AnnotationPattern has higher - precedence than && or ||, so the previous expression - is equivalent to ((@Immutable Foo+) || Goo). + annotation, or a type Goo. @@ -418,6 +433,28 @@ @NonPersistent annotation. + + + + Matches any type in a package beginning with the prefix org.xyz, + which has both an @Immutable annotation and an + @NonPersistent annotation. + + + + + + Matches any type in a package beginning with the prefix org.xyz, + which has an inheritable annotation. The annotation pattern + @(@Inherited *) matches any annotation of a type matching the + type pattern @Inherited *, which in turn matches any type with the + @Inherited annotation. + + @@ -429,13 +466,16 @@ @@ -487,26 +527,39 @@ + + @Persisted @Classified * * + + + Matches a field with an annotation @Persisted and + an annotation @Classified. + + + + A MethodPattern is of the form The optional AnnotationPattern 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: @@ -563,7 +621,6 @@ - @@ -577,7 +634,8 @@ within(@Secure *) - Matches any join point occuring in a type with an @Secure + Matches any join point where the code executing is declared in a + type with an @Secure annotation. The format of the within pointcut designator in AspectJ 5 is 'within' '(' OptionalParensTypePattern ')'. @@ -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 @args, @this, @target, - @within, @withincode, @call, @execution, @adviceexecution, @get, @set, - @staticinitialization, @initialization,, and @preinitialization + @within, @withincode, and @annotation It is a compilation error to attempt to match on an annotation type @@ -670,21 +727,23 @@ @@ -791,15 +850,14 @@ The @within and @withincode pointcut designators - match any join point where the enclosing type (@within), or - method/constructor (@withincode) has an annotation of the specified + match any join point where the executing code is defined within a type (@within), + or a method/constructor (@withincode) that has an annotation of the specified type. The form of these designators is: Some examples of using these designators follow: @@ -810,8 +868,8 @@ @within(@Foo) - Matches any join point where the enclosing type - has an annotation of type Foo. + Matches any join point where the executing code is defined + within a type which has an annotation of type Foo. @@ -821,8 +879,8 @@ @withincode(c); - Matches any join point whose shadow is lexically enclosed - in a method which has an annotation of type @Critical, + Matches any join point where the executing code is defined + in a method or constructor which has an annotation of type @Critical, and exposes the value of the annotation in the parameter c. @@ -831,111 +889,17 @@ - The remaining annotation-based pointcut designators are defined in a - similar fashion: + The @annotation pointcut designator matches any + join point where the subject of the join point has + an annotation of the given type. Like the other @pcds, it can also be + used for context exposure. - - - - - @call(@Foo) - - - Matches any call join point where the most specific join point - signature has an annotation of type @Foo. - - - - - - @execution(@Foo) - - - Matches any execution join point where the most specific join point - signature has an annotation of type @Foo. - - - - - - @adviceexecution(@Foo) - - - Matches any advice execution join point where the advice - has an annotation of type @Foo. - - - - - - @get(@Foo) - - - Matches any get join point where the target field - has an annotation of type @Foo. - - - - - - @set(@Foo) - - - Matches any set join point where the target field - has an annotation of type @Foo. - - - - - - @initialization(@Foo) - - - Matches any initialization join point where the initiating - constructor has an annotation of type @Foo. - - - - - - @preinitialization(@Foo) - - - Matches any preinitialization join point where the initiating - constructor has an annotation of type @Foo. - - - - - - @staticinitialization(@Foo) - - - Matches any staticinitialization join point where the type being - initialized has an annotation of type @Foo. - - - - - + AtAnnotation := '@annotation' '(' AnnotationOrIdentifier ')' + ]]> + + The subject of a join point is defined in the table in chapter one of + this guide. Access to annotation information on members at a matched join point is also available @@ -962,6 +926,15 @@ to Java 5. + + The @this,@target and @args + pointcut designators can only be used to match against annotations + that have runtime retention. The @within, @withincode + and @annotation 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. + + @@ -979,6 +952,8 @@ expressions before commiting to any one approach. + +