aboutsummaryrefslogtreecommitdiffstats
path: root/docs/modules/adk15notebook/pages/annotations.adoc
diff options
context:
space:
mode:
Diffstat (limited to 'docs/modules/adk15notebook/pages/annotations.adoc')
-rw-r--r--docs/modules/adk15notebook/pages/annotations.adoc48
1 files changed, 24 insertions, 24 deletions
diff --git a/docs/modules/adk15notebook/pages/annotations.adoc b/docs/modules/adk15notebook/pages/annotations.adoc
index 5fcf74608..24a0d27e5 100644
--- a/docs/modules/adk15notebook/pages/annotations.adoc
+++ b/docs/modules/adk15notebook/pages/annotations.adoc
@@ -1,14 +1,14 @@
-== Annotations
+= Annotations
[[annotations-inJava5]]
-=== Annotations in Java 5
+== Annotations in Java 5
This section provides the essential information about annotations in
Java 5 needed to understand how annotations are treated in AspectJ 5.
For a full introduction to annotations in Java, please see the
documentation for the Java 5 SDK.
-==== Using Annotations
+=== Using Annotations
Java 5 introduces _annotation types_ which can be used to express
metadata relating to program members in the form of _annotations_.
@@ -55,7 +55,7 @@ Multi-value annotations must use the `member-name=value
public void someMethod() {...}
....
-==== Retention Policies
+=== Retention Policies
Annotations can have one of three retention policies:
@@ -74,7 +74,7 @@ Local variable annotations are not retained in class files (or at
runtime) regardless of the retention policy set on the annotation type.
See JLS 9.6.1.2.
-==== Accessing Annotations at Runtime
+=== Accessing Annotations at Runtime
Java 5 supports a new interface, `java.lang.reflect.AnnotatedElement`,
that is implemented by the reflection classes in Java (`Class`,
@@ -84,7 +84,7 @@ you access to annotations _that have runtime retention_ via the
annotation types are just regular Java classes, the annotations returned
by these methods can be queried just like any regular Java object.
-==== Annotation Inheritance
+=== Annotation Inheritance
It is important to understand the rules relating to inheritance of
annotations, as these have a bearing on join point matching based on the
@@ -120,7 +120,7 @@ interfaces never inherits any annotations from the interfaces it
implements.
[[annotations-aspectmembers]]
-=== Annotating Aspects
+== Annotating Aspects
AspectJ 5 supports annotations on aspects, and on method, field,
constructor, advice, and inter-type declarations within aspects. Method
@@ -210,14 +210,14 @@ public aspect AnAspect {
....
[[annotations-pointcuts-and-advice]]
-=== Join Point Matching based on Annotations
+== Join Point Matching based on Annotations
This section discusses changes to type pattern and signature pattern
matching in AspectJ 5 that support matching join points based on the
presence or absence of annotations. We then discuss means of exposing
annotation values within the body of advice.
-==== Annotation Patterns
+=== Annotation Patterns
For any kind of annotated element (type, method, constructor, package,
etc.), an annotation pattern can be used to match against the set of
@@ -254,7 +254,7 @@ Some examples of annotation patterns follow:
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
+=== Type Patterns
AspectJ 1.5 extends type patterns to allow an optional
`AnnotationPattern` prefix.
@@ -320,10 +320,10 @@ patterns:
`@Inherited` annotation.
[[signaturePatterns]]
-==== Signature Patterns
+=== Signature Patterns
[[fieldPatterns]]
-===== Field Patterns
+==== Field Patterns
A `FieldPattern` can optionally specify an annotation-matching pattern
as the first element:
@@ -365,7 +365,7 @@ annotations that match the pattern. For example:
`@Classified`.
[[methodPatterns]]
-===== Method and Constructor Patterns
+==== Method and Constructor Patterns
A `MethodPattern` can optionally specify an annotation-matching pattern
as the first element.
@@ -424,7 +424,7 @@ annotations that match the pattern. For example:
Matches any method taking at least one parameter, where the parameter
type has an annotation `@Immutable`.
-==== Example Pointcuts
+=== Example Pointcuts
`within(@Secure *)`::
Matches any join point where the code executing is declared in a type
@@ -448,7 +448,7 @@ annotations that match the pattern. For example:
is not `Catastrophic`. The format of the `handler` pointcut designator
in AspectJ 5 is `'handler' '(' OptionalParensTypePattern ')'`.
-==== Runtime type matching and context exposure
+=== Runtime type matching and context exposure
AspectJ 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
@@ -617,7 +617,7 @@ 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.
-==== Package and Parameter Annotations
+=== Package and Parameter Annotations
_Matching on package annotations is not supported in AspectJ. Support
for this capability may be considered in a future release._
@@ -677,7 +677,7 @@ The parentheses are grouping @SomeOtherAnnotation with the * to form the
type pattern for the parameter, then the type @SomeAnnotation will be
treated as a parameter annotation pattern.
-==== Annotation Inheritance and pointcut matching
+=== Annotation Inheritance and pointcut matching
According to the Java 5 specification, non-type annotations are not
inherited, and annotations on types are only inherited if they have the
@@ -722,7 +722,7 @@ throws clause) is based on the subject of the join point (the method
actually being called).
[[matchingOnAnnotationValues]]
-==== Matching based on annotation values
+=== Matching based on annotation values
The `if` pointcut designator can be used to write pointcuts that match
based on the values annotation members. For example:
@@ -735,9 +735,9 @@ pointcut txRequiredMethod(Tx transactionAnnotation) :
....
[[annotations-decp]]
-=== Using Annotations with declare statements
+== Using Annotations with declare statements
-==== Declare error and declare warning
+=== Declare error and declare warning
Since pointcut expressions in AspectJ 5 support join point matching
based on annotations, this facility can be exploited when writing
@@ -757,7 +757,7 @@ declare error : call(* org.xyz.model.*.*(..)) &&
: "Untrusted code should not call the model classes directly";
....
-==== declare parents
+=== declare parents
The general form of a `declare parents` statement is:
@@ -787,7 +787,7 @@ annotation type is matched by a non-explicit type pattern used in a
declare parents statement it will be ignored (and an XLint warning
issued).
-==== declare precedence
+=== declare precedence
The general form of a declare precedence statement is:
@@ -805,7 +805,7 @@ information as part of the pattern specification. For example:
security-related aspects take precedence).
[[annotations-declare]]
-=== Declare Annotation
+== Declare Annotation
AspectJ 5 supports a new kind of declare statement,
`declare annotation`. This takes different forms according to the
@@ -854,6 +854,6 @@ declare @constructor : BankAccount+.new(..) :
annotation.
[[annotations-itds]]
-=== Inter-type Declarations
+== Inter-type Declarations
An annotation type may not be the target of an inter-type declaration.