From alex.buckley at oracle.com Wed Jul 3 19:47:30 2013
From: alex.buckley at oracle.com (Alex Buckley)
Date: Wed, 03 Jul 2013 19:47:30 -0700
Subject: Metadata about parameter names
In-Reply-To: <51C0F26F.3020908@oracle.com>
References: <51C0F26F.3020908@oracle.com>
Message-ID: <51D4E242.2080609@oracle.com>
FYI isNamePresent() has been added to j.l.r.Parameter [1].
Alex
[1] http://hg.openjdk.java.net/jdk8/tl/jdk/rev/a8f51c3341a5
On 6/18/2013 4:51 PM, Alex Buckley wrote:
> Prompted by discussions on jdk8-dev [1], I have specified an
> isNamePresent() method in java.lang.reflect.Parameter. It exposes
> whether the parameter has a name _according to the MethodParameters
> attribute_. Non-Java clients can use it to determine whether the
> parameter "really" has a name, because for the sake of Java clients, a
> parameter always has a name _according to getName()_ even if we have to
> synthesize it.
>
> The mini-spec for this method is at [2] and the enhanced metadata spec
> incorporates it for completeness [3].
>
> Alex
>
> [1] http://mail.openjdk.java.net/pipermail/jdk8-dev/2013-June/002658.html
> [2] http://bugs.sun.com/view_bug.do?bug_id=8016285
> [3] http://cr.openjdk.java.net/~abuckley/8misc.pdf
From joe.darcy at oracle.com Tue Jul 9 14:41:43 2013
From: joe.darcy at oracle.com (Joe Darcy)
Date: Tue, 09 Jul 2013 14:41:43 -0700
Subject: Review request for present, directly present, etc. in core reflection
javadoc
Message-ID: <51DC8397.8000508@oracle.com>
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.
*
- * The terms directly present and present are used
- * throughout this interface to describe precisely which annotations are
- * returned by methods:
+ *
The terms directly present, directly present,
+ * present, and associated are used throughout this
+ * interface to describe precisely which annotations are returned by
+ * methods:
*
*
- * - An annotation A is directly present on an element E if E is
- * associated with a RuntimeVisibleAnnotations or
- * RuntimeVisibleParameterAnnotations attribute, and:
+ *
+ *
- An annotation A is directly present on an
+ * element E if E has a {@code
+ * RuntimeVisibleAnnotations} or {@code
+ * RuntimeVisibleParameterAnnotations} or {@code
+ * RuntimeVisibleTypeAnnotations} attribute, and the attribute
+ * contains A.
+ *
+ *
- An annotation A is indirectly present on an
+ * element E if E has a {@code RuntimeVisibleAnnotations} or
+ * {@code RuntimeVisibleParameterAnnotations} or {@code
RuntimeVisibleTypeAnnotations}
+ * attribute, and A 's type is repeatable, and the attribute
contains
+ * exactly one annotation whose value element contains A and whose
+ * type is the containing annotation type of A 's type.
+ *
+ *
- An annotation A is present on an element E if either:
*
*
- * - for an invocation of {@code get[Declared]Annotation(Class)} or
- * {@code get[Declared]Annotations()}, the attribute contains A.
*
- *
- for an invocation of {@code
get[Declared]AnnotationsByType(Class)}, 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).
+ *
- A is directly present on E; or
+ *
+ *
- No annotation of A 's type is directly present on
+ * E, and E is a class, and A 's type is
+ * inheritable, and A is present on the superclass of E.
+ *
*
*
- *
- *
- An annotation A is present on an element E if either:
+ *
- An annotation A is associated with an element
E
+ * if either:
*
*
- * - A is directly present on E; or
*
- *
- A is not directly present on E, and E is a class, and
A's type
- * is inheritable (JLS 9.6.3.3), and A is present on the
superclass of
- * E.
+ *
- A is directly or indirectly present on E; or
+ *
+ *
- No annotation of A 's type is directly or indirectly
+ * present on E, and E is a class, and A's type
+ * is inheritable, and A is associated with the superclass of
+ * E.
+ *
*
*
*
*
+ * For an invocation of {@code get[Declared]AnnotationsByType( Class <
+ * T >)}, the order of annotations which are directly or indirectly
+ * present on an element E is computed as if indirectly present
+ * annotations on E are directly present on E in place
+ * of their container annotation, in the order in which they appear in
+ * the value element of the container annotation.
+
* 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.
*
- *
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}.
+ *
If an annotation type T is (meta-)annotated with an
+ * {@code @Repeatable} annotation whose value element indicates a type
+ * TC, but TC does not declare a {@code value()} method
+ * with a return type of T{@code []}, then an exception of type
+ * {@link java.lang.annotation.AnnotationFormatError} is thrown.
*
*
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 present on this element, else false. This method
* is designed primarily for convenient access to marker annotations.
*
*
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 present, else null.
*
* @param 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 getAnnotation(Class annotationClass);
/**
- * Returns annotations that are present on this element.
+ * Returns annotations that are associated with this element.
*
- * If there are no annotations present on this element,
the return
+ * If there are no annotations associated 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 directly present, else null.
*
* This method ignores inherited annotations. (Returns null if no
* annotations are directly present on this element.)
*
- * @param the type of the annotation to query for and return if
present
+ * @param 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
*/
From alex.buckley at oracle.com Tue Jul 9 16:00:35 2013
From: alex.buckley at oracle.com (Alex Buckley)
Date: Tue, 09 Jul 2013 16:00:35 -0700
Subject: Review request for present, directly present,
etc. in core reflection javadoc
In-Reply-To: <51DC8397.8000508@oracle.com>
References: <51DC8397.8000508@oracle.com>
Message-ID: <51DC9613.8050404@oracle.com>
Hi Joe,
Thanks for applying these spec changes to the API. I note the
refactoring in get[Declared]AnnotationByType so that the order of
directly + indirectly present annotations is specified earlier.
One omission: getDeclaredAnnotationsByType still says it returns
directly present annotations, when it should say directly _or
indirectly_ present annotations. After all, that method is different
than getDeclaredAnnotations precisely because of look-through. Please
see item 2 in the bug.
Alex
On 7/9/2013 2:41 PM, Joe Darcy wrote:
> 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.
> *
> - * The terms directly present and present are used
> - * throughout this interface to describe precisely which annotations are
> - * returned by methods:
> + *
The terms directly present, directly present,
> + * present, and associated are used throughout this
> + * interface to describe precisely which annotations are returned by
> + * methods:
> *
> *
> - * - An annotation A is directly present on an element E if
> E is
> - * associated with a RuntimeVisibleAnnotations or
> - * RuntimeVisibleParameterAnnotations attribute, and:
> + *
> + *
- An annotation A is directly present on an
> + * element E if E has a {@code
> + * RuntimeVisibleAnnotations} or {@code
> + * RuntimeVisibleParameterAnnotations} or {@code
> + * RuntimeVisibleTypeAnnotations} attribute, and the attribute
> + * contains A.
> + *
> + *
- An annotation A is indirectly present on an
> + * element E if E has a {@code RuntimeVisibleAnnotations} or
> + * {@code RuntimeVisibleParameterAnnotations} or {@code
> RuntimeVisibleTypeAnnotations}
> + * attribute, and A 's type is repeatable, and the attribute
> contains
> + * exactly one annotation whose value element contains A and whose
> + * type is the containing annotation type of A 's type.
> + *
> + *
- An annotation A is present on an element E if either:
> *
> *
> - * - for an invocation of {@code get[Declared]Annotation(Class)} or
> - * {@code get[Declared]Annotations()}, the attribute contains A.
> *
> - *
- for an invocation of {@code
> get[Declared]AnnotationsByType(Class)}, 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).
> + *
- A is directly present on E; or
> + *
> + *
- No annotation of A 's type is directly present on
> + * E, and E is a class, and A 's type is
> + * inheritable, and A is present on the superclass of E.
> + *
> *
> *
> - *
> - *
- An annotation A is present on an element E if either:
> + *
- An annotation A is associated with an element
> E
> + * if either:
> *
> *
> - * - A is directly present on E; or
> *
> - *
- A is not directly present on E, and E is a class, and
> A's type
> - * is inheritable (JLS 9.6.3.3), and A is present on the
> superclass of
> - * E.
> + *
- A is directly or indirectly present on E; or
> + *
> + *
- No annotation of A 's type is directly or indirectly
> + * present on E, and E is a class, and A's type
> + * is inheritable, and A is associated with the superclass of
> + * E.
> + *
> *
> *
> *
> *
> + * For an invocation of {@code get[Declared]AnnotationsByType( Class <
> + * T >)}, the order of annotations which are directly or indirectly
> + * present on an element E is computed as if indirectly present
> + * annotations on E are directly present on E in place
> + * of their container annotation, in the order in which they appear in
> + * the value element of the container annotation.
> +
> * 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.
> *
> - *
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}.
> + *
If an annotation type T is (meta-)annotated with an
> + * {@code @Repeatable} annotation whose value element indicates a type
> + * TC, but TC does not declare a {@code value()} method
> + * with a return type of T{@code []}, then an exception of type
> + * {@link java.lang.annotation.AnnotationFormatError} is thrown.
> *
> *
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 present on this element, else false. This method
> * is designed primarily for convenient access to marker annotations.
> *
> *
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 present, else null.
> *
> * @param 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 getAnnotation(Class annotationClass);
>
> /**
> - * Returns annotations that are present on this element.
> + * Returns annotations that are associated with this element.
> *
> - * If there are no annotations present on this element,
> the return
> + * If there are no annotations associated 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 directly present, else null.
> *
> * This method ignores inherited annotations. (Returns null if no
> * annotations are directly present on this element.)
> *
> - * @param the type of the annotation to query for and return if
> present
> + * @param 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
> */
>
From joe.darcy at oracle.com Tue Jul 9 18:38:53 2013
From: joe.darcy at oracle.com (Joe Darcy)
Date: Tue, 09 Jul 2013 18:38:53 -0700
Subject: Review request for present, directly present,
etc. in core reflection javadoc
In-Reply-To: <51DC9613.8050404@oracle.com>
References: <51DC8397.8000508@oracle.com> <51DC9613.8050404@oracle.com>
Message-ID: <51DCBB2D.9090803@oracle.com>
Hi Alex,
On 07/09/2013 04:00 PM, Alex Buckley wrote:
> Hi Joe,
>
> Thanks for applying these spec changes to the API. I note the
> refactoring in get[Declared]AnnotationByType so that the order of
> directly + indirectly present annotations is specified earlier.
>
> One omission: getDeclaredAnnotationsByType still says it returns
> directly present annotations, when it should say directly _or
> indirectly_ present annotations. After all, that method is different
> than getDeclaredAnnotations precisely because of look-through. Please
> see item 2 in the bug.
>
>
Another iteration on the specification changes below; revised webrev at:
cr.openjdk.java.net/~darcy/8010679.1/
-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 17:52:39 2013 -0700
@@ -32,49 +32,74 @@
* Represents an annotated element of the program currently running in
this
* VM. This interface allows annotations to be read reflectively. All
* annotations returned by methods in this interface are immutable and
- * serializable. It is permissible for the caller to modify the
- * arrays returned by accessors for array-valued enum members; it will
- * have no affect on the arrays returned to other callers.
+ * serializable. The arrays returned by methods of this interface may
be modified
+ * by callers without affecting the arrays returned to other callers.
*
* The {@link #getAnnotationsByType(Class)} and {@link
* #getDeclaredAnnotationsByType(Class)} methods support multiple
- * annotations of the same type on an element. If the argument to
either method
- * is a repeatable annotation type (JLS 9.6), then the method will "look
- * through" a container annotation (JLS 9.7) which was generated at
- * compile-time to wrap multiple annotations of the argument type.
+ * annotations of the same type on an element. If the argument to
+ * either method is a repeatable annotation type (JLS 9.6), then the
+ * method will "look through" a container annotation (JLS 9.7) and
+ * return the one or more annotations inside the container. Container
+ * annotations may be generated at compile-time to wrap multiple
+ * annotations of the argument type.
*
- *
The terms directly present and present are used
- * throughout this interface to describe precisely which annotations are
- * returned by methods:
+ *
The terms directly present, indirectly present,
+ * present, and associated are used throughout this
+ * interface to describe precisely which annotations are returned by
+ * methods:
*
*
- * - An annotation A is directly present on an element E if E is
- * associated with a RuntimeVisibleAnnotations or
- * RuntimeVisibleParameterAnnotations attribute, and:
+ *
+ *
- An annotation A is directly present on an
+ * element E if E has a {@code
+ * RuntimeVisibleAnnotations} or {@code
+ * RuntimeVisibleParameterAnnotations} or {@code
+ * RuntimeVisibleTypeAnnotations} attribute, and the attribute
+ * contains A.
+ *
+ *
- An annotation A is indirectly present on an
+ * element E if E has a {@code RuntimeVisibleAnnotations} or
+ * {@code RuntimeVisibleParameterAnnotations} or {@code
RuntimeVisibleTypeAnnotations}
+ * attribute, and A 's type is repeatable, and the attribute
contains
+ * exactly one annotation whose value element contains A and whose
+ * type is the containing annotation type of A 's type.
+ *
+ *
- An annotation A is present on an element E if either:
*
*
- * - for an invocation of {@code get[Declared]Annotation(Class)} or
- * {@code get[Declared]Annotations()}, the attribute contains A.
*
- *
- for an invocation of {@code
get[Declared]AnnotationsByType(Class)}, 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).
+ *
- A is directly present on E; or
+ *
+ *
- No annotation of A 's type is directly present on
+ * E, and E is a class, and A 's type is
+ * inheritable, and A is present on the superclass of E.
+ *
*
*
- *
- *
- An annotation A is present on an element E if either:
+ *
- An annotation A is associated with an element
E
+ * if either:
*
*
- * - A is directly present on E; or
*
- *
- A is not directly present on E, and E is a class, and
A's type
- * is inheritable (JLS 9.6.3.3), and A is present on the
superclass of
- * E.
+ *
- A is directly or indirectly present on E; or
+ *
+ *
- No annotation of A 's type is directly or indirectly
+ * present on E, and E is a class, and A's type
+ * is inheritable, and A is associated with the superclass of
+ * E.
+ *
*
*
*
*
+ * For an invocation of {@code get[Declared]AnnotationsByType( Class <
+ * T >)}, the order of annotations which are directly or indirectly
+ * present on an element E is computed as if indirectly present
+ * annotations on E are directly present on E in place
+ * of their container annotation, in the order in which they appear in
+ * the value element of the container annotation.
+
* 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 +110,11 @@
* a {@link EnumConstantNotPresentException} if the enum constant in the
* annotation is no longer present in the enum type.
*
- *
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}.
+ *
If an annotation type T is (meta-)annotated with an
+ * {@code @Repeatable} annotation whose value element indicates a type
+ * TC, but TC does not declare a {@code value()} method
+ * with a return type of T{@code []}, then an exception of type
+ * {@link java.lang.annotation.AnnotationFormatError} is thrown.
*
*
Finally, attempting to read a member whose definition has evolved
* incompatibly will result in a {@link
@@ -106,7 +132,7 @@
public interface AnnotatedElement {
/**
* Returns true if an annotation for the specified type
- * is present on this element, else false. This method
+ * is present on this element, else false. This method
* is designed primarily for convenient access to marker annotations.
*
*
The truth value returned by this method is equivalent to:
@@ -128,7 +154,7 @@
/**
* Returns this element's annotation for the specified type if
- * such an annotation is present, else null.
+ * such an annotation is present, else null.
*
* @param the type of the annotation to query for and return
if present
* @param annotationClass the Class object corresponding to the
@@ -141,9 +167,9 @@
T getAnnotation(Class annotationClass);
/**
- * Returns annotations that are present on this element.
+ * Returns annotations that are associated with this element.
*
- * If there are no annotations present on this element,
the return
+ * If there are no annotations associated with this
element, the return
* value is an array of length 0.
*
* The difference between this method and {@link
#getAnnotation(Class)}
@@ -159,7 +185,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,27 +207,30 @@
/**
* Returns this element's annotation for the specified type if
- * such an annotation is present, else null.
+ * such an annotation is directly present, else null.
*
* This method ignores inherited annotations. (Returns null if no
* annotations are directly present on this element.)
*
- * @param the type of the annotation to query for and return if
present
+ * @param 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
*/
T getDeclaredAnnotation(Class
annotationClass);
/**
- * Returns annotations that are directly present on this
element.
- * This method ignores inherited annotations.
+ * Returns this element's annotation(s) for the specified type if
+ * such annotations are either directly present or
+ * indirectly present. This method ignores inherited
+ * annotations.
*
- * If there are no annotations directly present on this
element,
- * the return value is an array of length 0.
+ * If there are no specified annotations directly or indirectly
+ * present on this element, the return value is an array of length
+ * 0.
*
* The difference between this method and {@link
* #getDeclaredAnnotation(Class)} is that this method detects if its
@@ -213,11 +242,11 @@
* have no effect on the arrays returned to other callers.
*
* @param the type of the annotation to query for and return
- * if directly present
+ * if directly or indirectly present
* @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
*/
From alex.buckley at oracle.com Wed Jul 10 11:16:11 2013
From: alex.buckley at oracle.com (Alex Buckley)
Date: Wed, 10 Jul 2013 11:16:11 -0700
Subject: Review request for present, directly present,
etc. in core reflection javadoc
In-Reply-To: <51DCBB2D.9090803@oracle.com>
References: <51DC8397.8000508@oracle.com> <51DC9613.8050404@oracle.com>
<51DCBB2D.9090803@oracle.com>
Message-ID: <51DDA4EB.3080405@oracle.com>
- The @return clause for getDeclaredAnnotationsByType is missing an
"indirectly". I have updated JDK-8010679 with complete return clauses.
- I feel strongly that the correct order for a triple of get methods is:
getAnnotation(...), getAnnotations(), getAnnotationsByType(...). This
puts the two legacy methods side by side so it's easier to read all
three in order (A-A-B only has one phase change, A-B-A has two). It is
also the most natural lexicographic ordering, which I rate above
grouping methods by parameter type.
Alex
On 7/9/2013 6:38 PM, Joe Darcy wrote:
> Hi Alex,
>
> On 07/09/2013 04:00 PM, Alex Buckley wrote:
>> Hi Joe,
>>
>> Thanks for applying these spec changes to the API. I note the
>> refactoring in get[Declared]AnnotationByType so that the order of
>> directly + indirectly present annotations is specified earlier.
>>
>> One omission: getDeclaredAnnotationsByType still says it returns
>> directly present annotations, when it should say directly _or
>> indirectly_ present annotations. After all, that method is different
>> than getDeclaredAnnotations precisely because of look-through. Please
>> see item 2 in the bug.
>>
>>
>
> Another iteration on the specification changes below; revised webrev at:
>
> cr.openjdk.java.net/~darcy/8010679.1/
>
> -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 17:52:39 2013 -0700
> @@ -32,49 +32,74 @@
> * Represents an annotated element of the program currently running in
> this
> * VM. This interface allows annotations to be read reflectively. All
> * annotations returned by methods in this interface are immutable and
> - * serializable. It is permissible for the caller to modify the
> - * arrays returned by accessors for array-valued enum members; it will
> - * have no affect on the arrays returned to other callers.
> + * serializable. The arrays returned by methods of this interface may
> be modified
> + * by callers without affecting the arrays returned to other callers.
> *
> * The {@link #getAnnotationsByType(Class)} and {@link
> * #getDeclaredAnnotationsByType(Class)} methods support multiple
> - * annotations of the same type on an element. If the argument to
> either method
> - * is a repeatable annotation type (JLS 9.6), then the method will "look
> - * through" a container annotation (JLS 9.7) which was generated at
> - * compile-time to wrap multiple annotations of the argument type.
> + * annotations of the same type on an element. If the argument to
> + * either method is a repeatable annotation type (JLS 9.6), then the
> + * method will "look through" a container annotation (JLS 9.7) and
> + * return the one or more annotations inside the container. Container
> + * annotations may be generated at compile-time to wrap multiple
> + * annotations of the argument type.
> *
> - *
The terms directly present and present are used
> - * throughout this interface to describe precisely which annotations are
> - * returned by methods:
> + *
The terms directly present, indirectly present,
> + * present, and associated are used throughout this
> + * interface to describe precisely which annotations are returned by
> + * methods:
> *
> *
> - * - An annotation A is directly present on an element E if
> E is
> - * associated with a RuntimeVisibleAnnotations or
> - * RuntimeVisibleParameterAnnotations attribute, and:
> + *
> + *
- An annotation A is directly present on an
> + * element E if E has a {@code
> + * RuntimeVisibleAnnotations} or {@code
> + * RuntimeVisibleParameterAnnotations} or {@code
> + * RuntimeVisibleTypeAnnotations} attribute, and the attribute
> + * contains A.
> + *
> + *
- An annotation A is indirectly present on an
> + * element E if E has a {@code RuntimeVisibleAnnotations} or
> + * {@code RuntimeVisibleParameterAnnotations} or {@code
> RuntimeVisibleTypeAnnotations}
> + * attribute, and A 's type is repeatable, and the attribute
> contains
> + * exactly one annotation whose value element contains A and whose
> + * type is the containing annotation type of A 's type.
> + *
> + *
- An annotation A is present on an element E if either:
> *
> *
> - * - for an invocation of {@code get[Declared]Annotation(Class)} or
> - * {@code get[Declared]Annotations()}, the attribute contains A.
> *
> - *
- for an invocation of {@code
> get[Declared]AnnotationsByType(Class)}, 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).
> + *
- A is directly present on E; or
> + *
> + *
- No annotation of A 's type is directly present on
> + * E, and E is a class, and A 's type is
> + * inheritable, and A is present on the superclass of E.
> + *
> *
> *
> - *
> - *
- An annotation A is present on an element E if either:
> + *
- An annotation A is associated with an element
> E
> + * if either:
> *
> *
> - * - A is directly present on E; or
> *
> - *
- A is not directly present on E, and E is a class, and
> A's type
> - * is inheritable (JLS 9.6.3.3), and A is present on the
> superclass of
> - * E.
> + *
- A is directly or indirectly present on E; or
> + *
> + *
- No annotation of A 's type is directly or indirectly
> + * present on E, and E is a class, and A's type
> + * is inheritable, and A is associated with the superclass of
> + * E.
> + *
> *
> *
> *
> *
> + * For an invocation of {@code get[Declared]AnnotationsByType( Class <
> + * T >)}, the order of annotations which are directly or indirectly
> + * present on an element E is computed as if indirectly present
> + * annotations on E are directly present on E in place
> + * of their container annotation, in the order in which they appear in
> + * the value element of the container annotation.
> +
> * 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 +110,11 @@
> * a {@link EnumConstantNotPresentException} if the enum constant in the
> * annotation is no longer present in the enum type.
> *
> - *
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}.
> + *
If an annotation type T is (meta-)annotated with an
> + * {@code @Repeatable} annotation whose value element indicates a type
> + * TC, but TC does not declare a {@code value()} method
> + * with a return type of T{@code []}, then an exception of type
> + * {@link java.lang.annotation.AnnotationFormatError} is thrown.
> *
> *
Finally, attempting to read a member whose definition has evolved
> * incompatibly will result in a {@link
> @@ -106,7 +132,7 @@
> public interface AnnotatedElement {
> /**
> * Returns true if an annotation for the specified type
> - * is present on this element, else false. This method
> + * is present on this element, else false. This method
> * is designed primarily for convenient access to marker annotations.
> *
> *
The truth value returned by this method is equivalent to:
> @@ -128,7 +154,7 @@
>
> /**
> * Returns this element's annotation for the specified type if
> - * such an annotation is present, else null.
> + * such an annotation is present, else null.
> *
> * @param the type of the annotation to query for and return
> if present
> * @param annotationClass the Class object corresponding to the
> @@ -141,9 +167,9 @@
> T getAnnotation(Class annotationClass);
>
> /**
> - * Returns annotations that are present on this element.
> + * Returns annotations that are associated with this element.
> *
> - * If there are no annotations present on this element,
> the return
> + * If there are no annotations associated with this
> element, the return
> * value is an array of length 0.
> *
> * The difference between this method and {@link
> #getAnnotation(Class)}
> @@ -159,7 +185,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,27 +207,30 @@
>
> /**
> * Returns this element's annotation for the specified type if
> - * such an annotation is present, else null.
> + * such an annotation is directly present, else null.
> *
> * This method ignores inherited annotations. (Returns null if no
> * annotations are directly present on this element.)
> *
> - * @param the type of the annotation to query for and return if
> present
> + * @param 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
> */
> T getDeclaredAnnotation(Class
> annotationClass);
>
> /**
> - * Returns annotations that are directly present on this
> element.
> - * This method ignores inherited annotations.
> + * Returns this element's annotation(s) for the specified type if
> + * such annotations are either directly present or
> + * indirectly present. This method ignores inherited
> + * annotations.
> *
> - * If there are no annotations directly present on this
> element,
> - * the return value is an array of length 0.
> + * If there are no specified annotations directly or indirectly
> + * present on this element, the return value is an array of length
> + * 0.
> *
> * The difference between this method and {@link
> * #getDeclaredAnnotation(Class)} is that this method detects if its
> @@ -213,11 +242,11 @@
> * have no effect on the arrays returned to other callers.
> *
> * @param the type of the annotation to query for and return
> - * if directly present
> + * if directly or indirectly present
> * @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
> */
>
>
From alex.buckley at oracle.com Wed Jul 10 11:29:48 2013
From: alex.buckley at oracle.com (Alex Buckley)
Date: Wed, 10 Jul 2013 11:29:48 -0700
Subject: Review request for present, directly present,
etc. in core reflection javadoc
In-Reply-To: <51DCBB2D.9090803@oracle.com>
References: <51DC8397.8000508@oracle.com> <51DC9613.8050404@oracle.com>
<51DCBB2D.9090803@oracle.com>
Message-ID: <51DDA81C.8090506@oracle.com>
Elena Votchennikova pointed out in a comment of JDK-8010679 that classes
which implement AnnotatedElement contain method specifications copied
from AnnotatedElement. I believe the following classes need to have
their method specifications updated:
- j.l.Class
- j.l.Package
- j.l.r.AccessibleObject
(re: j.l.r.Field, j.l.r.Executable, j.l.r.Method, j.l.r.Constructor)
- j.l.r.Parameter
Alex
On 7/9/2013 6:38 PM, Joe Darcy wrote:
> Hi Alex,
>
> On 07/09/2013 04:00 PM, Alex Buckley wrote:
>> Hi Joe,
>>
>> Thanks for applying these spec changes to the API. I note the
>> refactoring in get[Declared]AnnotationByType so that the order of
>> directly + indirectly present annotations is specified earlier.
>>
>> One omission: getDeclaredAnnotationsByType still says it returns
>> directly present annotations, when it should say directly _or
>> indirectly_ present annotations. After all, that method is different
>> than getDeclaredAnnotations precisely because of look-through. Please
>> see item 2 in the bug.
>>
>>
>
> Another iteration on the specification changes below; revised webrev at:
>
> cr.openjdk.java.net/~darcy/8010679.1/
>
> -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 17:52:39 2013 -0700
> @@ -32,49 +32,74 @@
> * Represents an annotated element of the program currently running in
> this
> * VM. This interface allows annotations to be read reflectively. All
> * annotations returned by methods in this interface are immutable and
> - * serializable. It is permissible for the caller to modify the
> - * arrays returned by accessors for array-valued enum members; it will
> - * have no affect on the arrays returned to other callers.
> + * serializable. The arrays returned by methods of this interface may
> be modified
> + * by callers without affecting the arrays returned to other callers.
> *
> * The {@link #getAnnotationsByType(Class)} and {@link
> * #getDeclaredAnnotationsByType(Class)} methods support multiple
> - * annotations of the same type on an element. If the argument to
> either method
> - * is a repeatable annotation type (JLS 9.6), then the method will "look
> - * through" a container annotation (JLS 9.7) which was generated at
> - * compile-time to wrap multiple annotations of the argument type.
> + * annotations of the same type on an element. If the argument to
> + * either method is a repeatable annotation type (JLS 9.6), then the
> + * method will "look through" a container annotation (JLS 9.7) and
> + * return the one or more annotations inside the container. Container
> + * annotations may be generated at compile-time to wrap multiple
> + * annotations of the argument type.
> *
> - *
The terms directly present and present are used
> - * throughout this interface to describe precisely which annotations are
> - * returned by methods:
> + *
The terms directly present, indirectly present,
> + * present, and associated are used throughout this
> + * interface to describe precisely which annotations are returned by
> + * methods:
> *
> *
> - * - An annotation A is directly present on an element E if
> E is
> - * associated with a RuntimeVisibleAnnotations or
> - * RuntimeVisibleParameterAnnotations attribute, and:
> + *
> + *
- An annotation A is directly present on an
> + * element E if E has a {@code
> + * RuntimeVisibleAnnotations} or {@code
> + * RuntimeVisibleParameterAnnotations} or {@code
> + * RuntimeVisibleTypeAnnotations} attribute, and the attribute
> + * contains A.
> + *
> + *
- An annotation A is indirectly present on an
> + * element E if E has a {@code RuntimeVisibleAnnotations} or
> + * {@code RuntimeVisibleParameterAnnotations} or {@code
> RuntimeVisibleTypeAnnotations}
> + * attribute, and A 's type is repeatable, and the attribute
> contains
> + * exactly one annotation whose value element contains A and whose
> + * type is the containing annotation type of A 's type.
> + *
> + *
- An annotation A is present on an element E if either:
> *
> *
> - * - for an invocation of {@code get[Declared]Annotation(Class)} or
> - * {@code get[Declared]Annotations()}, the attribute contains A.
> *
> - *
- for an invocation of {@code
> get[Declared]AnnotationsByType(Class)}, 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).
> + *
- A is directly present on E; or
> + *
> + *
- No annotation of A 's type is directly present on
> + * E, and E is a class, and A 's type is
> + * inheritable, and A is present on the superclass of E.
> + *
> *
> *
> - *
> - *
- An annotation A is present on an element E if either:
> + *
- An annotation A is associated with an element
> E
> + * if either:
> *
> *
> - * - A is directly present on E; or
> *
> - *
- A is not directly present on E, and E is a class, and
> A's type
> - * is inheritable (JLS 9.6.3.3), and A is present on the
> superclass of
> - * E.
> + *
- A is directly or indirectly present on E; or
> + *
> + *
- No annotation of A 's type is directly or indirectly
> + * present on E, and E is a class, and A's type
> + * is inheritable, and A is associated with the superclass of
> + * E.
> + *
> *
> *
> *
> *
> + * For an invocation of {@code get[Declared]AnnotationsByType( Class <
> + * T >)}, the order of annotations which are directly or indirectly
> + * present on an element E is computed as if indirectly present
> + * annotations on E are directly present on E in place
> + * of their container annotation, in the order in which they appear in
> + * the value element of the container annotation.
> +
> * 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 +110,11 @@
> * a {@link EnumConstantNotPresentException} if the enum constant in the
> * annotation is no longer present in the enum type.
> *
> - *
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}.
> + *
If an annotation type T is (meta-)annotated with an
> + * {@code @Repeatable} annotation whose value element indicates a type
> + * TC, but TC does not declare a {@code value()} method
> + * with a return type of T{@code []}, then an exception of type
> + * {@link java.lang.annotation.AnnotationFormatError} is thrown.
> *
> *
Finally, attempting to read a member whose definition has evolved
> * incompatibly will result in a {@link
> @@ -106,7 +132,7 @@
> public interface AnnotatedElement {
> /**
> * Returns true if an annotation for the specified type
> - * is present on this element, else false. This method
> + * is present on this element, else false. This method
> * is designed primarily for convenient access to marker annotations.
> *
> *
The truth value returned by this method is equivalent to:
> @@ -128,7 +154,7 @@
>
> /**
> * Returns this element's annotation for the specified type if
> - * such an annotation is present, else null.
> + * such an annotation is present, else null.
> *
> * @param the type of the annotation to query for and return
> if present
> * @param annotationClass the Class object corresponding to the
> @@ -141,9 +167,9 @@
> T getAnnotation(Class annotationClass);
>
> /**
> - * Returns annotations that are present on this element.
> + * Returns annotations that are associated with this element.
> *
> - * If there are no annotations present on this element,
> the return
> + * If there are no annotations associated with this
> element, the return
> * value is an array of length 0.
> *
> * The difference between this method and {@link
> #getAnnotation(Class)}
> @@ -159,7 +185,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,27 +207,30 @@
>
> /**
> * Returns this element's annotation for the specified type if
> - * such an annotation is present, else null.
> + * such an annotation is directly present, else null.
> *
> * This method ignores inherited annotations. (Returns null if no
> * annotations are directly present on this element.)
> *
> - * @param the type of the annotation to query for and return if
> present
> + * @param 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
> */
> T getDeclaredAnnotation(Class
> annotationClass);
>
> /**
> - * Returns annotations that are directly present on this
> element.
> - * This method ignores inherited annotations.
> + * Returns this element's annotation(s) for the specified type if
> + * such annotations are either directly present or
> + * indirectly present. This method ignores inherited
> + * annotations.
> *
> - * If there are no annotations directly present on this
> element,
> - * the return value is an array of length 0.
> + * If there are no specified annotations directly or indirectly
> + * present on this element, the return value is an array of length
> + * 0.
> *
> * The difference between this method and {@link
> * #getDeclaredAnnotation(Class)} is that this method detects if its
> @@ -213,11 +242,11 @@
> * have no effect on the arrays returned to other callers.
> *
> * @param the type of the annotation to query for and return
> - * if directly present
> + * if directly or indirectly present
> * @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
> */
>
>
From joel.franck at oracle.com Wed Jul 10 11:33:26 2013
From: joel.franck at oracle.com (=?iso-8859-1?Q?Joel_Borggr=E9n-Franck?=)
Date: Wed, 10 Jul 2013 20:33:26 +0200
Subject: Review request for present, directly present,
etc. in core reflection javadoc
In-Reply-To: <51DCBB2D.9090803@oracle.com>
References: <51DC8397.8000508@oracle.com> <51DC9613.8050404@oracle.com>
<51DCBB2D.9090803@oracle.com>
Message-ID: <64E6EEFF-0BDD-4B1E-B52D-52C1C0BCA95D@oracle.com>
Hi Joe,
On 10 jul 2013, at 03:38, Joe Darcy wrote:
Second paragraph:
> + * method will "look through" a container annotation (JLS 9.7) and
> + * return the one or more annotations inside the container. Container
> + * annotations may be generated at compile-time to wrap multiple
> + * annotations of the argument type.
> *
Is "the one or more" intended?
cheers
/Joel
From alex.buckley at oracle.com Wed Jul 10 12:05:17 2013
From: alex.buckley at oracle.com (Alex Buckley)
Date: Wed, 10 Jul 2013 12:05:17 -0700
Subject: Review request for present, directly present,
etc. in core reflection javadoc
In-Reply-To: <64E6EEFF-0BDD-4B1E-B52D-52C1C0BCA95D@oracle.com>
References: <51DC8397.8000508@oracle.com> <51DC9613.8050404@oracle.com>
<51DCBB2D.9090803@oracle.com>
<64E6EEFF-0BDD-4B1E-B52D-52C1C0BCA95D@oracle.com>
Message-ID: <51DDB06D.6000606@oracle.com>
On 7/10/2013 11:33 AM, Joel Borggr?n-Franck wrote:
> On 10 jul 2013, at 03:38, Joe Darcy wrote:
>
> Second paragraph:
>
>> + * method will "look through" a container annotation (JLS 9.7) and
>> + * return the one or more annotations inside the container. Container
>> + * annotations may be generated at compile-time to wrap multiple
>> + * annotations of the argument type.
>> *
>
> Is "the one or more" intended?
I think so, because typically the container annotation stores one or
more base annotations. If the text was "... and return the annotations
inside the container", then it implies there are always multiple
annotations, which is false.
It would be more general for the intro to say "... and return any
annotations inside the container", since that covers the "one or more"
case and also the rare "zero" case.
Alex
From joe.darcy at oracle.com Wed Jul 10 12:11:30 2013
From: joe.darcy at oracle.com (Joe Darcy)
Date: Wed, 10 Jul 2013 12:11:30 -0700
Subject: Review request for present, directly present,
etc. in core reflection javadoc
In-Reply-To: <51DDA81C.8090506@oracle.com>
References: <51DC8397.8000508@oracle.com> <51DC9613.8050404@oracle.com>
<51DCBB2D.9090803@oracle.com> <51DDA81C.8090506@oracle.com>
Message-ID: <51DDB1E2.30603@oracle.com>
On 07/10/2013 11:29 AM, Alex Buckley wrote:
> Elena Votchennikova pointed out in a comment of JDK-8010679 that
> classes which implement AnnotatedElement contain method specifications
> copied from AnnotatedElement. I believe the following classes need to
> have their method specifications updated:
>
> - j.l.Class
> - j.l.Package
> - j.l.r.AccessibleObject
> (re: j.l.r.Field, j.l.r.Executable, j.l.r.Method, j.l.r.Constructor)
> - j.l.r.Parameter
The specifications on the implementation classes should generally just
be @inheritdoc'ed (meaning no explicit update should be needed in those
files), but I'll double check.
-Joe
From alex.buckley at oracle.com Wed Jul 10 12:25:16 2013
From: alex.buckley at oracle.com (Alex Buckley)
Date: Wed, 10 Jul 2013 12:25:16 -0700
Subject: Review request for present, directly present,
etc. in core reflection javadoc
In-Reply-To: <51DDB1E2.30603@oracle.com>
References: <51DC8397.8000508@oracle.com> <51DC9613.8050404@oracle.com>
<51DCBB2D.9090803@oracle.com> <51DDA81C.8090506@oracle.com>
<51DDB1E2.30603@oracle.com>
Message-ID: <51DDB51C.9060300@oracle.com>
On 7/10/2013 12:11 PM, Joe Darcy wrote:
> On 07/10/2013 11:29 AM, Alex Buckley wrote:
>> Elena Votchennikova pointed out in a comment of JDK-8010679 that
>> classes which implement AnnotatedElement contain method specifications
>> copied from AnnotatedElement. I believe the following classes need to
>> have their method specifications updated:
>>
>> - j.l.Class
>> - j.l.Package
>> - j.l.r.AccessibleObject
>> (re: j.l.r.Field, j.l.r.Executable, j.l.r.Method, j.l.r.Constructor)
>> - j.l.r.Parameter
>
> The specifications on the implementation classes should generally just
> be @inheritdoc'ed (meaning no explicit update should be needed in those
> files), but I'll double check.
Is there a reason why isAnnotationPresent in the classes has an
@inheritDoc for its main description, but the six
get[Declared]Annotation... methods don't?
Alex
From joe.darcy at oracle.com Wed Jul 10 13:38:11 2013
From: joe.darcy at oracle.com (Joe Darcy)
Date: Wed, 10 Jul 2013 13:38:11 -0700
Subject: Review request for present, directly present,
etc. in core reflection javadoc
In-Reply-To: <51DDB51C.9060300@oracle.com>
References: <51DC8397.8000508@oracle.com> <51DC9613.8050404@oracle.com>
<51DCBB2D.9090803@oracle.com> <51DDA81C.8090506@oracle.com>
<51DDB1E2.30603@oracle.com> <51DDB51C.9060300@oracle.com>
Message-ID: <51DDC633.6080000@oracle.com>
On 07/10/2013 12:25 PM, Alex Buckley wrote:
> On 7/10/2013 12:11 PM, Joe Darcy wrote:
>> On 07/10/2013 11:29 AM, Alex Buckley wrote:
>>> Elena Votchennikova pointed out in a comment of JDK-8010679 that
>>> classes which implement AnnotatedElement contain method specifications
>>> copied from AnnotatedElement. I believe the following classes need to
>>> have their method specifications updated:
>>>
>>> - j.l.Class
>>> - j.l.Package
>>> - j.l.r.AccessibleObject
>>> (re: j.l.r.Field, j.l.r.Executable, j.l.r.Method, j.l.r.Constructor)
>>> - j.l.r.Parameter
>>
>> The specifications on the implementation classes should generally just
>> be @inheritdoc'ed (meaning no explicit update should be needed in those
>> files), but I'll double check.
>
> Is there a reason why isAnnotationPresent in the classes has an
> @inheritDoc for its main description, but the six
> get[Declared]Annotation... methods don't?
>
There is an implicit @inheritDoc if the method has no documentation, to
the explicit @inheritDoc is fine but not strictly required.
-Joe
From elena.votchennikova at oracle.com Thu Jul 11 04:13:55 2013
From: elena.votchennikova at oracle.com (elena votchennikova)
Date: Thu, 11 Jul 2013 15:13:55 +0400
Subject: Review request for present, directly present, etc. in core
reflection javadoc
In-Reply-To: <51DDB1E2.30603@oracle.com>
References: <51DC8397.8000508@oracle.com> <51DC9613.8050404@oracle.com>
<51DCBB2D.9090803@oracle.com> <51DDA81C.8090506@oracle.com>
<51DDB1E2.30603@oracle.com>
Message-ID: <51DE9373.6020308@oracle.com>
Hi Joe,
specifications for methods getDeclaredAnnotation(Class),
getDeclaredAnnotations(), getDeclaredAnnotationsByType(Class) is valid
and there are no contradiction (formally).
But the following classes
- j.l.Package
- j.l.r.AccessibleObject
(re: j.l.r.Field, j.l.r.Executable, j.l.r.Method, j.l.r.Constructor)
- j.l.r.Parameter
can have only directly present annotation. So, I think this is strange
to describe in the specification cases for inherited annotations for
these classes, because it could mislead readers.
Elena
On 10.07.2013 23:11, Joe Darcy wrote:
> On 07/10/2013 11:29 AM, Alex Buckley wrote:
>> Elena Votchennikova pointed out in a comment of JDK-8010679 that
>> classes which implement AnnotatedElement contain method
>> specifications copied from AnnotatedElement. I believe the following
>> classes need to have their method specifications updated:
>>
>> - j.l.Class
>> - j.l.Package
>> - j.l.r.AccessibleObject
>> (re: j.l.r.Field, j.l.r.Executable, j.l.r.Method, j.l.r.Constructor)
>> - j.l.r.Parameter
>
> The specifications on the implementation classes should generally just
> be @inheritdoc'ed (meaning no explicit update should be needed in
> those files), but I'll double check.
>
> -Joe
>
From joe.darcy at oracle.com Thu Jul 11 10:58:48 2013
From: joe.darcy at oracle.com (Joe Darcy)
Date: Thu, 11 Jul 2013 10:58:48 -0700
Subject: Review request for present, directly present,
etc. in core reflection javadoc
In-Reply-To: <51DE9373.6020308@oracle.com>
References: <51DC8397.8000508@oracle.com> <51DC9613.8050404@oracle.com>
<51DCBB2D.9090803@oracle.com> <51DDA81C.8090506@oracle.com>
<51DDB1E2.30603@oracle.com> <51DE9373.6020308@oracle.com>
Message-ID: <51DEF258.3060507@oracle.com>
Hello Elena,
On 07/11/2013 04:13 AM, elena votchennikova wrote:
> Hi Joe,
>
> specifications for methods getDeclaredAnnotation(Class),
> getDeclaredAnnotations(), getDeclaredAnnotationsByType(Class) is valid
> and there are no contradiction (formally).
> But the following classes
> - j.l.Package
> - j.l.r.AccessibleObject
> (re: j.l.r.Field, j.l.r.Executable, j.l.r.Method, j.l.r.Constructor)
> - j.l.r.Parameter
> can have only directly present annotation. So, I think this is strange
> to describe in the specification cases for inherited annotations for
> these classes, because it could mislead readers.
When managing javadoc along different points in an type hierarchy, there
is a trade-off between making statements that are universally true in
the parent type (listing all the special cases) so that there is only
one copy of a method's specification and creating specialized copies of
the specification at each location. (This is more pronounced in
interface-only hierarchies where a method from a supertype method
doesn't get an explicit inclusion unless it is overridden. When a class
implements an interface, the implementation will get its own javadoc
entry even if it is just inherited from the interface.)
The former approach offers benefits in maintainability at the risk of
giving the user some irrelevant information for overridden methods.
For this work, the version of the specification in AnnotatedElement
needs to have all the special cases laid out. To follow your guidance,
there would in addition need to be
* A specialized version of the specification for j.l.Class covering
inheritance
* Three *independently maintained* copies specialized to ignore inheritance:
* AccessibleObject (covers Field, Method, Constructor)
* j.l.Package
* j.l.r.Parameter
So I don't think it is a good trade-off to go from managing 1 copy of
the javadoc in question to managing 5 copies.
Cheers,
-Joe
>
>
> Elena
>
>
> On 10.07.2013 23:11, Joe Darcy wrote:
>> On 07/10/2013 11:29 AM, Alex Buckley wrote:
>>> Elena Votchennikova pointed out in a comment of JDK-8010679 that
>>> classes which implement AnnotatedElement contain method
>>> specifications copied from AnnotatedElement. I believe the following
>>> classes need to have their method specifications updated:
>>>
>>> - j.l.Class
>>> - j.l.Package
>>> - j.l.r.AccessibleObject
>>> (re: j.l.r.Field, j.l.r.Executable, j.l.r.Method, j.l.r.Constructor)
>>> - j.l.r.Parameter
>>
>> The specifications on the implementation classes should generally
>> just be @inheritdoc'ed (meaning no explicit update should be needed
>> in those files), but I'll double check.
>>
>> -Joe
>>
>
From joe.darcy at oracle.com Thu Jul 11 12:36:38 2013
From: joe.darcy at oracle.com (Joe Darcy)
Date: Thu, 11 Jul 2013 12:36:38 -0700
Subject: Review request for present, directly present,
etc. in core reflection javadoc
In-Reply-To: <51DDB06D.6000606@oracle.com>
References: <51DC8397.8000508@oracle.com> <51DC9613.8050404@oracle.com>
<51DCBB2D.9090803@oracle.com>
<64E6EEFF-0BDD-4B1E-B52D-52C1C0BCA95D@oracle.com>
<51DDB06D.6000606@oracle.com>
Message-ID: <51DF0946.7010201@oracle.com>
On 07/10/2013 12:05 PM, Alex Buckley wrote:
> On 7/10/2013 11:33 AM, Joel Borggr?n-Franck wrote:
>> On 10 jul 2013, at 03:38, Joe Darcy wrote:
>>
>> Second paragraph:
>>
>>> + * method will "look through" a container annotation (JLS 9.7) and
>>> + * return the one or more annotations inside the container. Container
>>> + * annotations may be generated at compile-time to wrap multiple
>>> + * annotations of the argument type.
>>> *
>>
>> Is "the one or more" intended?
>
> I think so, because typically the container annotation stores one or
> more base annotations. If the text was "... and return the annotations
> inside the container", then it implies there are always multiple
> annotations, which is false.
>
> It would be more general for the intro to say "... and return any
> annotations inside the container", since that covers the "one or more"
> case and also the rare "zero" case.
>
Hello,
Typo Joel noticed fixed, methods reordered, some wording changed, and
helpful summary table added:
Kind of Presence
Method Directly Present Indirectly Present Present Associated
|T getAnnotation(Class)|
X
|Annotation[] getAnnotations()|
X
|T[] getAnnotationsByType(Class|
X
|T getDeclaredAnnotation(Class)|
X
|T[] getDeclaredAnnotationsByType(Class)|
X X
|Annotation[] getDeclaredAnnotations()|
X
Patch below; full webrev at:
http://cr.openjdk.java.net/~darcy/8010679.2/
All the text for the javadoc these methods currently comes from the
interface.
Thanks,
-Joe
--- old/src/share/classes/java/lang/reflect/AnnotatedElement.java
2013-07-11 12:26:50.000000000 -0700
+++ new/src/share/classes/java/lang/reflect/AnnotatedElement.java
2013-07-11 12:26:49.000000000 -0700
@@ -32,49 +32,101 @@
* Represents an annotated element of the program currently running in
this
* VM. This interface allows annotations to be read reflectively. All
* annotations returned by methods in this interface are immutable and
- * serializable. It is permissible for the caller to modify the
- * arrays returned by accessors for array-valued enum members; it will
- * have no affect on the arrays returned to other callers.
+ * serializable. The arrays returned by methods of this interface may
be modified
+ * by callers without affecting the arrays returned to other callers.
*
* The {@link #getAnnotationsByType(Class)} and {@link
* #getDeclaredAnnotationsByType(Class)} methods support multiple
- * annotations of the same type on an element. If the argument to
either method
- * is a repeatable annotation type (JLS 9.6), then the method will "look
- * through" a container annotation (JLS 9.7) which was generated at
- * compile-time to wrap multiple annotations of the argument type.
- *
- *
The terms directly present and present are used
- * throughout this interface to describe precisely which annotations are
- * returned by methods:
+ * annotations of the same type on an element. If the argument to
+ * either method is a repeatable annotation type (JLS 9.6), then the
+ * method will "look through" a container annotation (JLS 9.7), if
+ * present, and return any annotations inside the container. Container
+ * annotations may be generated at compile-time to wrap multiple
+ * annotations of the argument type.
+ *
+ *
The terms directly present, indirectly present,
+ * present, and associated are used throughout this
+ * interface to describe precisely which annotations are returned by
+ * methods:
*
*
- * - An annotation A is directly present on an element E if E is
- * associated with a RuntimeVisibleAnnotations or
- * RuntimeVisibleParameterAnnotations attribute, and:
+ *
+ *
- An annotation A is directly present on an
+ * element E if E has a {@code
+ * RuntimeVisibleAnnotations} or {@code
+ * RuntimeVisibleParameterAnnotations} or {@code
+ * RuntimeVisibleTypeAnnotations} attribute, and the attribute
+ * contains A.
+ *
+ *
- An annotation A is indirectly present on an
+ * element E if E has a {@code RuntimeVisibleAnnotations} or
+ * {@code RuntimeVisibleParameterAnnotations} or {@code
RuntimeVisibleTypeAnnotations}
+ * attribute, and A 's type is repeatable, and the attribute
contains
+ * exactly one annotation whose value element contains A and whose
+ * type is the containing annotation type of A 's type.
+ *
+ *
- An annotation A is present on an element E if either:
*
*
- * - for an invocation of {@code get[Declared]Annotation(Class)} or
- * {@code get[Declared]Annotations()}, the attribute contains A.
*
- *
- for an invocation of {@code
get[Declared]AnnotationsByType(Class)}, 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).
+ *
- A is directly present on E; or
+ *
+ *
- No annotation of A 's type is directly present on
+ * E, and E is a class, and A 's type is
+ * inheritable, and A is present on the superclass of E.
+ *
*
*
- *
- *
- An annotation A is present on an element E if either:
+ *
- An annotation A is associated with an element
E
+ * if either:
*
*
- * - A is directly present on E; or
*
- *
- A is not directly present on E, and E is a class, and
A's type
- * is inheritable (JLS 9.6.3.3), and A is present on the
superclass of
- * E.
+ *
- A is directly or indirectly present on E; or
+ *
+ *
- No annotation of A 's type is directly or indirectly
+ * present on E, and E is a class, and A's type
+ * is inheritable, and A is associated with the superclass of
+ * E.
+ *
*
*
*
*
+ * The table below summarizes which kind of annotation presence
+ * different methods in this interface examine.
+ *
+ *
+ * Overview of kind of presence detected by different
AnnotatedElement methods
+ * | Kind of Presence |
+ *
|---|
| Method | Directly Present | Indirectly
Present | Present | Associated |
+ *
|---|
| {@link #getAnnotation(Class) T getAnnotation(Class<T>)}
+ * | | | X | |
+ *
+ * | {@link #getAnnotations Annotation[] getAnnotations()}
+ * | | | X | |
+ *
+ * | {@link #getAnnotationsByType(Class) T[]
getAnnotationsByType(Class<T>}
+ * | | | | X |
+ *
+ * | {@link #getDeclaredAnnotation(Class) T
getDeclaredAnnotation(Class<T>)}
+ * | X | | | |
+ *
+ * | {@link #getDeclaredAnnotationsByType(Class) T[]
getDeclaredAnnotationsByType(Class<T>)}
+ * | X | X | | |
+ *
+ * | {@link #getDeclaredAnnotations Annotation[]
getDeclaredAnnotations()}
+ * | X | | | |
+ *
+ *
+ *
+ * For an invocation of {@code get[Declared]AnnotationsByType( Class <
+ * T >)}, the order of annotations which are directly or indirectly
+ * present on an element E is computed as if indirectly present
+ * annotations on E are directly present on E in place
+ * of their container annotation, in the order in which they appear in
+ * the value element of the container annotation.
+
*
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 +137,11 @@
* a {@link EnumConstantNotPresentException} if the enum constant in the
* annotation is no longer present in the enum type.
*
- *
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}.
+ *
If an annotation type T is (meta-)annotated with an
+ * {@code @Repeatable} annotation whose value element indicates a type
+ * TC, but TC does not declare a {@code value()} method
+ * with a return type of T{@code []}, then an exception of type
+ * {@link java.lang.annotation.AnnotationFormatError} is thrown.
*
*
Finally, attempting to read a member whose definition has evolved
* incompatibly will result in a {@link
@@ -106,7 +159,7 @@
public interface AnnotatedElement {
/**
* Returns true if an annotation for the specified type
- * is present on this element, else false. This method
+ * is present on this element, else false. This method
* is designed primarily for convenient access to marker annotations.
*
*
The truth value returned by this method is equivalent to:
@@ -128,7 +181,7 @@
/**
* Returns this element's annotation for the specified type if
- * such an annotation is present, else null.
+ * such an annotation is present, else null.
*
* @param the type of the annotation to query for and return
if present
* @param annotationClass the Class object corresponding to the
@@ -146,6 +199,20 @@
* If there are no annotations present on this element,
the return
* value is an array of length 0.
*
+ * The caller of this method is free to modify the returned array;
it will
+ * have no effect on the arrays returned to other callers.
+ *
+ * @return annotations present on this element
+ * @since 1.5
+ */
+ Annotation[] getAnnotations();
+
+ /**
+ * Returns annotations that are associated with this element.
+ *
+ * If there are no annotations associated with this
element, the return
+ * value is an array of length 0.
+ *
* The difference between this method and {@link
#getAnnotation(Class)}
* is that this method detects if its argument is a repeatable
* annotation type (JLS 9.6), and if so, attempts to find one or
@@ -159,65 +226,54 @@
* @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
*/
T[] getAnnotationsByType(Class
annotationClass);
/**
- * Returns annotations that are present on this element.
- *
- * If there are no annotations present on this element,
the return
- * value is an array of length 0.
- *
- * The caller of this method is free to modify the returned array;
it will
- * have no effect on the arrays returned to other callers.
- *
- * @return annotations present on this element
- * @since 1.5
- */
- Annotation[] getAnnotations();
-
- /**
* Returns this element's annotation for the specified type if
- * such an annotation is present, else null.
+ * such an annotation is directly present, else null.
*
* This method ignores inherited annotations. (Returns null if no
* annotations are directly present on this element.)
*
- * @param the type of the annotation to query for and return if
present
+ * @param 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
*/
T getDeclaredAnnotation(Class
annotationClass);
/**
- * Returns annotations that are directly present on this
element.
- * This method ignores inherited annotations.
- *
- * If there are no annotations directly present on this
element,
- * the return value is an array of length 0.
+ * Returns this element's annotation(s) for the specified type if
+ * such annotations are either directly present or
+ * indirectly present. This method ignores inherited
+ * annotations.
+ *
+ * If there are no specified annotations directly or indirectly
+ * present on this element, the return value is an array of length
+ * 0.
*
* The difference between this method and {@link
* #getDeclaredAnnotation(Class)} is that this method detects if its
* argument is a repeatable annotation type (JLS 9.6),
and if so,
* attempts to find one or more annotations of that type by "looking
- * through" a container annotation.
+ * through" a container annotation if one is present.
*
* The caller of this method is free to modify the returned array;
it will
* have no effect on the arrays returned to other callers.
*
* @param the type of the annotation to query for and return
- * if directly present
+ * if directly or indirectly present
* @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 or indirectly present on this element, else an
array of length zero
* @throws NullPointerException if the given annotation class is null
* @since 1.8
*/
From alex.buckley at oracle.com Thu Jul 11 15:35:29 2013
From: alex.buckley at oracle.com (Alex Buckley)
Date: Thu, 11 Jul 2013 15:35:29 -0700
Subject: Review request for present, directly present,
etc. in core reflection javadoc
In-Reply-To: <51DF0946.7010201@oracle.com>
References: <51DC8397.8000508@oracle.com> <51DC9613.8050404@oracle.com>
<51DCBB2D.9090803@oracle.com>
<64E6EEFF-0BDD-4B1E-B52D-52C1C0BCA95D@oracle.com>
<51DDB06D.6000606@oracle.com> <51DF0946.7010201@oracle.com>
Message-ID: <51DF3331.1000005@oracle.com>
I am glad that getAnnotation(...), getAnnotations(), and
getAnnotationsByType(...) are now presented in that order.
But I should have been clearer that this order also applies to
getDeclaredAnnotation(...), getDeclaredAnnotations(), and
getDeclaredAnnotationsByType(...). Each triple of methods has the same
natural order: legacy-legacy-new.
This also applies to the summary table:
T getAnnotation(Class)
Annotation[] getAnnotations()
T[] getAnnotationsByType(Class <-- missing ) in the webrev
T getDeclaredAnnotation(Class)
Annotation[] getDeclaredAnnotations()
T[] getDeclaredAnnotationsByType(Class)
- Since the text in the Method column is monospaced, could it be spaced
as above, so that method names line up?
- Consider adding a column after Method: "Since". Column values: 1.5 1.5
1.8 1.5 1.5 1.8.
Alex
On 7/11/2013 12:36 PM, Joe Darcy wrote:
> On 07/10/2013 12:05 PM, Alex Buckley wrote:
>> On 7/10/2013 11:33 AM, Joel Borggr?n-Franck wrote:
>>> On 10 jul 2013, at 03:38, Joe Darcy wrote:
>>>
>>> Second paragraph:
>>>
>>>> + * method will "look through" a container annotation (JLS 9.7) and
>>>> + * return the one or more annotations inside the container. Container
>>>> + * annotations may be generated at compile-time to wrap multiple
>>>> + * annotations of the argument type.
>>>> *
>>>
>>> Is "the one or more" intended?
>>
>> I think so, because typically the container annotation stores one or
>> more base annotations. If the text was "... and return the annotations
>> inside the container", then it implies there are always multiple
>> annotations, which is false.
>>
>> It would be more general for the intro to say "... and return any
>> annotations inside the container", since that covers the "one or more"
>> case and also the rare "zero" case.
>>
>
> Hello,
>
> Typo Joel noticed fixed, methods reordered, some wording changed, and
> helpful summary table added:
>
>
> Kind of Presence
> Method Directly Present Indirectly Present Present Associated
> |T getAnnotation(Class)|
>
>
>
> X
> |Annotation[] getAnnotations()|
>
>
>
> X
> |T[] getAnnotationsByType(Class|
>
>
>
>
> X
> |T getDeclaredAnnotation(Class)|
>
> X
>
>
> |T[] getDeclaredAnnotationsByType(Class)|
>
> X X
>
> |Annotation[] getDeclaredAnnotations()|
>
> X
>
>
>
>
>
> Patch below; full webrev at:
>
> http://cr.openjdk.java.net/~darcy/8010679.2/
>
> All the text for the javadoc these methods currently comes from the
> interface.
>
> Thanks,
>
> -Joe
>
>
> --- old/src/share/classes/java/lang/reflect/AnnotatedElement.java
> 2013-07-11 12:26:50.000000000 -0700
> +++ new/src/share/classes/java/lang/reflect/AnnotatedElement.java
> 2013-07-11 12:26:49.000000000 -0700
> @@ -32,49 +32,101 @@
> * Represents an annotated element of the program currently running in
> this
> * VM. This interface allows annotations to be read reflectively. All
> * annotations returned by methods in this interface are immutable and
> - * serializable. It is permissible for the caller to modify the
> - * arrays returned by accessors for array-valued enum members; it will
> - * have no affect on the arrays returned to other callers.
> + * serializable. The arrays returned by methods of this interface may
> be modified
> + * by callers without affecting the arrays returned to other callers.
> *
> * The {@link #getAnnotationsByType(Class)} and {@link
> * #getDeclaredAnnotationsByType(Class)} methods support multiple
> - * annotations of the same type on an element. If the argument to
> either method
> - * is a repeatable annotation type (JLS 9.6), then the method will "look
> - * through" a container annotation (JLS 9.7) which was generated at
> - * compile-time to wrap multiple annotations of the argument type.
> - *
> - *
The terms directly present and present are used
> - * throughout this interface to describe precisely which annotations are
> - * returned by methods:
> + * annotations of the same type on an element. If the argument to
> + * either method is a repeatable annotation type (JLS 9.6), then the
> + * method will "look through" a container annotation (JLS 9.7), if
> + * present, and return any annotations inside the container. Container
> + * annotations may be generated at compile-time to wrap multiple
> + * annotations of the argument type.
> + *
> + *
The terms directly present, indirectly present,
> + * present, and associated are used throughout this
> + * interface to describe precisely which annotations are returned by
> + * methods:
> *
> *
> - * - An annotation A is directly present on an element E if E is
> - * associated with a RuntimeVisibleAnnotations or
> - * RuntimeVisibleParameterAnnotations attribute, and:
> + *
> + *
- An annotation A is directly present on an
> + * element E if E has a {@code
> + * RuntimeVisibleAnnotations} or {@code
> + * RuntimeVisibleParameterAnnotations} or {@code
> + * RuntimeVisibleTypeAnnotations} attribute, and the attribute
> + * contains A.
> + *
> + *
- An annotation A is indirectly present on an
> + * element E if E has a {@code RuntimeVisibleAnnotations} or
> + * {@code RuntimeVisibleParameterAnnotations} or {@code
> RuntimeVisibleTypeAnnotations}
> + * attribute, and A 's type is repeatable, and the attribute
> contains
> + * exactly one annotation whose value element contains A and whose
> + * type is the containing annotation type of A 's type.
> + *
> + *
- An annotation A is present on an element E if either:
> *
> *
> - * - for an invocation of {@code get[Declared]Annotation(Class)} or
> - * {@code get[Declared]Annotations()}, the attribute contains A.
> *
> - *
- for an invocation of {@code
> get[Declared]AnnotationsByType(Class)}, 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).
> + *
- A is directly present on E; or
> + *
> + *
- No annotation of A 's type is directly present on
> + * E, and E is a class, and A 's type is
> + * inheritable, and A is present on the superclass of E.
> + *
> *
> *
> - *
> - *
- An annotation A is present on an element E if either:
> + *
- An annotation A is associated with an element
> E
> + * if either:
> *
> *
> - * - A is directly present on E; or
> *
> - *
- A is not directly present on E, and E is a class, and
> A's type
> - * is inheritable (JLS 9.6.3.3), and A is present on the
> superclass of
> - * E.
> + *
- A is directly or indirectly present on E; or
> + *
> + *
- No annotation of A 's type is directly or indirectly
> + * present on E, and E is a class, and A's type
> + * is inheritable, and A is associated with the superclass of
> + * E.
> + *
> *
> *
> *
> *
> + * The table below summarizes which kind of annotation presence
> + * different methods in this interface examine.
> + *
> + *
> + * Overview of kind of presence detected by different
> AnnotatedElement methods
> + * | Kind of Presence |
> + *
|---|
| Method | Directly Present | Indirectly
> Present | Present | Associated |
> + *
|---|
| {@link #getAnnotation(Class) T getAnnotation(Class<T>)}
> + * | | | X | |
> + *
> + * | {@link #getAnnotations Annotation[] getAnnotations()}
> + * | | | X | |
> + *
> + * | {@link #getAnnotationsByType(Class) T[]
> getAnnotationsByType(Class<T>}
> + * | | | | X |
> + *
> + * | {@link #getDeclaredAnnotation(Class) T
> getDeclaredAnnotation(Class<T>)}
> + * | X | | | |
> + *
> + * | {@link #getDeclaredAnnotationsByType(Class) T[]
> getDeclaredAnnotationsByType(Class<T>)}
> + * | X | X | | |
> + *
> + * | {@link #getDeclaredAnnotations Annotation[]
> getDeclaredAnnotations()}
> + * | X | | | |
> + *
> + *
> + *
> + * For an invocation of {@code get[Declared]AnnotationsByType( Class <
> + * T >)}, the order of annotations which are directly or indirectly
> + * present on an element E is computed as if indirectly present
> + * annotations on E are directly present on E in place
> + * of their container annotation, in the order in which they appear in
> + * the value element of the container annotation.
> +
> *
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 +137,11 @@
> * a {@link EnumConstantNotPresentException} if the enum constant in the
> * annotation is no longer present in the enum type.
> *
> - *
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}.
> + *
If an annotation type T is (meta-)annotated with an
> + * {@code @Repeatable} annotation whose value element indicates a type
> + * TC, but TC does not declare a {@code value()} method
> + * with a return type of T{@code []}, then an exception of type
> + * {@link java.lang.annotation.AnnotationFormatError} is thrown.
> *
> *
Finally, attempting to read a member whose definition has evolved
> * incompatibly will result in a {@link
> @@ -106,7 +159,7 @@
> public interface AnnotatedElement {
> /**
> * Returns true if an annotation for the specified type
> - * is present on this element, else false. This method
> + * is present on this element, else false. This method
> * is designed primarily for convenient access to marker annotations.
> *
> *
The truth value returned by this method is equivalent to:
> @@ -128,7 +181,7 @@
>
> /**
> * Returns this element's annotation for the specified type if
> - * such an annotation is present, else null.
> + * such an annotation is present, else null.
> *
> * @param the type of the annotation to query for and return
> if present
> * @param annotationClass the Class object corresponding to the
> @@ -146,6 +199,20 @@
> * If there are no annotations present on this element,
> the return
> * value is an array of length 0.
> *
> + * The caller of this method is free to modify the returned array;
> it will
> + * have no effect on the arrays returned to other callers.
> + *
> + * @return annotations present on this element
> + * @since 1.5
> + */
> + Annotation[] getAnnotations();
> +
> + /**
> + * Returns annotations that are associated with this element.
> + *
> + * If there are no annotations associated with this
> element, the return
> + * value is an array of length 0.
> + *
> * The difference between this method and {@link
> #getAnnotation(Class)}
> * is that this method detects if its argument is a repeatable
> * annotation type (JLS 9.6), and if so, attempts to find one or
> @@ -159,65 +226,54 @@
> * @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
> */
> T[] getAnnotationsByType(Class
> annotationClass);
>
> /**
> - * Returns annotations that are present on this element.
> - *
> - * If there are no annotations present on this element,
> the return
> - * value is an array of length 0.
> - *
> - * The caller of this method is free to modify the returned array;
> it will
> - * have no effect on the arrays returned to other callers.
> - *
> - * @return annotations present on this element
> - * @since 1.5
> - */
> - Annotation[] getAnnotations();
> -
> - /**
> * Returns this element's annotation for the specified type if
> - * such an annotation is present, else null.
> + * such an annotation is directly present, else null.
> *
> * This method ignores inherited annotations. (Returns null if no
> * annotations are directly present on this element.)
> *
> - * @param the type of the annotation to query for and return if
> present
> + * @param 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
> */
> T getDeclaredAnnotation(Class
> annotationClass);
>
> /**
> - * Returns annotations that are directly present on this
> element.
> - * This method ignores inherited annotations.
> - *
> - * If there are no annotations directly present on this
> element,
> - * the return value is an array of length 0.
> + * Returns this element's annotation(s) for the specified type if
> + * such annotations are either directly present or
> + * indirectly present. This method ignores inherited
> + * annotations.
> + *
> + * If there are no specified annotations directly or indirectly
> + * present on this element, the return value is an array of length
> + * 0.
> *
> * The difference between this method and {@link
> * #getDeclaredAnnotation(Class)} is that this method detects if its
> * argument is a repeatable annotation type (JLS 9.6),
> and if so,
> * attempts to find one or more annotations of that type by "looking
> - * through" a container annotation.
> + * through" a container annotation if one is present.
> *
> * The caller of this method is free to modify the returned array;
> it will
> * have no effect on the arrays returned to other callers.
> *
> * @param the type of the annotation to query for and return
> - * if directly present
> + * if directly or indirectly present
> * @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 or indirectly present on this element, else an
> array of length zero
> * @throws NullPointerException if the given annotation class is null
> * @since 1.8
> */
>
From joe.darcy at oracle.com Thu Jul 11 23:01:33 2013
From: joe.darcy at oracle.com (Joe Darcy)
Date: Thu, 11 Jul 2013 23:01:33 -0700
Subject: Review request for present, directly present,
etc. in core reflection javadoc
In-Reply-To: <51DF3331.1000005@oracle.com>
References: <51DC8397.8000508@oracle.com> <51DC9613.8050404@oracle.com>
<51DCBB2D.9090803@oracle.com>
<64E6EEFF-0BDD-4B1E-B52D-52C1C0BCA95D@oracle.com>
<51DDB06D.6000606@oracle.com> <51DF0946.7010201@oracle.com>
<51DF3331.1000005@oracle.com>
Message-ID: <51DF9BBD.1000604@oracle.com>
Hello,
On 07/11/2013 03:35 PM, Alex Buckley wrote:
> I am glad that getAnnotation(...), getAnnotations(), and
> getAnnotationsByType(...) are now presented in that order.
>
> But I should have been clearer that this order also applies to
> getDeclaredAnnotation(...), getDeclaredAnnotations(), and
> getDeclaredAnnotationsByType(...). Each triple of methods has the same
> natural order: legacy-legacy-new.
Reordered.
>
> This also applies to the summary table:
>
> T getAnnotation(Class)
> Annotation[] getAnnotations()
> T[] getAnnotationsByType(Class <-- missing ) in the webrev
Fixed.
> T getDeclaredAnnotation(Class)
> Annotation[] getDeclaredAnnotations()
> T[] getDeclaredAnnotationsByType(Class)
>
> - Since the text in the Method column is monospaced, could it be
> spaced as above, so that method names line up?
I broke this up into two columns for display purposes.
>
> - Consider adding a column after Method: "Since". Column values: 1.5
> 1.5 1.8 1.5 1.5 1.8.
I think that would look dated very quickly.
Patch below; webrev at
http://cr.openjdk.java.net/~darcy/8010679.3/
Thanks,
-Joe
--- old/src/share/classes/java/lang/reflect/AnnotatedElement.java
2013-07-11 22:57:50.000000000 -0700
+++ new/src/share/classes/java/lang/reflect/AnnotatedElement.java
2013-07-11 22:57:49.000000000 -0700
@@ -32,49 +32,101 @@
* Represents an annotated element of the program currently running in
this
* VM. This interface allows annotations to be read reflectively. All
* annotations returned by methods in this interface are immutable and
- * serializable. It is permissible for the caller to modify the
- * arrays returned by accessors for array-valued enum members; it will
- * have no affect on the arrays returned to other callers.
+ * serializable. The arrays returned by methods of this interface may
be modified
+ * by callers without affecting the arrays returned to other callers.
*
* The {@link #getAnnotationsByType(Class)} and {@link
* #getDeclaredAnnotationsByType(Class)} methods support multiple
- * annotations of the same type on an element. If the argument to
either method
- * is a repeatable annotation type (JLS 9.6), then the method will "look
- * through" a container annotation (JLS 9.7) which was generated at
- * compile-time to wrap multiple annotations of the argument type.
- *
- *
The terms directly present and present are used
- * throughout this interface to describe precisely which annotations are
- * returned by methods:
+ * annotations of the same type on an element. If the argument to
+ * either method is a repeatable annotation type (JLS 9.6), then the
+ * method will "look through" a container annotation (JLS 9.7), if
+ * present, and return any annotations inside the container. Container
+ * annotations may be generated at compile-time to wrap multiple
+ * annotations of the argument type.
+ *
+ *
The terms directly present, indirectly present,
+ * present, and associated are used throughout this
+ * interface to describe precisely which annotations are returned by
+ * methods:
*
*
- * - An annotation A is directly present on an element E if E is
- * associated with a RuntimeVisibleAnnotations or
- * RuntimeVisibleParameterAnnotations attribute, and:
+ *
+ *
- An annotation A is directly present on an
+ * element E if E has a {@code
+ * RuntimeVisibleAnnotations} or {@code
+ * RuntimeVisibleParameterAnnotations} or {@code
+ * RuntimeVisibleTypeAnnotations} attribute, and the attribute
+ * contains A.
+ *
+ *
- An annotation A is indirectly present on an
+ * element E if E has a {@code RuntimeVisibleAnnotations} or
+ * {@code RuntimeVisibleParameterAnnotations} or {@code
RuntimeVisibleTypeAnnotations}
+ * attribute, and A 's type is repeatable, and the attribute
contains
+ * exactly one annotation whose value element contains A and whose
+ * type is the containing annotation type of A 's type.
+ *
+ *
- An annotation A is present on an element E if either:
*
*
- * - for an invocation of {@code get[Declared]Annotation(Class)} or
- * {@code get[Declared]Annotations()}, the attribute contains A.
*
- *
- for an invocation of {@code
get[Declared]AnnotationsByType(Class)}, 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).
+ *
- A is directly present on E; or
+ *
+ *
- No annotation of A 's type is directly present on
+ * E, and E is a class, and A 's type is
+ * inheritable, and A is present on the superclass of E.
+ *
*
*
- *
- *
- An annotation A is present on an element E if either:
+ *
- An annotation A is associated with an element
E
+ * if either:
*
*
- * - A is directly present on E; or
*
- *
- A is not directly present on E, and E is a class, and
A's type
- * is inheritable (JLS 9.6.3.3), and A is present on the
superclass of
- * E.
+ *
- A is directly or indirectly present on E; or
+ *
+ *
- No annotation of A 's type is directly or indirectly
+ * present on E, and E is a class, and A's type
+ * is inheritable, and A is associated with the superclass of
+ * E.
+ *
*
*
*
*
+ * The table below summarizes which kind of annotation presence
+ * different methods in this interface examine.
+ *
+ *
+ * Overview of kind of presence detected by different
AnnotatedElement methods
+ * | Kind of Presence |
+ *
|---|
| Method | Directly Present | Indirectly
Present | Present | Associated |
+ *
|---|
| {@code T} | {@link #getAnnotation(Class)
getAnnotation(Class<T>)}
+ * | | | X | |
+ *
+ * | {@code Annotation[]} | {@link
#getAnnotations getAnnotations()}
+ * | | | X | |
+ *
+ * | {@code T[]} | {@link
#getAnnotationsByType(Class) getAnnotationsByType(Class<T>)}
+ * | | | | X |
+ *
+ * | {@code T} | {@link
#getDeclaredAnnotation(Class) getDeclaredAnnotation(Class<T>)}
+ * | X | | | |
+ *
+ * | {@code Annotation[]} | {@link
#getDeclaredAnnotations getDeclaredAnnotations()}
+ * | X | | | |
+ *
+ * | {@code T[]} | {@link
#getDeclaredAnnotationsByType(Class)
getDeclaredAnnotationsByType(Class<T>)}
+ * | X | X | | |
+ *
+ *
+ *
+ * For an invocation of {@code get[Declared]AnnotationsByType( Class <
+ * T >)}, the order of annotations which are directly or indirectly
+ * present on an element E is computed as if indirectly present
+ * annotations on E are directly present on E in place
+ * of their container annotation, in the order in which they appear in
+ * the value element of the container annotation.
+
*
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 +137,11 @@
* a {@link EnumConstantNotPresentException} if the enum constant in the
* annotation is no longer present in the enum type.
*
- *
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}.
+ *
If an annotation type T is (meta-)annotated with an
+ * {@code @Repeatable} annotation whose value element indicates a type
+ * TC, but TC does not declare a {@code value()} method
+ * with a return type of T{@code []}, then an exception of type
+ * {@link java.lang.annotation.AnnotationFormatError} is thrown.
*
*
Finally, attempting to read a member whose definition has evolved
* incompatibly will result in a {@link
@@ -106,7 +159,7 @@
public interface AnnotatedElement {
/**
* Returns true if an annotation for the specified type
- * is present on this element, else false. This method
+ * is present on this element, else false. This method
* is designed primarily for convenient access to marker annotations.
*
*
The truth value returned by this method is equivalent to:
@@ -128,7 +181,7 @@
/**
* Returns this element's annotation for the specified type if
- * such an annotation is present, else null.
+ * such an annotation is present, else null.
*
* @param the type of the annotation to query for and return
if present
* @param annotationClass the Class object corresponding to the
@@ -146,6 +199,20 @@
* If there are no annotations present on this element,
the return
* value is an array of length 0.
*
+ * The caller of this method is free to modify the returned array;
it will
+ * have no effect on the arrays returned to other callers.
+ *
+ * @return annotations present on this element
+ * @since 1.5
+ */
+ Annotation[] getAnnotations();
+
+ /**
+ * Returns annotations that are associated with this element.
+ *
+ * If there are no annotations associated with this
element, the return
+ * value is an array of length 0.
+ *
* The difference between this method and {@link
#getAnnotation(Class)}
* is that this method detects if its argument is a repeatable
* annotation type (JLS 9.6), and if so, attempts to find one or
@@ -159,65 +226,54 @@
* @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
*/
T[] getAnnotationsByType(Class
annotationClass);
/**
- * Returns annotations that are present on this element.
- *
- * If there are no annotations present on this element,
the return
- * value is an array of length 0.
- *
- * The caller of this method is free to modify the returned array;
it will
- * have no effect on the arrays returned to other callers.
- *
- * @return annotations present on this element
- * @since 1.5
- */
- Annotation[] getAnnotations();
-
- /**
* Returns this element's annotation for the specified type if
- * such an annotation is present, else null.
+ * such an annotation is directly present, else null.
*
* This method ignores inherited annotations. (Returns null if no
* annotations are directly present on this element.)
*
- * @param the type of the annotation to query for and return if
present
+ * @param 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
*/
T getDeclaredAnnotation(Class
annotationClass);
/**
- * Returns annotations that are directly present on this
element.
- * This method ignores inherited annotations.
- *
- * If there are no annotations directly present on this
element,
- * the return value is an array of length 0.
+ * Returns this element's annotation(s) for the specified type if
+ * such annotations are either directly present or
+ * indirectly present. This method ignores inherited
+ * annotations.
+ *
+ * If there are no specified annotations directly or indirectly
+ * present on this element, the return value is an array of length
+ * 0.
*
* The difference between this method and {@link
* #getDeclaredAnnotation(Class)} is that this method detects if its
* argument is a repeatable annotation type (JLS 9.6),
and if so,
* attempts to find one or more annotations of that type by "looking
- * through" a container annotation.
+ * through" a container annotation if one is present.
*
* The caller of this method is free to modify the returned array;
it will
* have no effect on the arrays returned to other callers.
*
* @param the type of the annotation to query for and return
- * if directly present
+ * if directly or indirectly present
* @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 or indirectly present on this element, else an
array of length zero
* @throws NullPointerException if the given annotation class is null
* @since 1.8
*/
From alex.buckley at oracle.com Fri Jul 12 10:03:56 2013
From: alex.buckley at oracle.com (Alex Buckley)
Date: Fri, 12 Jul 2013 10:03:56 -0700
Subject: Review request for present, directly present,
etc. in core reflection javadoc
In-Reply-To: <51DF9BBD.1000604@oracle.com>
References: <51DC8397.8000508@oracle.com> <51DC9613.8050404@oracle.com>
<51DCBB2D.9090803@oracle.com>
<64E6EEFF-0BDD-4B1E-B52D-52C1C0BCA95D@oracle.com>
<51DDB06D.6000606@oracle.com> <51DF0946.7010201@oracle.com>
<51DF3331.1000005@oracle.com> <51DF9BBD.1000604@oracle.com>
Message-ID: <51E036FC.80903@oracle.com>
Looks good now.
On 7/11/2013 11:01 PM, Joe Darcy wrote:
> Hello,
>
> On 07/11/2013 03:35 PM, Alex Buckley wrote:
>> I am glad that getAnnotation(...), getAnnotations(), and
>> getAnnotationsByType(...) are now presented in that order.
>>
>> But I should have been clearer that this order also applies to
>> getDeclaredAnnotation(...), getDeclaredAnnotations(), and
>> getDeclaredAnnotationsByType(...). Each triple of methods has the same
>> natural order: legacy-legacy-new.
>
> Reordered.
>
>>
>> This also applies to the summary table:
>>
>> T getAnnotation(Class)
>> Annotation[] getAnnotations()
>> T[] getAnnotationsByType(Class <-- missing ) in the webrev
>
> Fixed.
>
>> T getDeclaredAnnotation(Class)
>> Annotation[] getDeclaredAnnotations()
>> T[] getDeclaredAnnotationsByType(Class)
>>
>> - Since the text in the Method column is monospaced, could it be
>> spaced as above, so that method names line up?
>
> I broke this up into two columns for display purposes.
>
>>
>> - Consider adding a column after Method: "Since". Column values: 1.5
>> 1.5 1.8 1.5 1.5 1.8.
>
> I think that would look dated very quickly.
>
> Patch below; webrev at
>
> http://cr.openjdk.java.net/~darcy/8010679.3/
>
> Thanks,
>
> -Joe
From elena.votchennikova at oracle.com Thu Jul 18 06:32:47 2013
From: elena.votchennikova at oracle.com (elena votchennikova)
Date: Thu, 18 Jul 2013 17:32:47 +0400
Subject: Review request for present, directly present,
etc. in core reflection javadoc
In-Reply-To: <51DEF258.3060507@oracle.com>
References: <51DC8397.8000508@oracle.com> <51DC9613.8050404@oracle.com>
<51DCBB2D.9090803@oracle.com> <51DDA81C.8090506@oracle.com>
<51DDB1E2.30603@oracle.com> <51DE9373.6020308@oracle.com>
<51DEF258.3060507@oracle.com>
Message-ID: <51E7EE7F.9020404@oracle.com>
Hello Joe,
please look at my new question bellow.
On 11.07.2013 21:58, Joe Darcy wrote:
> Hello Elena,
>
> On 07/11/2013 04:13 AM, elena votchennikova wrote:
>> Hi Joe,
>>
>> specifications for methods getDeclaredAnnotation(Class),
>> getDeclaredAnnotations(), getDeclaredAnnotationsByType(Class) is
>> valid and there are no contradiction (formally).
>> But the following classes
>> - j.l.Package
>> - j.l.r.AccessibleObject
>> (re: j.l.r.Field, j.l.r.Executable, j.l.r.Method, j.l.r.Constructor)
>> - j.l.r.Parameter
>> can have only directly present annotation. So, I think this is
>> strange to describe in the specification cases for inherited
>> annotations for these classes, because it could mislead readers.
>
> When managing javadoc along different points in an type hierarchy,
> there is a trade-off between making statements that are universally
> true in the parent type (listing all the special cases) so that there
> is only one copy of a method's specification and creating specialized
> copies of the specification at each location. (This is more pronounced
> in interface-only hierarchies where a method from a supertype method
> doesn't get an explicit inclusion unless it is overridden. When a
> class implements an interface, the implementation will get its own
> javadoc entry even if it is just inherited from the interface.)
>
> The former approach offers benefits in maintainability at the risk of
> giving the user some irrelevant information for overridden methods.
>
> For this work, the version of the specification in AnnotatedElement
> needs to have all the special cases laid out. To follow your guidance,
> there would in addition need to be
>
> * A specialized version of the specification for j.l.Class covering
> inheritance
> * Three *independently maintained* copies specialized to ignore
> inheritance:
> * AccessibleObject (covers Field, Method, Constructor)
> * j.l.Package
> * j.l.r.Parameter
>
> So I don't think it is a good trade-off to go from managing 1 copy of
> the javadoc in question to managing 5 copies.
Ok, thank you for explanation.
But maybe 'getDeclared*' methods should be placed directly in j.l.Class?
Why these methods were placed in j.l.r.AnnotatedElement?
Thanks a lot,
Elena
(member of the JCK team)
>
> Cheers,
>
> -Joe
>
>>
>>
>> Elena
>>
>>
>> On 10.07.2013 23:11, Joe Darcy wrote:
>>> On 07/10/2013 11:29 AM, Alex Buckley wrote:
>>>> Elena Votchennikova pointed out in a comment of JDK-8010679 that
>>>> classes which implement AnnotatedElement contain method
>>>> specifications copied from AnnotatedElement. I believe the
>>>> following classes need to have their method specifications updated:
>>>>
>>>> - j.l.Class
>>>> - j.l.Package
>>>> - j.l.r.AccessibleObject
>>>> (re: j.l.r.Field, j.l.r.Executable, j.l.r.Method, j.l.r.Constructor)
>>>> - j.l.r.Parameter
>>>
>>> The specifications on the implementation classes should generally
>>> just be @inheritdoc'ed (meaning no explicit update should be needed
>>> in those files), but I'll double check.
>>>
>>> -Joe
>>>
>>
>
From alex.buckley at oracle.com Thu Jul 18 09:38:22 2013
From: alex.buckley at oracle.com (Alex Buckley)
Date: Thu, 18 Jul 2013 09:38:22 -0700 (PDT)
Subject: Review request for present, directly present, etc. in core
reflection javadoc
Message-ID: <40b2ddd1-8bfb-49b3-8901-e0323c42488f@default>
Elena, getAnnotationXXX methods have been visible in Package and AccessibleObject for years. It is not a problem in practice, and it is not a meaningful conformance issue. At this point in JDK8, we need to be fixing real bugs, not rearranging documentation.
Alex
----- Original Message -----
From: elena.votchennikova at oracle.com
To: joe.darcy at oracle.com
Cc: alex.buckley at oracle.com, enhanced-metadata-spec-discuss at openjdk.java.net
Sent: Thursday, July 18, 2013 6:33:21 AM GMT -08:00 US/Canada Pacific
Subject: Re: Review request for present, directly present, etc. in core reflection javadoc
Hello Joe,
please look at my new question bellow.
On 11.07.2013 21:58, Joe Darcy wrote:
> Hello Elena,
>
> On 07/11/2013 04:13 AM, elena votchennikova wrote:
>> Hi Joe,
>>
>> specifications for methods getDeclaredAnnotation(Class),
>> getDeclaredAnnotations(), getDeclaredAnnotationsByType(Class) is
>> valid and there are no contradiction (formally).
>> But the following classes
>> - j.l.Package
>> - j.l.r.AccessibleObject
>> (re: j.l.r.Field, j.l.r.Executable, j.l.r.Method, j.l.r.Constructor)
>> - j.l.r.Parameter
>> can have only directly present annotation. So, I think this is
>> strange to describe in the specification cases for inherited
>> annotations for these classes, because it could mislead readers.
>
> When managing javadoc along different points in an type hierarchy,
> there is a trade-off between making statements that are universally
> true in the parent type (listing all the special cases) so that there
> is only one copy of a method's specification and creating specialized
> copies of the specification at each location. (This is more pronounced
> in interface-only hierarchies where a method from a supertype method
> doesn't get an explicit inclusion unless it is overridden. When a
> class implements an interface, the implementation will get its own
> javadoc entry even if it is just inherited from the interface.)
>
> The former approach offers benefits in maintainability at the risk of
> giving the user some irrelevant information for overridden methods.
>
> For this work, the version of the specification in AnnotatedElement
> needs to have all the special cases laid out. To follow your guidance,
> there would in addition need to be
>
> * A specialized version of the specification for j.l.Class covering
> inheritance
> * Three *independently maintained* copies specialized to ignore
> inheritance:
> * AccessibleObject (covers Field, Method, Constructor)
> * j.l.Package
> * j.l.r.Parameter
>
> So I don't think it is a good trade-off to go from managing 1 copy of
> the javadoc in question to managing 5 copies.
Ok, thank you for explanation.
But maybe 'getDeclared*' methods should be placed directly in j.l.Class?
Why these methods were placed in j.l.r.AnnotatedElement?
Thanks a lot,
Elena
(member of the JCK team)
>
> Cheers,
>
> -Joe
>
>>
>>
>> Elena
>>
>>
>> On 10.07.2013 23:11, Joe Darcy wrote:
>>> On 07/10/2013 11:29 AM, Alex Buckley wrote:
>>>> Elena Votchennikova pointed out in a comment of JDK-8010679 that
>>>> classes which implement AnnotatedElement contain method
>>>> specifications copied from AnnotatedElement. I believe the
>>>> following classes need to have their method specifications updated:
>>>>
>>>> - j.l.Class
>>>> - j.l.Package
>>>> - j.l.r.AccessibleObject
>>>> (re: j.l.r.Field, j.l.r.Executable, j.l.r.Method, j.l.r.Constructor)
>>>> - j.l.r.Parameter
>>>
>>> The specifications on the implementation classes should generally
>>> just be @inheritdoc'ed (meaning no explicit update should be needed
>>> in those files), but I'll double check.
>>>
>>> -Joe
>>>
>>
>
From elena.votchennikova at oracle.com Fri Jul 19 01:55:28 2013
From: elena.votchennikova at oracle.com (elena votchennikova)
Date: Fri, 19 Jul 2013 12:55:28 +0400
Subject: Review request for present, directly present,
etc. in core reflection javadoc
In-Reply-To: <40b2ddd1-8bfb-49b3-8901-e0323c42488f@default>
References: <40b2ddd1-8bfb-49b3-8901-e0323c42488f@default>
Message-ID: <51E8FF00.8040609@oracle.com>
Hi Alex,
On 18.07.2013 20:38, Alex Buckley wrote:
> Elena, getAnnotationXXX methods have been visible in Package and AccessibleObject for years. It is not a problem in practice, and it is not a meaningful conformance issue. At this point in JDK8, we need to be fixing real bugs, not rearranging documentation.
I've not proposed rearrange the documentation, I'm sorry if it looks so.
I've asked you about the reasons why getDeclaredXXX methods were placed
in j.l.r.AnnotatedElement and not in j.l.Class, for better
understanding. And if I understand your previous letter correct - this
is because of historical reasons. Ok.
Thanks a lot for your answer,
Elena
>
> Alex
>
> ----- Original Message -----
> From: elena.votchennikova at oracle.com
> To: joe.darcy at oracle.com
> Cc: alex.buckley at oracle.com, enhanced-metadata-spec-discuss at openjdk.java.net
> Sent: Thursday, July 18, 2013 6:33:21 AM GMT -08:00 US/Canada Pacific
> Subject: Re: Review request for present, directly present, etc. in core reflection javadoc
>
> Hello Joe,
>
> please look at my new question bellow.
>
> On 11.07.2013 21:58, Joe Darcy wrote:
>> Hello Elena,
>>
>> On 07/11/2013 04:13 AM, elena votchennikova wrote:
>>> Hi Joe,
>>>
>>> specifications for methods getDeclaredAnnotation(Class),
>>> getDeclaredAnnotations(), getDeclaredAnnotationsByType(Class) is
>>> valid and there are no contradiction (formally).
>>> But the following classes
>>> - j.l.Package
>>> - j.l.r.AccessibleObject
>>> (re: j.l.r.Field, j.l.r.Executable, j.l.r.Method, j.l.r.Constructor)
>>> - j.l.r.Parameter
>>> can have only directly present annotation. So, I think this is
>>> strange to describe in the specification cases for inherited
>>> annotations for these classes, because it could mislead readers.
>> When managing javadoc along different points in an type hierarchy,
>> there is a trade-off between making statements that are universally
>> true in the parent type (listing all the special cases) so that there
>> is only one copy of a method's specification and creating specialized
>> copies of the specification at each location. (This is more pronounced
>> in interface-only hierarchies where a method from a supertype method
>> doesn't get an explicit inclusion unless it is overridden. When a
>> class implements an interface, the implementation will get its own
>> javadoc entry even if it is just inherited from the interface.)
>>
>> The former approach offers benefits in maintainability at the risk of
>> giving the user some irrelevant information for overridden methods.
>>
>> For this work, the version of the specification in AnnotatedElement
>> needs to have all the special cases laid out. To follow your guidance,
>> there would in addition need to be
>>
>> * A specialized version of the specification for j.l.Class covering
>> inheritance
>> * Three *independently maintained* copies specialized to ignore
>> inheritance:
>> * AccessibleObject (covers Field, Method, Constructor)
>> * j.l.Package
>> * j.l.r.Parameter
>>
>> So I don't think it is a good trade-off to go from managing 1 copy of
>> the javadoc in question to managing 5 copies.
> Ok, thank you for explanation.
>
> But maybe 'getDeclared*' methods should be placed directly in j.l.Class?
> Why these methods were placed in j.l.r.AnnotatedElement?
>
>
> Thanks a lot,
> Elena
> (member of the JCK team)
>
>> Cheers,
>>
>> -Joe
>>
>>>
>>> Elena
>>>
>>>
>>> On 10.07.2013 23:11, Joe Darcy wrote:
>>>> On 07/10/2013 11:29 AM, Alex Buckley wrote:
>>>>> Elena Votchennikova pointed out in a comment of JDK-8010679 that
>>>>> classes which implement AnnotatedElement contain method
>>>>> specifications copied from AnnotatedElement. I believe the
>>>>> following classes need to have their method specifications updated:
>>>>>
>>>>> - j.l.Class
>>>>> - j.l.Package
>>>>> - j.l.r.AccessibleObject
>>>>> (re: j.l.r.Field, j.l.r.Executable, j.l.r.Method, j.l.r.Constructor)
>>>>> - j.l.r.Parameter
>>>> The specifications on the implementation classes should generally
>>>> just be @inheritdoc'ed (meaning no explicit update should be needed
>>>> in those files), but I'll double check.
>>>>
>>>> -Joe
>>>>