Review request for present, directly present, etc. in core reflection javadoc
Joe Darcy
joe.darcy at oracle.com
Tue Jul 9 14:41:43 PDT 2013
Hello,
Please review the patch below which incorporates the "present",
"directly present", "associated", etc. terminology into the
AnnotatedElement interface in core reflection. This is wholly analogous
to the previous work of using that terminology in the AnnotatedConstruct
interface in javax.lang.model.model.
Full webrev viewable at:
http://cr.openjdk.java.net/~darcy/8010679.0/
Thanks,
-Joe
diff -r 83c2976ef8ee
src/share/classes/java/lang/reflect/AnnotatedElement.java
--- a/src/share/classes/java/lang/reflect/AnnotatedElement.java Tue Jul
09 16:00:41 2013 +0100
+++ b/src/share/classes/java/lang/reflect/AnnotatedElement.java Tue Jul
09 14:40:02 2013 -0700
@@ -43,38 +43,62 @@
* through" a container annotation (JLS 9.7) which was generated at
* compile-time to wrap multiple annotations of the argument type.
*
- * <p>The terms <em>directly present</em> and <em>present</em> are used
- * throughout this interface to describe precisely which annotations are
- * returned by methods:
+ * <p>The terms <em>directly present</em>, <em>directly present</em>,
+ * <em>present</em>, and <em>associated</em> are used throughout this
+ * interface to describe precisely which annotations are returned by
+ * methods:
*
* <ul>
- * <li>An annotation A is <em>directly present</em> on an element E if E is
- * associated with a RuntimeVisibleAnnotations or
- * RuntimeVisibleParameterAnnotations attribute, and:
+ *
+ * <li> An annotation <i>A</i> is <em>directly present</em> on an
+ * element <i>E</i> if <i>E</i> has a {@code
+ * RuntimeVisibleAnnotations} or {@code
+ * RuntimeVisibleParameterAnnotations} or {@code
+ * RuntimeVisibleTypeAnnotations} attribute, and the attribute
+ * contains <i>A</i>.
+ *
+ * <li>An annotation <i>A</i> is <em>indirectly present</em> on an
+ * element <i>E</i> if <i>E</i> has a {@code RuntimeVisibleAnnotations} or
+ * {@code RuntimeVisibleParameterAnnotations} or {@code
RuntimeVisibleTypeAnnotations}
+ * attribute, and <i>A</i> 's type is repeatable, and the attribute
contains
+ * exactly one annotation whose value element contains <i>A</i> and whose
+ * type is the containing annotation type of <i>A</i> 's type.
+ *
+ * <li>An annotation <i>A</i> is present on an element <i>E</i> if either:
*
* <ul>
- * <li>for an invocation of {@code get[Declared]Annotation(Class<T>)} or
- * {@code get[Declared]Annotations()}, the attribute contains A.
*
- * <li>for an invocation of {@code
get[Declared]AnnotationsByType(Class<T>)}, the
- * attribute either contains A or, if the type of A is repeatable, contains
- * exactly one annotation whose value element contains A and whose type
is the
- * containing annotation type of A's type (JLS 9.6).
+ * <li><i>A</i> is directly present on <i>E</i>; or
+ *
+ * <li>No annotation of <i>A</i> 's type is directly present on
+ * <i>E</i>, and <i>E</i> is a class, and <i>A</i> 's type is
+ * inheritable, and <i>A</i> is present on the superclass of <i>E</i>.
+ *
* </ul>
*
- * <p>
- * <li>An annotation A is <em>present</em> on an element E if either:
+ * <li>An annotation <i>A</i> is <em>associated</em> with an element
<i>E</i>
+ * if either:
*
* <ul>
- * <li>A is <em>directly present</em> on E; or
*
- * <li>A is not <em>directly present</em> on E, and E is a class, and
A's type
- * is inheritable (JLS 9.6.3.3), and A is <em>present</em> on the
superclass of
- * E.
+ * <li><i>A</i> is directly or indirectly present on <i>E</i>; or
+ *
+ * <li>No annotation of <i>A</i> 's type is directly or indirectly
+ * present on <i>E</i>, and <i>E</i> is a class, and <i>A</i>'s type
+ * is inheritable, and <i>A</i> is associated with the superclass of
+ * <i>E</i>.
+ *
* </ul>
*
* </ul>
*
+ * For an invocation of {@code get[Declared]AnnotationsByType( Class <
+ * T >)}, the order of annotations which are directly or indirectly
+ * present on an element <i>E</i> is computed as if indirectly present
+ * annotations on <i>E</i> are directly present on <i>E</i> in place
+ * of their container annotation, in the order in which they appear in
+ * the value element of the container annotation.
+
* <p>If an annotation returned by a method in this interface contains
* (directly or indirectly) a {@link Class}-valued member referring to
* a class that is not accessible in this VM, attempting to read the class
@@ -85,10 +109,11 @@
* a {@link EnumConstantNotPresentException} if the enum constant in the
* annotation is no longer present in the enum type.
*
- * <p>Attempting to read annotations of a repeatable annotation type T
- * that are contained in an annotation whose type is not, in fact, the
- * containing annotation type of T, will result in an {@link
- * AnnotationFormatError}.
+ * <p>If an annotation type <i>T</i> is (meta-)annotated with an
+ * {@code @Repeatable} annotation whose value element indicates a type
+ * <i>TC</i>, but <i>TC</i> does not declare a {@code value()} method
+ * with a return type of <i>T</i>{@code []}, then an exception of type
+ * {@link java.lang.annotation.AnnotationFormatError} is thrown.
*
* <p>Finally, attempting to read a member whose definition has evolved
* incompatibly will result in a {@link
@@ -106,7 +131,7 @@
public interface AnnotatedElement {
/**
* Returns true if an annotation for the specified type
- * is present on this element, else false. This method
+ * is <em>present</em> on this element, else false. This method
* is designed primarily for convenient access to marker annotations.
*
* <p>The truth value returned by this method is equivalent to:
@@ -128,7 +153,7 @@
/**
* Returns this element's annotation for the specified type if
- * such an annotation is present, else null.
+ * such an annotation is <em>present</em>, else null.
*
* @param <T> the type of the annotation to query for and return
if present
* @param annotationClass the Class object corresponding to the
@@ -141,9 +166,9 @@
<T extends Annotation> T getAnnotation(Class<T> annotationClass);
/**
- * Returns annotations that are <em>present</em> on this element.
+ * Returns annotations that are <em>associated</em> with this element.
*
- * If there are no annotations <em>present</em> on this element,
the return
+ * If there are no annotations <em>associated</em> with this
element, the return
* value is an array of length 0.
*
* The difference between this method and {@link
#getAnnotation(Class)}
@@ -159,7 +184,7 @@
* @param annotationClass the Class object corresponding to the
* annotation type
* @return all this element's annotations for the specified
annotation type if
- * present on this element, else an array of length zero
+ * associated with this element, else an array of length zero
* @throws NullPointerException if the given annotation class is null
* @since 1.8
*/
@@ -181,16 +206,16 @@
/**
* Returns this element's annotation for the specified type if
- * such an annotation is present, else null.
+ * such an annotation is <em>directly present</em>, else null.
*
* This method ignores inherited annotations. (Returns null if no
* annotations are directly present on this element.)
*
- * @param <T> the type of the annotation to query for and return if
present
+ * @param <T> the type of the annotation to query for and return if
directly present
* @param annotationClass the Class object corresponding to the
* annotation type
* @return this element's annotation for the specified annotation
type if
- * present on this element, else null
+ * directly present on this element, else null
* @throws NullPointerException if the given annotation class is null
* @since 1.8
*/
@@ -217,7 +242,7 @@
* @param annotationClass the Class object corresponding to the
* annotation type
* @return all this element's annotations for the specified
annotation type if
- * present on this element, else an array of length zero
+ * directly present on this element, else an array of length zero
* @throws NullPointerException if the given annotation class is null
* @since 1.8
*/
More information about the enhanced-metadata-spec-discuss
mailing list