FYI, JSR 308 and the annotation processing discovery process

Thu Jun 27 23:00:21 PDT 2013

Hello,

Swapping discussion of this specification back in so it can be brought 
to a conclusion.

Diffs of changed specification text are below. FYI, full webrev, 
including supporting implementation changes, viewable at:

 http://cr.openjdk.java.net/~darcy/7162089.3/

On 05/23/2013 11:59 AM, Alex Buckley wrote:
> Thanks very much Joe. Some distressingly tricky stuff below:
>
> On 5/22/2013 10:07 PM, Joe Darcy wrote:
>> @@ -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 @@
>
> It would be clearer and more kind-correct to say:
>
> "Which processors the tool asks to run is a function of i) the types 
> of the annotations present on the root elements, ii) the annotation 
> types supported by a processor, and iii) the annotation types claimed 
> by a processor."

The full situation is a bit more complicated. There is a set of 
annotation types. The processing environment keeps looking for 
processors to process them until the set is empty or until there are no 
processors to ask. If a processor claims annotation (types), they are 
removed from the set of unmatched annotation types. Therefore, the types 
of annotation a processor is asked to process depends on the annotation 
types claimed by processors earlier on the search path.

>
> The idea that a processor CLAIMS annotation types comes from line 104. 
> And if this is right, Processor#process must be clarified. It takes a 
> set of types - great - and returns whether the processor claims all 
> annotations of those types. If you intend to draw an equivalence 
> between "claiming all annotations of types X and Y" and "claiming the 
> annotation types X and Y", please be explicit about it. Right now, the 
> following method spec simply does not parse: "Processes a set of 
> ANNOTATION TYPES on type elements originating from the prior round and 
> returns whether or not THESE ANNOTATIONS are claimed by this processor."

I've gone through and changed the wording of Processor and 
AbstractProcessor to use "annotation types" consistently.

>
> It would also be good to say "(see below)" when line 104 introduces 
> the idea of annotation types being present, since the more common 
> concept is of annotations being present.
>
> OK, moving to the new text...
>
>> + * 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.
>
> An annotation might be able to target type uses _and_ traditional 
> declaration locations. I think you want to ignore annotations which 
> are _solely_ interested in targeting type uses. At the same time, 
> remember that ElementType.TYPE_USE means "type uses _and_ type 
> declarations and type parameter declarations". So, given an annotation 
> type Foo with @Target(TYPE_USE) and no other @Target, would @Foo being 
> present on a type declaration mean that annotation type Foo is 
> present? The answer should be "yes", because the intent of 
> ElementType.TYPE_USE is to supersede ElementType.TYPE (no doubt the 
> prior @Target of Foo) and previous annotation processors would have 
> processed @Foo on a type declaration just fine.

Clarified intention.

>
> BTW, line 102 should say "the tool computes the set of annotation 
> types PRESENT on the root elements."
>
>> + * For this purpose, a type parameter is
>> + * considered to be enclosed by its {@linkplain
>> + * TypeParameter#getGenericElement generic element}.
>
> Big context switch here from type-oriented stuff to element-oriented. 
> Please put it in in TypeParameterElement's spec.

This is compensating for a design but in the initial JSR 269 where type 
parameters were not enclosed by their declaring method/constructor or type.

>
> Please have a paragraph break before the "annotation is present" stuff.
>
>> + * 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.
>
> This was going great until: "advised to include both the annotation 
> and its container in the set of ..." - it should be "include both the 
> repeatable annotation type and its containing annotation type in the 
> set of ...".
>

Reworded.

Thanks,

-Joe

diff -r 5c548a8542b8 
src/share/classes/javax/annotation/processing/Processor.java

--- a/src/share/classes/javax/annotation/processing/Processor.java Thu 
Jun 27 17:45:56 2013 -0400
+++ b/src/share/classes/javax/annotation/processing/Processor.java Thu 
Jun 27 22:59:40 2013 -0700
@@ -1,5 +1,5 @@
  /*
- * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights 
reserved.
+ * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights 
reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
@@ -26,6 +26,8 @@
  package javax.annotation.processing;

  import java.util.Set;
+import javax.lang.model.util.Elements;
+import javax.lang.model.AnnotatedConstruct;
  import javax.lang.model.element.*;
  import javax.lang.model.SourceVersion;

@@ -88,11 +90,12 @@
   * 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 <em>{@linkplain AnnotatedConstruct 
present}</em>
+ * on the {@linkplain
   * RoundEnvironment#getRootElements root elements}, what {@linkplain
   * #getSupportedAnnotationTypes annotation types a processor
   * processes}, and whether or not a processor {@linkplain #process
- * claims the annotations it processes}.  A processor will be asked to
+ * claims the annotation types it processes}.  A processor will be asked to
   * process a subset of the annotation types it supports, possibly an
   * empty set.
   *
@@ -106,6 +109,32 @@
   * processing {@code "*"} can claim the (empty) set of annotation
   * types.
   *
+ * <p>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}, as opposed to annotations on
+ * elements, are <em>not</em> considered as part of the
+ * computation. For this purpose, a type parameter is considered to be
+ * enclosed by its {@linkplain TypeParameter#getGenericElement generic
+ * element}.
+ *
+ * <p>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
+ * <em>not</em> 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 repeatable annotation
+ * type and its containing annotation type in the set of {@linkplain
+ * #getSupportedAnnotationTypes() supported annotation types} of a
+ * processor.
+ *
   * <p>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
@@ -257,10 +286,10 @@
      /**
       * Processes a set of annotation types on type elements
       * originating from the prior round and returns whether or not
-     * these annotations are claimed by this processor.  If {@code
-     * true} is returned, the annotations are claimed and subsequent
+     * these annotation types are claimed by this processor.  If {@code
+     * true} is returned, the annotation types are claimed and subsequent
       * processors will not be asked to process them; if {@code false}
-     * is returned, the annotations are unclaimed and subsequent
+     * is returned, the annotation types are unclaimed and subsequent
       * processors may be asked to process them.  A processor may
       * always return the same boolean value or may vary the result
       * based on chosen criteria.
@@ -271,7 +300,7 @@
       *
       * @param annotations the annotation types requested to be processed
       * @param roundEnv  environment for information about the current 
and prior round
-     * @return whether or not the set of annotations are claimed by 
this processor
+     * @return whether or not the set of annotation types are claimed 
by this processor
       */
      boolean process(Set<? extends TypeElement> annotations,
                      RoundEnvironment roundEnv);

diff -r 5c548a8542b8 
src/share/classes/javax/annotation/processing/AbstractProcessor.java
--- 
a/src/share/classes/javax/annotation/processing/AbstractProcessor.java 
Thu Jun 27 17:45:56 2013 -0400
+++ 
b/src/share/classes/javax/annotation/processing/AbstractProcessor.java 
Thu Jun 27 23:00:00 2013 -0700
@@ -38,7 +38,7 @@
   * superclass for most concrete annotation processors.  This class
   * examines annotation values to compute the {@linkplain
   * #getSupportedOptions options}, {@linkplain
- * #getSupportedAnnotationTypes annotations}, and {@linkplain
+ * #getSupportedAnnotationTypes annotation types}, and {@linkplain
   * #getSupportedSourceVersion source version} supported by its
   * subtypes.
   *

