From alex.buckley at oracle.com Wed May 1 12:51:08 2013 From: alex.buckley at oracle.com (Alex Buckley) Date: Wed, 01 May 2013 12:51:08 -0700 Subject: Request for revised terminology describing ways annotations can be present or not In-Reply-To: <51634990.6030402@oracle.com> References: <51522AFA.4070906@oracle.com> <51526305.2040804@oracle.com> <51631B9E.2000905@oracle.com> <51634990.6030402@oracle.com> Message-ID: <5181722C.8090309@oracle.com> On 4/8/2013 3:49 PM, Alex Buckley wrote: > On 4/8/2013 12:33 PM, Joe Darcy wrote: >>> The building blocks are easy: >>> >>> a) An annotation A is DIRECTLY PRESENT on an element E if E is >>> associated with a RuntimeVisibleAnnotations or >>> RuntimeVisibleParameterAnnotations attribute, and the attribute >>> contains A. >> >> For completeness, the attributes used to store declaration annotations >> on type parameters should be included in this list too. > > Yes, thanks. I updated JDK-8010679 and will upload a new spec document > soon. I have updated the spec for what is hopefully the final time: http://cr.openjdk.java.net/~abuckley/8misc.pdf The only changes are i) mentioning RuntimeVisibleTypeAnnotations in the definition of "directly present" (since reflection APIs expose type parameter declaration annotations stored in that attribute), and ii) adding getAnnotatedType() to java.lang.reflect.Parameter (for consistency with other jang.lang.reflect types). Alex From jesper at selskabet.org Wed May 1 15:18:40 2013 From: jesper at selskabet.org (=?iso-8859-1?Q?Jesper_Steen_M=F8ller?=) Date: Thu, 2 May 2013 00:18:40 +0200 Subject: JEP-118: Why are parameter names not mandatory? Message-ID: <29B4CD45-5452-43D0-A3F0-7A414F1D2E42@selskabet.org> Hi experts I'm currently examining these two JEPs, and was curious: Why not make the ParameterNames attribute mandatory at least for non-private methods. I don't quite get why it makes sense to add this info which will be useful for introspection, IDE's and annotation processing, but only make it optional - even defaulting to 'off'? I apologise if this has been discussed before, I'm new to these two JEPs, but currently investigating them for support in the Ecliipse Java Compiler and tools. Kind regards, Jesper From alex.buckley at oracle.com Wed May 1 16:59:16 2013 From: alex.buckley at oracle.com (Alex Buckley) Date: Wed, 01 May 2013 16:59:16 -0700 Subject: JEP-118: Why are parameter names not mandatory? In-Reply-To: <29B4CD45-5452-43D0-A3F0-7A414F1D2E42@selskabet.org> References: <29B4CD45-5452-43D0-A3F0-7A414F1D2E42@selskabet.org> Message-ID: <5181AC54.2070000@oracle.com> On 5/1/2013 3:18 PM, Jesper Steen M?ller wrote: > I'm currently examining these two JEPs, and was curious: Why not make > the ParameterNames attribute mandatory at least for non-private > methods. I don't quite get why it makes sense to add this info which > will be useful for introspection, IDE's and annotation processing, > but only make it optional - even defaulting to 'off'? Please see the introduction to chapter 2 of http://cr.openjdk.java.net/~abuckley/8misc.pdf. The bottom line is that for every programmer you please by including parameter names by default, you intensely anger another. Some people dislike the extra class file size; some dislike the new compatibility surface; some regard it as exposing sensitive information. So you need an opt-in mechanism. If you want it in the Java language, you need to define syntax and scope. See the first thread at http://mail.openjdk.java.net/pipermail/enhanced-metadata-spec-discuss/2012-November/thread.html. Personally I would focus on simplicity (@ReifyParameters on a type decl means store p-names of public methods) but that did not meet others' needs. For once, I felt not standardizing was the right answer. This freed us to focus on getting the interaction right between java.lang.reflect.Parameter, type annotations, and repeating annotations. I hope to standardize the opt-in mechanism in SE 9. Alex From markus_keller at ch.ibm.com Thu May 2 05:56:09 2013 From: markus_keller at ch.ibm.com (Markus Keller) Date: Thu, 2 May 2013 14:56:09 +0200 Subject: changing a parameter name will never be a binary-incompatible change Message-ID: Section 2.1 of "Method Parameter Reflection" says: "1. Parameter names are not essential to the Java virtual machine. They play no part in linkage, so changing a parameter name will never be a binary-incompatible change." Is the "will never be" really necessary? Is it absolutely impossible that the JVM will at one point get a new instruction that will perform method lookup by parameter name? Maybe not for the Java language, but to better support other languages. The "will never be" would make such an evolution illegal. I think it's better to just say "[..], so changing a parameter name is a binary-compatible change.". That's clear enough for now, but leaves the door open for developments in a new version of the spec. Markus From alex.buckley at oracle.com Thu May 2 16:22:24 2013 From: alex.buckley at oracle.com (Alex Buckley) Date: Thu, 02 May 2013 16:22:24 -0700 Subject: changing a parameter name will never be a binary-incompatible change In-Reply-To: References: Message-ID: <5182F530.8060205@oracle.com> I appreciate your thorough reading of the 8misc.pdf file. In this instance, I can set your mind at rest. The file contains updates to numbered sections of the JLS and JVMS, but also motivation and rationale for the features. The text you quote from 2.1 is just that - motivation for the attribute definition which follows in 4.7.22. If that part of 2.1 even makes it into JVMS8, it would at most be non-normative text in 4.7.22, probably shortened and softened. Accordingly, there's no need to worry that JVMS8 might bind its successors by stating normatively that something "will never be". Alex On 5/2/2013 5:56 AM, Markus Keller wrote: > Section 2.1 of "Method Parameter Reflection" says: > "1. Parameter names are not essential to the Java virtual machine. They > play no part > in linkage, so changing a parameter name will never be a > binary-incompatible > change." > > Is the "will never be" really necessary? Is it absolutely impossible that > the JVM will at one point get a new instruction that will perform method > lookup by parameter name? Maybe not for the Java language, but to better > support other languages. > > The "will never be" would make such an evolution illegal. I think it's > better to just say "[..], so changing a parameter name is a > binary-compatible change.". That's clear enough for now, but leaves the > door open for developments in a new version of the spec. > > Markus > From joe.darcy at oracle.com Wed May 15 23:22:42 2013 From: joe.darcy at oracle.com (Joe Darcy) Date: Wed, 15 May 2013 23:22:42 -0700 Subject: Proposed incorporation of specification change for present/directly present/etc. terminology into javax.lang.model Message-ID: <51947B32.70701@oracle.com> Hello, I've been working to update the javadoc specification in javax.lang.model.* with the new present / directly present / etc. terminology from the latest 8misc.pdf file. Proposed patch is below. Full webrev of the change available from http://cr.openjdk.java.net/~darcy/8010680.1/ Thanks, -Joe --- a/src/share/classes/javax/lang/model/AnnotatedConstruct.java Wed May 15 10:39:26 2013 -0700 +++ b/src/share/classes/javax/lang/model/AnnotatedConstruct.java Wed May 15 23:18:28 2013 -0700 @@ -39,35 +39,64 @@ * are on a declaration, whereas annotations on a type are on * a specific use of a type name. * - * The terms directly present and present are used + * The terms directly present, present, + * indirectly present, and associated are used * throughout this interface to describe precisely which annotations - * are returned by methods: + * are returned by the methods defined herein. * - *

