diff --git a/langtools/src/share/classes/javax/lang/model/AnnotatedConstruct.java b/langtools/src/share/classes/javax/lang/model/AnnotatedConstruct.java index c96bff48432..f02f5cdbbd0 100644 --- a/langtools/src/share/classes/javax/lang/model/AnnotatedConstruct.java +++ b/langtools/src/share/classes/javax/lang/model/AnnotatedConstruct.java @@ -39,35 +39,76 @@ import javax.lang.model.type.*; * are on a declaration, whereas annotations on a type are on * a specific use of a type name. * - * The terms directly present and present are used + * The terms directly present, present, + * indirectly present, and associated are used * throughout this interface to describe precisely which annotations - * are returned by methods: + * are returned by the methods defined herein. * - *
An annotation A is directly present on a - * construct E if E is annotated, and: + *
In the definitions below, an annotation A has an + * annotation type AT. If AT is a repeatable annotation + * type, the type of the containing annotation is ATC. + * + *
Annotation A is directly present on a construct + * C if either: * *
Typically, if exactly one annotation of type AT appears in + * the source code of representation of C, then A is + * explicitly declared as applying to C. + * + * If there are multiple annotations of type AT present on + * C, then if AT is repeatable annotation type, an + * annotation of type ATC is implicitly declared on C. + * + *
An annotation A is present on a construct E if either: + *
An annotation A is present on a + * construct C if either: + *
The annotation returned by this method could contain an element * whose value is of type {@code Class}. @@ -118,9 +158,8 @@ public interface AnnotatedConstruct { * @param the annotation type * @param annotationType the {@code Class} object corresponding to * the annotation type - * @return this element's or type use's annotation for the - * specified annotation type if present on this element, else - * {@code null} + * @return this construct's annotation for the specified + * annotation type if present, else {@code null} * * @see #getAnnotationMirrors() * @see java.lang.reflect.AnnotatedElement#getAnnotation @@ -134,10 +173,16 @@ public interface AnnotatedConstruct { A getAnnotation(Class annotationType); /** - * Returns annotations that are present on this construct. + * Returns annotations that are associated with this construct. * - * If there are no annotations present on this construct, - * the return value is an array of length 0. + * If there are no annotations associated with this construct, the + * return value is an array of length 0. + * + * The order of annotations which are directly or indirectly + * present on a construct C is computed as if indirectly present + * annotations on C are directly present on C in place of their + * container annotation, in the order in which they appear in the + * value element of the container annotation. * * The difference between this method and {@link #getAnnotation(Class)} * is that this method detects if its argument is a repeatable @@ -172,8 +217,8 @@ public interface AnnotatedConstruct { * @param the annotation type * @param annotationType the {@code Class} object corresponding to * the annotation type - * @return this element's annotations for the specified annotation - * type if present on this element, else an empty array + * @return this construct's annotations for the specified annotation + * type if present on this construct, else an empty array * * @see #getAnnotationMirrors() * @see #getAnnotation(java.lang.Class) diff --git a/langtools/src/share/classes/javax/lang/model/util/Elements.java b/langtools/src/share/classes/javax/lang/model/util/Elements.java index f782294299a..bc4eb283201 100644 --- a/langtools/src/share/classes/javax/lang/model/util/Elements.java +++ b/langtools/src/share/classes/javax/lang/model/util/Elements.java @@ -143,12 +143,13 @@ public interface Elements { List extends Element> getAllMembers(TypeElement type); /** - * Returns all annotations of an element, whether - * inherited or directly present. + * Returns all annotations present on an element, whether + * directly present or present via inheritance. * * @param e the element being examined * @return all annotations of the element * @see Element#getAnnotationMirrors + * @see javax.lang.model.AnnotatedConstruct */ List extends AnnotationMirror> getAllAnnotationMirrors(Element e);