An annotation A is directly present on a - * construct E if E is annotated, and: + *

An annotation A of annotation type AT is + * directly present on a construct C if either: * *

    * - *
  • for an invocation of {@code getAnnotation(Class)} or - * {@code getAnnotationMirrors()}, E's annotations contain A. + *
  • Exactly one annotation of type AT appears in the source + * code representation for C. * - *
  • for an invocation of {@code getAnnotationsByType(Class)}, - * E's annotations either contain A or, if the type of - * A is repeatable, contain exactly one annotation whose value - * element contains A and whose type is the containing - * annotation type of A's type. + *
  • AT is the containing annotation type for a repeatable + * annotation type T and the source code for C has + * multiple annotations of type T. + * + *
  • A representation of A appears in the executable output + * for C, such as the {@code RuntimeVisibleAnnotations} or + * {@code RuntimeVisibleParameterAnnotations} attributes of a class + * file. * *
* - *

An annotation A is present on a construct E if either: + *

An annotation A is present on a + * construct C if either: + *

    + * + *
  • A is directly present on C. + * + *
  • No annotation of type AT is directly present on + * C, and C is a class and AT is inheritable + * and A is present on the superclass of C. + * + *
+ * + * An annotation A is indirectly present on a construct + * C if: * *
    - *
  • A is directly present on E; or * - *
  • A is not directly present on E, and - * E is an element representing a class, and A's type - * is inheritable, and A is present on the element - * representing the superclass of E. + *
  • AT is a repeatable annotation type with a containing annotation type ATC. + * + *
  • An annotation of type ATC is directly present on C. + * + *
+ * + * An annotation A is associated with a construct + * C if either: + * + *
    + * + *
  • A is directly or indirectly present on C. + * + *
  • No annotation of type AT is directly or indirectly + * present on C, C is a class, and AT is + * inheritable, and AT is associated with the superclass of + * C. * *
* @@ -86,9 +115,8 @@ List getAnnotationMirrors(); /** - * Returns this construct's annotation of the - * specified type if such an annotation is present, else {@code - * null}. + * Returns this construct's annotation of the specified type if + * such an annotation is present, else {@code null}. * *

The annotation returned by this method could contain an element * whose value is of type {@code Class}. @@ -118,9 +146,8 @@ * @param the annotation type * @param annotationType the {@code Class} object corresponding to * the annotation type - * @return this element's or type use's annotation for the - * specified annotation type if present on this element, else - * {@code null} + * @return this construct's annotation for the specified + * annotation type if present, else {@code null} * * @see #getAnnotationMirrors() * @see java.lang.reflect.AnnotatedElement#getAnnotation @@ -134,10 +161,10 @@ A getAnnotation(Class annotationType); /** - * Returns annotations that are present on this construct. + * Returns annotations that are associated with this construct. * - * If there are no annotations present on this construct, - * the return value is an array of length 0. + * If there are no annotations associated with this construct, the + * return value is an array of length 0. * * The difference between this method and {@link #getAnnotation(Class)} * is that this method detects if its argument is a repeatable @@ -172,8 +199,8 @@ * @param the annotation type * @param annotationType the {@code Class} object corresponding to * the annotation type - * @return this element's annotations for the specified annotation - * type if present on this element, else an empty array + * @return this construct's annotations for the specified annotation + * type if present on this construct, else an empty array * * @see #getAnnotationMirrors() * @see #getAnnotation(java.lang.Class) diff -r 445b8b5ae9f4 src/share/classes/javax/lang/model/util/Elements.java --- a/src/share/classes/javax/lang/model/util/Elements.java Wed May 15 10:39:26 2013 -0700 +++ b/src/share/classes/javax/lang/model/util/Elements.java Wed May 15 23:18:28 2013 -0700 @@ -143,12 +143,13 @@ List getAllMembers(TypeElement type); /** - * Returns all annotations of an element, whether - * inherited or directly present. + * Returns all annotations present on an element, whether + * directly present or present via inheritance. * * @param e the element being examined * @return all annotations of the element * @see Element#getAnnotationMirrors + * @see javax.lang.model.AnnotatedConstruct */ List getAllAnnotationMirrors(Element e); From alex.buckley at oracle.com Thu May 16 11:56:36 2013 From: alex.buckley at oracle.com (Alex Buckley) Date: Thu, 16 May 2013 11:56:36 -0700 Subject: Proposed incorporation of specification change for present/directly present/etc. terminology into javax.lang.model In-Reply-To: <51947B32.70701@oracle.com> References: <51947B32.70701@oracle.com> Message-ID: <51952BE4.9070002@oracle.com> 1. "directly present" says the annotation @Foo(x=1) is directly present if any annotation of type Foo is present. (Assuming an int element x in type Foo.) So is @Foo(x=2). And @Foo(x=3). And @Foo(x=4). And so on. I know we only have type-based lookup for annotations today, but we should not open the door to weirdo answers for "tell me all the annotations of type Foo which are directly present". Try this: -- An annotation A is directly present on a construct C if either: - A is explicitly or implicitly declared as applying to the source code representation of C; or - A appears in the executable output corresponding to C, such as in the RuntimeVisibleAnnotations attribute of a class file. -- (The "declared" in "explicitly or implicitly declared" does not pertain to solely declaration annotations. If you repeat a type annotation, then the type annotations' container annotation will be an implicitly declared type annotation.) 2. The "present" and "associated" definitions both use the type AT but it's not bound to anything. 3. The "indirectly present" definition also has AT spring out of nowhere, but also it's important to say "... if both of the following conditions are true:" rather than just "... if:" because it's easy to assume the bullet point are alternatives as in the other three definitions. Alex On 5/15/2013 11:22 PM, Joe Darcy wrote: > Hello, > > I've been working to update the javadoc specification in > javax.lang.model.* with the new present / directly present / etc. > terminology from the latest 8misc.pdf file. > > Proposed patch is below. > > Full webrev of the change available from > > http://cr.openjdk.java.net/~darcy/8010680.1/ > > Thanks, > > -Joe > > --- a/src/share/classes/javax/lang/model/AnnotatedConstruct.java Wed May > 15 10:39:26 2013 -0700 > +++ b/src/share/classes/javax/lang/model/AnnotatedConstruct.java Wed May > 15 23:18:28 2013 -0700 > @@ -39,35 +39,64 @@ > * are on a declaration, whereas annotations on a type are on > * a specific use of a type name. > * > - * The terms directly present and present are used > + * The terms directly present, present, > + * indirectly present, and associated are used > * throughout this interface to describe precisely which annotations > - * are returned by methods: > + * are returned by the methods defined herein. > * > - *

An annotation A is directly present on a > - * construct E if E is annotated, and: > + *

An annotation A of annotation type AT is > + * directly present on a construct C if either: > * > *

> * > - *

An annotation A is present on a construct E if either: > + *

An annotation A is present on a > + * construct C if either: > + *

    > + * > + *
  • A is directly present on C. > + * > + *
  • No annotation of type AT is directly present on > + * C, and C is a class and AT is inheritable > + * and A is present on the superclass of C. > + * > + *
> + * > + * An annotation A is indirectly present on a construct > + * C if: > * > *
    > - *
  • A is directly present on E; or > * > - *
  • A is not directly present on E, and > - * E is an element representing a class, and A's type > - * is inheritable, and A is present on the element > - * representing the superclass of E. > + *
  • AT is a repeatable annotation type with a containing > annotation type ATC. > + * > + *
  • An annotation of type ATC is directly present on C. > + * > + *
> + * > + * An annotation A is associated with a construct > + * C if either: > + * > + *
    > + * > + *
  • A is directly or indirectly present on C. > + * > + *
  • No annotation of type AT is directly or indirectly > + * present on C, C is a class, and AT is > + * inheritable, and AT is associated with the superclass of > + * C. > * > *
> * > @@ -86,9 +115,8 @@ > List getAnnotationMirrors(); > > /** > - * Returns this construct's annotation of the > - * specified type if such an annotation is present, else > {@code > - * null}. > + * Returns this construct's annotation of the specified type if > + * such an annotation is present, else {@code null}. > * > *

The annotation returned by this method could contain an > element > * whose value is of type {@code Class}. > @@ -118,9 +146,8 @@ > * @param the annotation type > * @param annotationType the {@code Class} object corresponding to > * the annotation type > - * @return this element's or type use's annotation for the > - * specified annotation type if present on this element, else > - * {@code null} > + * @return this construct's annotation for the specified > + * annotation type if present, else {@code null} > * > * @see #getAnnotationMirrors() > * @see java.lang.reflect.AnnotatedElement#getAnnotation > @@ -134,10 +161,10 @@ > A getAnnotation(Class annotationType); > > /** > - * Returns annotations that are present on this construct. > + * Returns annotations that are associated with this > construct. > * > - * If there are no annotations present on this construct, > - * the return value is an array of length 0. > + * If there are no annotations associated with this construct, the > + * return value is an array of length 0. > * > * The difference between this method and {@link > #getAnnotation(Class)} > * is that this method detects if its argument is a repeatable > @@ -172,8 +199,8 @@ > * @param the annotation type > * @param annotationType the {@code Class} object corresponding to > * the annotation type > - * @return this element's annotations for the specified annotation > - * type if present on this element, else an empty array > + * @return this construct's annotations for the specified annotation > + * type if present on this construct, else an empty array > * > * @see #getAnnotationMirrors() > * @see #getAnnotation(java.lang.Class) > diff -r 445b8b5ae9f4 src/share/classes/javax/lang/model/util/Elements.java > --- a/src/share/classes/javax/lang/model/util/Elements.java Wed May > 15 10:39:26 2013 -0700 > +++ b/src/share/classes/javax/lang/model/util/Elements.java Wed May > 15 23:18:28 2013 -0700 > @@ -143,12 +143,13 @@ > List getAllMembers(TypeElement type); > > /** > - * Returns all annotations of an element, whether > - * inherited or directly present. > + * Returns all annotations present on an element, whether > + * directly present or present via inheritance. > * > * @param e the element being examined > * @return all annotations of the element > * @see Element#getAnnotationMirrors > + * @see javax.lang.model.AnnotatedConstruct > */ > List getAllAnnotationMirrors(Element e); > > From joe.darcy at oracle.com Mon May 20 22:35:36 2013 From: joe.darcy at oracle.com (Joe Darcy) Date: Mon, 20 May 2013 22:35:36 -0700 Subject: Proposed incorporation of specification change for present/directly present/etc. terminology into javax.lang.model In-Reply-To: <51952BE4.9070002@oracle.com> References: <51947B32.70701@oracle.com> <51952BE4.9070002@oracle.com> Message-ID: <519B07A8.6040903@oracle.com> Hello, On 05/16/2013 11:56 AM, Alex Buckley wrote: > 1. "directly present" says the annotation @Foo(x=1) is directly > present if any annotation of type Foo is present. (Assuming an int > element x in type Foo.) So is @Foo(x=2). And @Foo(x=3). And @Foo(x=4). > And so on. I know we only have type-based lookup for annotations > today, but we should not open the door to weirdo answers for "tell me > all the annotations of type Foo which are directly present". Try this: > > -- > An annotation A is directly present on a construct C if either: > > - A is explicitly or implicitly declared as applying to the source > code representation of C; or > - A appears in the executable output corresponding to C, such as in > the RuntimeVisibleAnnotations attribute of a class file. > -- > > (The "declared" in "explicitly or implicitly declared" does not > pertain to solely declaration annotations. If you repeat a type > annotation, then the type annotations' container annotation will be an > implicitly declared type annotation.) > > 2. The "present" and "associated" definitions both use the type AT but > it's not bound to anything. > > 3. The "indirectly present" definition also has AT spring out of > nowhere, but also it's important to say "... if both of the following > conditions are true:" rather than just "... if:" because it's easy to > assume the bullet point are alternatives as in the other three > definitions. Reworked portions of the patch below; full webrev at http://cr.openjdk.java.net/~darcy/8010680.2 Thanks, -Joe --- a/src/share/classes/javax/lang/model/AnnotatedConstruct.java Fri May 17 13:48:41 2013 -0700 +++ b/src/share/classes/javax/lang/model/AnnotatedConstruct.java Mon May 20 22:34:23 2013 -0700 @@ -39,35 +39,72 @@ * are on a declaration, whereas annotations on a type are on * a specific use of a type name. * - * The terms directly present and present are used + * The terms directly present, present, + * indirectly present, and associated are used * throughout this interface to describe precisely which annotations - * are returned by methods: + * are returned by the methods defined herein. * - *

An annotation A is directly present on a - * construct E if E is annotated, and: + *

In the definitions below, an annotation A has an + * annotation type AT. If AT is a repeatable annotation + * type, the type of the containing annotation is ATC. + * + *

Annotation A is directly present on a construct + * C if either: * *

* - *

An annotation A is present on a construct E if either: + *

An annotation A is present on a + * construct C if either: + *

    + * + *
  • A is directly present on C. + * + *
  • No annotation of type AT is directly present on + * C, and C is a class and AT is inheritable + * and A is present on the superclass of C. + * + *
+ * + * An annotation A is indirectly present on a construct + * C if both: * *
    - *
  • A is directly present on E; or * - *
  • A is not directly present on E, and - * E is an element representing a class, and A's type - * is inheritable, and A is present on the element - * representing the superclass of E. + *
  • AT is a repeatable annotation type with a containing annotation type ATC. + * + *
  • An annotation of type ATC is directly present on C. + * + *
+ * + * An annotation A is associated with a construct + * C if either: + * + *
    + * + *
  • A is directly or indirectly present on C. + * + *
  • No annotation of type AT is directly or indirectly + * present on C, C is a class, and AT is + * inheritable, and AT is associated with the superclass of + * C. * *
* > > Alex > > On 5/15/2013 11:22 PM, Joe Darcy wrote: >> Hello, >> >> I've been working to update the javadoc specification in >> javax.lang.model.* with the new present / directly present / etc. >> terminology from the latest 8misc.pdf file. >> >> Proposed patch is below. >> >> Full webrev of the change available from >> >> http://cr.openjdk.java.net/~darcy/8010680.1/ >> >> Thanks, >> >> -Joe From alex.buckley at oracle.com Tue May 21 17:20:16 2013 From: alex.buckley at oracle.com (Alex Buckley) Date: Tue, 21 May 2013 17:20:16 -0700 Subject: Proposed incorporation of specification change for present/directly present/etc. terminology into javax.lang.model In-Reply-To: <519B07A8.6040903@oracle.com> References: <51947B32.70701@oracle.com> <51952BE4.9070002@oracle.com> <519B07A8.6040903@oracle.com> Message-ID: <519C0F40.3050802@oracle.com> - "directly present" and "present" are OK. - "indirectly present" still doesn't bind A strongly enough ... it's necessary but not sufficient that an annotation of type ATC is directly present on C ... the sufficient clause is that the ATC-typed annotation must have a value element which contains A. - "associated" is almost OK except for a type error: the final clause must be "and A is associated with the superclass of C." (The domain of "associated" is annotations, not annotation types, so AT is never associated with anything.) Alex On 5/20/2013 10:35 PM, Joe Darcy wrote: > Hello, > > On 05/16/2013 11:56 AM, Alex Buckley wrote: >> 1. "directly present" says the annotation @Foo(x=1) is directly >> present if any annotation of type Foo is present. (Assuming an int >> element x in type Foo.) So is @Foo(x=2). And @Foo(x=3). And @Foo(x=4). >> And so on. I know we only have type-based lookup for annotations >> today, but we should not open the door to weirdo answers for "tell me >> all the annotations of type Foo which are directly present". Try this: >> >> -- >> An annotation A is directly present on a construct C if either: >> >> - A is explicitly or implicitly declared as applying to the source >> code representation of C; or >> - A appears in the executable output corresponding to C, such as in >> the RuntimeVisibleAnnotations attribute of a class file. >> -- >> >> (The "declared" in "explicitly or implicitly declared" does not >> pertain to solely declaration annotations. If you repeat a type >> annotation, then the type annotations' container annotation will be an >> implicitly declared type annotation.) >> >> 2. The "present" and "associated" definitions both use the type AT but >> it's not bound to anything. >> >> 3. The "indirectly present" definition also has AT spring out of >> nowhere, but also it's important to say "... if both of the following >> conditions are true:" rather than just "... if:" because it's easy to >> assume the bullet point are alternatives as in the other three >> definitions. > > Reworked portions of the patch below; full webrev at > > http://cr.openjdk.java.net/~darcy/8010680.2 > > Thanks, > > -Joe > > --- a/src/share/classes/javax/lang/model/AnnotatedConstruct.java Fri May > 17 13:48:41 2013 -0700 > +++ b/src/share/classes/javax/lang/model/AnnotatedConstruct.java Mon May > 20 22:34:23 2013 -0700 > @@ -39,35 +39,72 @@ > * are on a declaration, whereas annotations on a type are on > * a specific use of a type name. > * > - * The terms directly present and present are used > + * The terms directly present, present, > + * indirectly present, and associated are used > * throughout this interface to describe precisely which annotations > - * are returned by methods: > + * are returned by the methods defined herein. > * > - *

An annotation A is directly present on a > - * construct E if E is annotated, and: > + *

In the definitions below, an annotation A has an > + * annotation type AT. If AT is a repeatable annotation > + * type, the type of the containing annotation is ATC. > + * > + *

Annotation A is directly present on a construct > + * C if either: > * > *

    > * > - *
  • for an invocation of {@code getAnnotation(Class)} or > - * {@code getAnnotationMirrors()}, E's annotations contain > A. > + *
  • A is explicitly or implicitly declared as applying to > + * the source code representation of C. > * > - *
  • for an invocation of {@code getAnnotationsByType(Class)}, > - * E's annotations either contain A or, if the type of > - * A is repeatable, contain exactly one annotation whose value > - * element contains A and whose type is the containing > - * annotation type of A's type. > + *

    Typically, if exactly one annotation of type AT appears in > + * the source code of representation of C, then A is > + * explicitly declared as applying to C. > + * > + * If there are multiple annotations of type AT present on > + * C, then if AT is repeatable annotation type, an > + * annotation of type ATC is implicitly declared on C. > + * > + *

  • A representation of A appears in the executable output > + * for C, such as the {@code RuntimeVisibleAnnotations} or > + * {@code RuntimeVisibleParameterAnnotations} attributes of a class > + * file. > * > *
> * > - *

An annotation A is present on a construct E if either: > + *

An annotation A is present on a > + * construct C if either: > + *

    > + * > + *
  • A is directly present on C. > + * > + *
  • No annotation of type AT is directly present on > + * C, and C is a class and AT is inheritable > + * and A is present on the superclass of C. > + * > + *
> + * > + * An annotation A is indirectly present on a construct > + * C if both: > * > *
    > - *
  • A is directly present on E; or > * > - *
  • A is not directly present on E, and > - * E is an element representing a class, and A's type > - * is inheritable, and A is present on the element > - * representing the superclass of E. > + *
  • AT is a repeatable annotation type with a containing > annotation type ATC. > + * > + *
  • An annotation of type ATC is directly present on C. > + * > + *
> + * > + * An annotation A is associated with a construct > + * C if either: > + * > + *
    > + * > + *
  • A is directly or indirectly present on C. > + * > + *
  • No annotation of type AT is directly or indirectly > + * present on C, C is a class, and AT is > + * inheritable, and AT is associated with the superclass of > + * C. > * > *
> * > > >> >> Alex >> >> On 5/15/2013 11:22 PM, Joe Darcy wrote: >>> Hello, >>> >>> I've been working to update the javadoc specification in >>> javax.lang.model.* with the new present / directly present / etc. >>> terminology from the latest 8misc.pdf file. >>> >>> Proposed patch is below. >>> >>> Full webrev of the change available from >>> >>> http://cr.openjdk.java.net/~darcy/8010680.1/ >>> >>> Thanks, >>> >>> -Joe > From joe.darcy at oracle.com Tue May 21 21:38:45 2013 From: joe.darcy at oracle.com (Joe Darcy) Date: Tue, 21 May 2013 21:38:45 -0700 Subject: Proposed incorporation of specification change for present/directly present/etc. terminology into javax.lang.model In-Reply-To: <519C0F40.3050802@oracle.com> References: <51947B32.70701@oracle.com> <51952BE4.9070002@oracle.com> <519B07A8.6040903@oracle.com> <519C0F40.3050802@oracle.com> Message-ID: <519C4BD5.7040709@oracle.com> Hello, On 05/21/2013 05:20 PM, Alex Buckley wrote: > - "directly present" and "present" are OK. > > - "indirectly present" still doesn't bind A strongly enough ... it's > necessary but not sufficient that an annotation of type ATC is > directly present on C ... the sufficient clause is that the ATC-typed > annotation must have a value element which contains A. > > - "associated" is almost OK except for a type error: the final clause > must be "and A is associated with the superclass of C." > (The domain of "associated" is annotations, not annotation types, so > AT is never associated with anything.) Hopefully final iteration; edits to "indirectly present" and "associated" definitions compared to the current code: + * An annotation A is indirectly present on a construct + * C if both: * *
    - *
  • A is directly present on E; or * - *
  • A is not directly present on E, and - * E is an element representing a class, and A's type - * is inheritable, and A is present on the element - * representing the superclass of E. + *
  • AT is a repeatable annotation type with a containing + * annotation type ATC. + * + *
  • An annotation of type ATC is directly present on + * C and A is one of the annotations included in result + * of calling the {@code value} method of the directly present + * annotation of type ATC. + * + *
+ * + * An annotation A is associated with a construct + * C if either: + * + *
    + * + *
  • A is directly or indirectly present on C. + * + *
  • No annotation of type AT is directly or indirectly + * present on C, C is a class, and AT is + * inheritable, and A is associated with the superclass of + * C. * Full new webrev at http://cr.openjdk.java.net/~darcy/8010680.3 Thanks, -Joe > > Alex > > On 5/20/2013 10:35 PM, Joe Darcy wrote: >> Hello, >> >> On 05/16/2013 11:56 AM, Alex Buckley wrote: >>> 1. "directly present" says the annotation @Foo(x=1) is directly >>> present if any annotation of type Foo is present. (Assuming an int >>> element x in type Foo.) So is @Foo(x=2). And @Foo(x=3). And @Foo(x=4). >>> And so on. I know we only have type-based lookup for annotations >>> today, but we should not open the door to weirdo answers for "tell me >>> all the annotations of type Foo which are directly present". Try this: >>> >>> -- >>> An annotation A is directly present on a construct C if either: >>> >>> - A is explicitly or implicitly declared as applying to the source >>> code representation of C; or >>> - A appears in the executable output corresponding to C, such as in >>> the RuntimeVisibleAnnotations attribute of a class file. >>> -- >>> >>> (The "declared" in "explicitly or implicitly declared" does not >>> pertain to solely declaration annotations. If you repeat a type >>> annotation, then the type annotations' container annotation will be an >>> implicitly declared type annotation.) >>> >>> 2. The "present" and "associated" definitions both use the type AT but >>> it's not bound to anything. >>> >>> 3. The "indirectly present" definition also has AT spring out of >>> nowhere, but also it's important to say "... if both of the following >>> conditions are true:" rather than just "... if:" because it's easy to >>> assume the bullet point are alternatives as in the other three >>> definitions. >> >> Reworked portions of the patch below; full webrev at >> >> http://cr.openjdk.java.net/~darcy/8010680.2 >> >> Thanks, >> >> -Joe >> >> --- a/src/share/classes/javax/lang/model/AnnotatedConstruct.java Fri May >> 17 13:48:41 2013 -0700 >> +++ b/src/share/classes/javax/lang/model/AnnotatedConstruct.java Mon May >> 20 22:34:23 2013 -0700 >> @@ -39,35 +39,72 @@ >> * are on a declaration, whereas annotations on a type are on >> * a specific use of a type name. >> * >> - * The terms directly present and present are used >> + * The terms directly present, present, >> + * indirectly present, and associated are used >> * throughout this interface to describe precisely which annotations >> - * are returned by methods: >> + * are returned by the methods defined herein. >> * >> - *

    An annotation A is directly present on a >> - * construct E if E is annotated, and: >> + *

    In the definitions below, an annotation A has an >> + * annotation type AT. If AT is a repeatable annotation >> + * type, the type of the containing annotation is ATC. >> + * >> + *

    Annotation A is directly present on a construct >> + * C if either: >> * >> *

      >> * >> - *
    • for an invocation of {@code getAnnotation(Class)} or >> - * {@code getAnnotationMirrors()}, E's annotations contain >> A. >> + *
    • A is explicitly or implicitly declared as applying to >> + * the source code representation of C. >> * >> - *
    • for an invocation of {@code getAnnotationsByType(Class)}, >> - * E's annotations either contain A or, if the type of >> - * A is repeatable, contain exactly one annotation whose value >> - * element contains A and whose type is the containing >> - * annotation type of A's type. >> + *

      Typically, if exactly one annotation of type AT appears in >> + * the source code of representation of C, then A is >> + * explicitly declared as applying to C. >> + * >> + * If there are multiple annotations of type AT present on >> + * C, then if AT is repeatable annotation type, an >> + * annotation of type ATC is implicitly declared on C. >> + * >> + *

    • A representation of A appears in the executable output >> + * for C, such as the {@code RuntimeVisibleAnnotations} or >> + * {@code RuntimeVisibleParameterAnnotations} attributes of a class >> + * file. >> * >> *
    >> * >> - *

    An annotation A is present on a construct E if either: >> + *

    An annotation A is present on a >> + * construct C if either: >> + *

      >> + * >> + *
    • A is directly present on C. >> + * >> + *
    • No annotation of type AT is directly present on >> + * C, and C is a class and AT is inheritable >> + * and A is present on the superclass of C. >> + * >> + *
    >> + * >> + * An annotation A is indirectly present on a construct >> + * C if both: >> * >> *
      >> - *
    • A is directly present on E; or >> * >> - *
    • A is not directly present on E, and >> - * E is an element representing a class, and A's type >> - * is inheritable, and A is present on the element >> - * representing the superclass of E. >> + *
    • AT is a repeatable annotation type with a containing >> annotation type ATC. >> + * >> + *
    • An annotation of type ATC is directly present on >> C. >> + * >> + *
    >> + * >> + * An annotation A is associated with a construct >> + * C if either: >> + * >> + *
      >> + * >> + *
    • A is directly or indirectly present on C. >> + * >> + *
    • No annotation of type AT is directly or indirectly >> + * present on C, C is a class, and AT is >> + * inheritable, and AT is associated with the superclass of >> + * C. >> * >> *
    >> * >> >> >>> >>> Alex >>> >>> On 5/15/2013 11:22 PM, Joe Darcy wrote: >>>> Hello, >>>> >>>> I've been working to update the javadoc specification in >>>> javax.lang.model.* with the new present / directly present / etc. >>>> terminology from the latest 8misc.pdf file. >>>> >>>> Proposed patch is below. >>>> >>>> Full webrev of the change available from >>>> >>>> http://cr.openjdk.java.net/~darcy/8010680.1/ >>>> >>>> Thanks, >>>> >>>> -Joe >> From alex.buckley at oracle.com Wed May 22 12:52:07 2013 From: alex.buckley at oracle.com (Alex Buckley) Date: Wed, 22 May 2013 12:52:07 -0700 Subject: Proposed incorporation of specification change for present/directly present/etc. terminology into javax.lang.model In-Reply-To: <519C4BD5.7040709@oracle.com> References: <51947B32.70701@oracle.com> <51952BE4.9070002@oracle.com> <519B07A8.6040903@oracle.com> <519C0F40.3050802@oracle.com> <519C4BD5.7040709@oracle.com> Message-ID: <519D21E7.1040703@oracle.com> - For readability the definition of "associated" could use an "and" before "C is a class". - The definition of "indirectly present" is missing a "the" before "result", and wrongly implies that multiple annotations will always be reported by calling the value() method ("A is one of the annotations included in ..."). I updated JDK-8010680 to incorporate the edits I suggested earlier in this thread plus the note you added to "directly present" ("Typically, ..."). It's the text I will add to the PDF for long-term memory about these definitions. If it's not what you want to put in javadoc, please edit the bug. Alex On 5/21/2013 9:38 PM, Joe Darcy wrote: > Hello, > > On 05/21/2013 05:20 PM, Alex Buckley wrote: >> - "directly present" and "present" are OK. >> >> - "indirectly present" still doesn't bind A strongly enough ... it's >> necessary but not sufficient that an annotation of type ATC is >> directly present on C ... the sufficient clause is that the ATC-typed >> annotation must have a value element which contains A. >> >> - "associated" is almost OK except for a type error: the final clause >> must be "and A is associated with the superclass of C." >> (The domain of "associated" is annotations, not annotation types, so >> AT is never associated with anything.) > > Hopefully final iteration; edits to "indirectly present" and > "associated" definitions compared to the current code: > > + * An annotation A is indirectly present on a construct > + * C if both: > * > *
      > - *
    • A is directly present on E; or > * > - *
    • A is not directly present on E, and > - * E is an element representing a class, and A's type > - * is inheritable, and A is present on the element > - * representing the superclass of E. > + *
    • AT is a repeatable annotation type with a containing > + * annotation type ATC. > + * > + *
    • An annotation of type ATC is directly present on > + * C and A is one of the annotations included in result > + * of calling the {@code value} method of the directly present > + * annotation of type ATC. > + * > + *
    > + * > + * An annotation A is associated with a construct > + * C if either: > + * > + *
      > + * > + *
    • A is directly or indirectly present on C. > + * > + *
    • No annotation of type AT is directly or indirectly > + * present on C, C is a class, and AT is > + * inheritable, and A is associated with the superclass of > + * C. > * > > Full new webrev at > > http://cr.openjdk.java.net/~darcy/8010680.3 > > Thanks, > > -Joe > >> >> Alex >> >> On 5/20/2013 10:35 PM, Joe Darcy wrote: >>> Hello, >>> >>> On 05/16/2013 11:56 AM, Alex Buckley wrote: >>>> 1. "directly present" says the annotation @Foo(x=1) is directly >>>> present if any annotation of type Foo is present. (Assuming an int >>>> element x in type Foo.) So is @Foo(x=2). And @Foo(x=3). And @Foo(x=4). >>>> And so on. I know we only have type-based lookup for annotations >>>> today, but we should not open the door to weirdo answers for "tell me >>>> all the annotations of type Foo which are directly present". Try this: >>>> >>>> -- >>>> An annotation A is directly present on a construct C if either: >>>> >>>> - A is explicitly or implicitly declared as applying to the source >>>> code representation of C; or >>>> - A appears in the executable output corresponding to C, such as in >>>> the RuntimeVisibleAnnotations attribute of a class file. >>>> -- >>>> >>>> (The "declared" in "explicitly or implicitly declared" does not >>>> pertain to solely declaration annotations. If you repeat a type >>>> annotation, then the type annotations' container annotation will be an >>>> implicitly declared type annotation.) >>>> >>>> 2. The "present" and "associated" definitions both use the type AT but >>>> it's not bound to anything. >>>> >>>> 3. The "indirectly present" definition also has AT spring out of >>>> nowhere, but also it's important to say "... if both of the following >>>> conditions are true:" rather than just "... if:" because it's easy to >>>> assume the bullet point are alternatives as in the other three >>>> definitions. >>> >>> Reworked portions of the patch below; full webrev at >>> >>> http://cr.openjdk.java.net/~darcy/8010680.2 >>> >>> Thanks, >>> >>> -Joe >>> >>> --- a/src/share/classes/javax/lang/model/AnnotatedConstruct.java Fri May >>> 17 13:48:41 2013 -0700 >>> +++ b/src/share/classes/javax/lang/model/AnnotatedConstruct.java Mon May >>> 20 22:34:23 2013 -0700 >>> @@ -39,35 +39,72 @@ >>> * are on a declaration, whereas annotations on a type are on >>> * a specific use of a type name. >>> * >>> - * The terms directly present and present are used >>> + * The terms directly present, present, >>> + * indirectly present, and associated are used >>> * throughout this interface to describe precisely which annotations >>> - * are returned by methods: >>> + * are returned by the methods defined herein. >>> * >>> - *

      An annotation A is directly present on a >>> - * construct E if E is annotated, and: >>> + *

      In the definitions below, an annotation A has an >>> + * annotation type AT. If AT is a repeatable annotation >>> + * type, the type of the containing annotation is ATC. >>> + * >>> + *

      Annotation A is directly present on a construct >>> + * C if either: >>> * >>> *

        >>> * >>> - *
      • for an invocation of {@code getAnnotation(Class)} or >>> - * {@code getAnnotationMirrors()}, E's annotations contain >>> A. >>> + *
      • A is explicitly or implicitly declared as applying to >>> + * the source code representation of C. >>> * >>> - *
      • for an invocation of {@code getAnnotationsByType(Class)}, >>> - * E's annotations either contain A or, if the type of >>> - * A is repeatable, contain exactly one annotation whose value >>> - * element contains A and whose type is the containing >>> - * annotation type of A's type. >>> + *

        Typically, if exactly one annotation of type AT appears in >>> + * the source code of representation of C, then A is >>> + * explicitly declared as applying to C. >>> + * >>> + * If there are multiple annotations of type AT present on >>> + * C, then if AT is repeatable annotation type, an >>> + * annotation of type ATC is implicitly declared on C. >>> + * >>> + *

      • A representation of A appears in the executable output >>> + * for C, such as the {@code RuntimeVisibleAnnotations} or >>> + * {@code RuntimeVisibleParameterAnnotations} attributes of a class >>> + * file. >>> * >>> *
      >>> * >>> - *

      An annotation A is present on a construct E if either: >>> + *

      An annotation A is present on a >>> + * construct C if either: >>> + *

        >>> + * >>> + *
      • A is directly present on C. >>> + * >>> + *
      • No annotation of type AT is directly present on >>> + * C, and C is a class and AT is inheritable >>> + * and A is present on the superclass of C. >>> + * >>> + *
      >>> + * >>> + * An annotation A is indirectly present on a construct >>> + * C if both: >>> * >>> *
        >>> - *
      • A is directly present on E; or >>> * >>> - *
      • A is not directly present on E, and >>> - * E is an element representing a class, and A's type >>> - * is inheritable, and A is present on the element >>> - * representing the superclass of E. >>> + *
      • AT is a repeatable annotation type with a containing >>> annotation type ATC. >>> + * >>> + *
      • An annotation of type ATC is directly present on >>> C. >>> + * >>> + *
      >>> + * >>> + * An annotation A is associated with a construct >>> + * C if either: >>> + * >>> + *
        >>> + * >>> + *
      • A is directly or indirectly present on C. >>> + * >>> + *
      • No annotation of type AT is directly or indirectly >>> + * present on C, C is a class, and AT is >>> + * inheritable, and AT is associated with the superclass of >>> + * C. >>> * >>> *
      >>> * >>> >>> >>>> >>>> Alex >>>> >>>> On 5/15/2013 11:22 PM, Joe Darcy wrote: >>>>> Hello, >>>>> >>>>> I've been working to update the javadoc specification in >>>>> javax.lang.model.* with the new present / directly present / etc. >>>>> terminology from the latest 8misc.pdf file. >>>>> >>>>> Proposed patch is below. >>>>> >>>>> Full webrev of the change available from >>>>> >>>>> http://cr.openjdk.java.net/~darcy/8010680.1/ >>>>> >>>>> Thanks, >>>>> >>>>> -Joe >>> > From joe.darcy at oracle.com Wed May 22 13:18:09 2013 From: joe.darcy at oracle.com (Joe Darcy) Date: Wed, 22 May 2013 13:18:09 -0700 Subject: Proposed incorporation of specification change for present/directly present/etc. terminology into javax.lang.model In-Reply-To: <519D21E7.1040703@oracle.com> References: <51947B32.70701@oracle.com> <51952BE4.9070002@oracle.com> <519B07A8.6040903@oracle.com> <519C0F40.3050802@oracle.com> <519C4BD5.7040709@oracle.com> <519D21E7.1040703@oracle.com> Message-ID: <519D2801.4050503@oracle.com> On 05/22/2013 12:52 PM, Alex Buckley wrote: > - For readability the definition of "associated" could use an "and" > before "C is a class". Fixed. > > - The definition of "indirectly present" is missing a "the" before > "result", and wrongly implies that multiple annotations will always be > reported by calling the value() method ("A is one of the annotations > included in ..."). Changed to: * An annotation A is indirectly present on a construct * C if both: * *
        * *
      • AT is a repeatable annotation type with a containing * annotation type ATC. * *
      • An annotation of type ATC is directly present on * C and A is an annotation included in the result of * calling the {@code value} method of the directly present annotation * of type ATC. In the near future, I will push this version; webrev at http://cr.openjdk.java.net/~darcy/8010680.4 Thanks, -Joe > > I updated JDK-8010680 to incorporate the edits I suggested earlier in > this thread plus the note you added to "directly present" ("Typically, > ..."). It's the text I will add to the PDF for long-term memory about > these definitions. If it's not what you want to put in javadoc, please > edit the bug. > > Alex > > On 5/21/2013 9:38 PM, Joe Darcy wrote: >> Hello, >> >> On 05/21/2013 05:20 PM, Alex Buckley wrote: >>> - "directly present" and "present" are OK. >>> >>> - "indirectly present" still doesn't bind A strongly enough ... it's >>> necessary but not sufficient that an annotation of type ATC is >>> directly present on C ... the sufficient clause is that the ATC-typed >>> annotation must have a value element which contains A. >>> >>> - "associated" is almost OK except for a type error: the final clause >>> must be "and A is associated with the superclass of C." >>> (The domain of "associated" is annotations, not annotation types, so >>> AT is never associated with anything.) >> >> Hopefully final iteration; edits to "indirectly present" and >> "associated" definitions compared to the current code: >> >> + * An annotation A is indirectly present on a construct >> + * C if both: >> * >> *
          >> - *
        • A is directly present on E; or >> * >> - *
        • A is not directly present on E, and >> - * E is an element representing a class, and A's type >> - * is inheritable, and A is present on the element >> - * representing the superclass of E. >> + *
        • AT is a repeatable annotation type with a containing >> + * annotation type ATC. >> + * >> + *
        • An annotation of type ATC is directly present on >> + * C and A is one of the annotations included in result >> + * of calling the {@code value} method of the directly present >> + * annotation of type ATC. >> + * >> + *
        >> + * >> + * An annotation A is associated with a construct >> + * C if either: >> + * >> + *
          >> + * >> + *
        • A is directly or indirectly present on C. >> + * >> + *
        • No annotation of type AT is directly or indirectly >> + * present on C, C is a class, and AT is >> + * inheritable, and A is associated with the superclass of >> + * C. >> * >> >> Full new webrev at >> >> http://cr.openjdk.java.net/~darcy/8010680.3 >> >> Thanks, >> >> -Joe >> >>> >>> Alex >>> >>> On 5/20/2013 10:35 PM, Joe Darcy wrote: >>>> Hello, >>>> >>>> On 05/16/2013 11:56 AM, Alex Buckley wrote: >>>>> 1. "directly present" says the annotation @Foo(x=1) is directly >>>>> present if any annotation of type Foo is present. (Assuming an int >>>>> element x in type Foo.) So is @Foo(x=2). And @Foo(x=3). And >>>>> @Foo(x=4). >>>>> And so on. I know we only have type-based lookup for annotations >>>>> today, but we should not open the door to weirdo answers for "tell me >>>>> all the annotations of type Foo which are directly present". Try >>>>> this: >>>>> >>>>> -- >>>>> An annotation A is directly present on a construct C if either: >>>>> >>>>> - A is explicitly or implicitly declared as applying to the source >>>>> code representation of C; or >>>>> - A appears in the executable output corresponding to C, such as in >>>>> the RuntimeVisibleAnnotations attribute of a class file. >>>>> -- >>>>> >>>>> (The "declared" in "explicitly or implicitly declared" does not >>>>> pertain to solely declaration annotations. If you repeat a type >>>>> annotation, then the type annotations' container annotation will >>>>> be an >>>>> implicitly declared type annotation.) >>>>> >>>>> 2. The "present" and "associated" definitions both use the type AT >>>>> but >>>>> it's not bound to anything. >>>>> >>>>> 3. The "indirectly present" definition also has AT spring out of >>>>> nowhere, but also it's important to say "... if both of the following >>>>> conditions are true:" rather than just "... if:" because it's easy to >>>>> assume the bullet point are alternatives as in the other three >>>>> definitions. >>>> >>>> Reworked portions of the patch below; full webrev at >>>> >>>> http://cr.openjdk.java.net/~darcy/8010680.2 >>>> >>>> Thanks, >>>> >>>> -Joe >>>> >>>> --- a/src/share/classes/javax/lang/model/AnnotatedConstruct.java >>>> Fri May >>>> 17 13:48:41 2013 -0700 >>>> +++ b/src/share/classes/javax/lang/model/AnnotatedConstruct.java >>>> Mon May >>>> 20 22:34:23 2013 -0700 >>>> @@ -39,35 +39,72 @@ >>>> * are on a declaration, whereas annotations on a type >>>> are on >>>> * a specific use of a type name. >>>> * >>>> - * The terms directly present and present are used >>>> + * The terms directly present, present, >>>> + * indirectly present, and associated are used >>>> * throughout this interface to describe precisely which annotations >>>> - * are returned by methods: >>>> + * are returned by the methods defined herein. >>>> * >>>> - *

          An annotation A is directly present on a >>>> - * construct E if E is annotated, and: >>>> + *

          In the definitions below, an annotation A has an >>>> + * annotation type AT. If AT is a repeatable annotation >>>> + * type, the type of the containing annotation is ATC. >>>> + * >>>> + *

          Annotation A is directly present on a construct >>>> + * C if either: >>>> * >>>> *

            >>>> * >>>> - *
          • for an invocation of {@code getAnnotation(Class)} or >>>> - * {@code getAnnotationMirrors()}, E's annotations contain >>>> A. >>>> + *
          • A is explicitly or implicitly declared as applying to >>>> + * the source code representation of C. >>>> * >>>> - *
          • for an invocation of {@code getAnnotationsByType(Class)}, >>>> - * E's annotations either contain A or, if the type of >>>> - * A is repeatable, contain exactly one annotation whose value >>>> - * element contains A and whose type is the containing >>>> - * annotation type of A's type. >>>> + *

            Typically, if exactly one annotation of type AT >>>> appears in >>>> + * the source code of representation of C, then A is >>>> + * explicitly declared as applying to C. >>>> + * >>>> + * If there are multiple annotations of type AT present on >>>> + * C, then if AT is repeatable annotation type, an >>>> + * annotation of type ATC is implicitly declared on C. >>>> + * >>>> + *

          • A representation of A appears in the executable output >>>> + * for C, such as the {@code RuntimeVisibleAnnotations} or >>>> + * {@code RuntimeVisibleParameterAnnotations} attributes of a class >>>> + * file. >>>> * >>>> *
          >>>> * >>>> - *

          An annotation A is present on a construct E if either: >>>> + *

          An annotation A is present on a >>>> + * construct C if either: >>>> + *

            >>>> + * >>>> + *
          • A is directly present on C. >>>> + * >>>> + *
          • No annotation of type AT is directly present on >>>> + * C, and C is a class and AT is inheritable >>>> + * and A is present on the superclass of C. >>>> + * >>>> + *
          >>>> + * >>>> + * An annotation A is indirectly present on a >>>> construct >>>> + * C if both: >>>> * >>>> *
            >>>> - *
          • A is directly present on E; or >>>> * >>>> - *
          • A is not directly present on E, and >>>> - * E is an element representing a class, and A's type >>>> - * is inheritable, and A is present on the element >>>> - * representing the superclass of E. >>>> + *
          • AT is a repeatable annotation type with a containing >>>> annotation type ATC. >>>> + * >>>> + *
          • An annotation of type ATC is directly present on >>>> C. >>>> + * >>>> + *
          >>>> + * >>>> + * An annotation A is associated with a construct >>>> + * C if either: >>>> + * >>>> + *
            >>>> + * >>>> + *
          • A is directly or indirectly present on C. >>>> + * >>>> + *
          • No annotation of type AT is directly or indirectly >>>> + * present on C, C is a class, and AT is >>>> + * inheritable, and AT is associated with the superclass of >>>> + * C. >>>> * >>>> *
          >>>> * >>>> >>>> >>>>> >>>>> Alex >>>>> >>>>> On 5/15/2013 11:22 PM, Joe Darcy wrote: >>>>>> Hello, >>>>>> >>>>>> I've been working to update the javadoc specification in >>>>>> javax.lang.model.* with the new present / directly present / etc. >>>>>> terminology from the latest 8misc.pdf file. >>>>>> >>>>>> Proposed patch is below. >>>>>> >>>>>> Full webrev of the change available from >>>>>> >>>>>> http://cr.openjdk.java.net/~darcy/8010680.1/ >>>>>> >>>>>> Thanks, >>>>>> >>>>>> -Joe >>>> >> From joe.darcy at oracle.com Wed May 22 21:56:39 2013 From: joe.darcy at oracle.com (Joe Darcy) Date: Wed, 22 May 2013 21:56:39 -0700 Subject: Updates to javax.annotation.processing.Processor for repeating annotations Message-ID: <519DA187.3030109@oracle.com> Hello, Now that the new present, directly present, etc. terminology is worked out, the time has come to update the specification of the annotation processing discovery procedure to take into account repeating annotations (and other annotation updates in Java SE 8). Proposed diff below. Full webrev of proposed specification and implementation changes at: http://cr.openjdk.java.net/~darcy/7162089.2/ Thanks, -Joe @@ -88,7 +90,8 @@ * configuration mechanisms, such as command line options; for * details, refer to the particular tool's documentation. Which * processors the tool asks to {@linkplain #process run} is a function - * of what annotations are present on the {@linkplain + * of the types of the annotations {@linkplain AnnotatedConstruct present} + * on the {@linkplain * RoundEnvironment#getRootElements root elements}, what {@linkplain * #getSupportedAnnotationTypes annotation types a processor * processes}, and whether or not a processor {@linkplain #process @@ -106,6 +109,28 @@ * processing {@code "*"} can claim the (empty) set of annotation * types. * + *

          An annotation type is considered present if there is at least + * one annotation of that type present on an element enclosed within + * the root elements of a round. Annotations on {@linkplain + * ElementType#TYPE_USE type uses} are not considered as part + * of the computation. For this purpose, a type parameter is + * considered to be enclosed by its {@linkplain + * TypeParameter#getGenericElement generic element}. An annotation is + * present if it meets the definition of being present given in {@link + * AnnotatedConstruct}. In brief, an annotation is considered present + * for the purposes of discovery if it is directly present or present + * via inheritance. An annotation is not considered present + * by virtue of being wrapped by a container + * annotation. Operationally, this is equivalent to an annotation + * being present on an element if and only if it would be included in + * the results of {@link Elements#getAllAnnotationMirrors()} called on + * that element. Since annotations inside container annotations are + * not considered present, to properly process {@linkplain + * java.lang.annotation.Repeatable repeatable annotation types}, + * processors are advised to include both the annotation and its + * container in the set of {@linkplain #getSupportedAnnotationTypes() + * supported annotation types} of a processor. + * *

          Note that if a processor supports {@code "*"} and returns {@code * true}, all annotations are claimed. Therefore, a universal * processor being used to, for example, implement additional validity From alex.buckley at oracle.com Thu May 23 12:05:24 2013 From: alex.buckley at oracle.com (Alex Buckley) Date: Thu, 23 May 2013 12:05:24 -0700 Subject: Updates to javax.annotation.processing.Processor for repeating annotations In-Reply-To: <519DA187.3030109@oracle.com> References: <519DA187.3030109@oracle.com> Message-ID: <519E6874.1020004@oracle.com> Thanks Joe. Since annotation [type] discovery applies to type annotations as well as repeating annotations, I have responded to the spec update on the type-annotations-spec-comments list (which uses the same license as this list). Please see: http://mail.openjdk.java.net/pipermail/type-annotations-spec-comments/2013-May/000034.html. Alex On 5/22/2013 9:56 PM, Joe Darcy wrote: > Hello, > > Now that the new present, directly present, etc. terminology is worked > out, the time has come to update the specification of the annotation > processing discovery procedure to take into account repeating > annotations (and other annotation updates in Java SE 8). > > Proposed diff below. Full webrev of proposed specification and > implementation changes at: > > http://cr.openjdk.java.net/~darcy/7162089.2/ > > Thanks, > > -Joe > > @@ -88,7 +90,8 @@ > * configuration mechanisms, such as command line options; for > * details, refer to the particular tool's documentation. Which > * processors the tool asks to {@linkplain #process run} is a function > - * of what annotations are present on the {@linkplain > + * of the types of the annotations {@linkplain AnnotatedConstruct > present} > + * on the {@linkplain > * RoundEnvironment#getRootElements root elements}, what {@linkplain > * #getSupportedAnnotationTypes annotation types a processor > * processes}, and whether or not a processor {@linkplain #process > @@ -106,6 +109,28 @@ > * processing {@code "*"} can claim the (empty) set of annotation > * types. > * > + *

          An annotation type is considered present if there is at least > + * one annotation of that type present on an element enclosed within > + * the root elements of a round. Annotations on {@linkplain > + * ElementType#TYPE_USE type uses} are not considered as part > + * of the computation. For this purpose, a type parameter is > + * considered to be enclosed by its {@linkplain > + * TypeParameter#getGenericElement generic element}. An annotation is > + * present if it meets the definition of being present given in {@link > + * AnnotatedConstruct}. In brief, an annotation is considered present > + * for the purposes of discovery if it is directly present or present > + * via inheritance. An annotation is not considered present > + * by virtue of being wrapped by a container > + * annotation. Operationally, this is equivalent to an annotation > + * being present on an element if and only if it would be included in > + * the results of {@link Elements#getAllAnnotationMirrors()} called on > + * that element. Since annotations inside container annotations are > + * not considered present, to properly process {@linkplain > + * java.lang.annotation.Repeatable repeatable annotation types}, > + * processors are advised to include both the annotation and its > + * container in the set of {@linkplain #getSupportedAnnotationTypes() > + * supported annotation types} of a processor. > + * > *

          Note that if a processor supports {@code "*"} and returns {@code > * true}, all annotations are claimed. Therefore, a universal > * processor being used to, for example, implement additional validity >