Mercurial > jdk8-mips64-public > langtools / changeset

     1.1 --- a/src/share/classes/javax/lang/model/AnnotatedConstruct.java	Wed May 22 09:59:05 2013 -0700
     1.2 +++ b/src/share/classes/javax/lang/model/AnnotatedConstruct.java	Wed May 22 13:34:03 2013 -0700
     1.3 @@ -39,35 +39,76 @@
     1.4   * are on a <em>declaration</em>, whereas annotations on a type are on
     1.5   * a specific <em>use</em> of a type name.
     1.6   *
     1.7 - * The terms <em>directly present</em> and <em>present</em> are used
     1.8 + * The terms <em>directly present</em>, <em>present</em>,
     1.9 + * <em>indirectly present</em>, and <em>associated </em> are used
    1.10   * throughout this interface to describe precisely which annotations
    1.11 - * are returned by methods:
    1.12 + * are returned by the methods defined herein.
    1.13   *
    1.14 - * <p>An annotation <i>A</i> is <em>directly present</em> on a
    1.15 - * construct <i>E</i> if <i>E</i> is annotated, and:
    1.16 + * <p>In the definitions below, an annotation <i>A</i> has an
    1.17 + * annotation type <i>AT</i>. If <i>AT</i> is a repeatable annotation
    1.18 + * type, the type of the containing annotation is <i>ATC</i>.
    1.19 + *
    1.20 + * <p>Annotation <i>A</i> is <em>directly present</em> on a construct
    1.21 + * <i>C</i> if either:
    1.22   *
    1.23   * <ul>
    1.24   *
    1.25 - * <li> for an invocation of {@code getAnnotation(Class<T>)} or
    1.26 - * {@code getAnnotationMirrors()}, <i>E</i>'s annotations contain <i>A</i>.
    1.27 + * <li><i>A</i> is explicitly or implicitly declared as applying to
    1.28 + * the source code representation of <i>C</i>.
    1.29   *
    1.30 - * <li> for an invocation of {@code getAnnotationsByType(Class<T>)},
    1.31 - * <i>E</i>'s annotations either contain <i>A</i> or, if the type of
    1.32 - * <i>A</i> is repeatable, contain exactly one annotation whose value
    1.33 - * element contains <i>A</i> and whose type is the containing
    1.34 - * annotation type of <i>A</i>'s type.
    1.35 + * <p>Typically, if exactly one annotation of type <i>AT</i> appears in
    1.36 + * the source code of representation of <i>C</i>, then <i>A</i> is
    1.37 + * explicitly declared as applying to <i>C</i>.
    1.38 + *
    1.39 + * If there are multiple annotations of type <i>AT</i> present on
    1.40 + * <i>C</i>, then if <i>AT</i> is repeatable annotation type, an
    1.41 + * annotation of type <i>ATC</i> is implicitly declared on <i>C</i>.
    1.42 + *
    1.43 + * <li> A representation of <i>A</i> appears in the executable output
    1.44 + * for <i>C</i>, such as the {@code RuntimeVisibleAnnotations} or
    1.45 + * {@code RuntimeVisibleParameterAnnotations} attributes of a class
    1.46 + * file.
    1.47   *
    1.48   * </ul>
    1.49   *
    1.50 - * <p>An annotation A is <em>present</em> on a construct E if either:
    1.51 + * <p>An annotation <i>A</i> is <em>present</em> on a
    1.52 + * construct <i>C</i> if either:
    1.53 + * <ul>
    1.54 + *
    1.55 + * <li><i>A</i> is directly present on <i>C</i>.
    1.56 + *
    1.57 + * <li>No annotation of type <i>AT</i> is directly present on
    1.58 + * <i>C</i>, and <i>C</i> is a class and <i>AT</i> is inheritable
    1.59 + * and <i>A</i> is present on the superclass of <i>C</i>.
    1.60 + *
    1.61 + * </ul>
    1.62 + *
    1.63 + * An annotation <i>A</i> is <em>indirectly present</em> on a construct
    1.64 + * <i>C</i> if both:
    1.65   *
    1.66   * <ul>
    1.67 - *  <li> <i>A</i> is <em>directly present</em> on <i>E</i>; or
    1.68   *
    1.69 - *  <li> <i>A</i> is not <em>directly present</em> on <i>E</i>, and
    1.70 - *  <i>E</i> is an element representing a class, and <i>A</i>'s type
    1.71 - *  is inheritable, and <i>A</i> is <em>present</em> on the element
    1.72 - *  representing the superclass of <i>E</i>.
    1.73 + * <li><i>AT</i> is a repeatable annotation type with a containing
    1.74 + * annotation type <i>ATC</i>.
    1.75 + *
    1.76 + * <li>An annotation of type <i>ATC</i> is directly present on
    1.77 + * <i>C</i> and <i>A</i> is an annotation included in the result of
    1.78 + * calling the {@code value} method of the directly present annotation
    1.79 + * of type <i>ATC</i>.
    1.80 + *
    1.81 + * </ul>
    1.82 + *
    1.83 + * An annotation <i>A</i> is <em>associated</em> with a construct
    1.84 + * <i>C</i> if either:
    1.85 + *
    1.86 + * <ul>
    1.87 + *
    1.88 + * <li> <i>A</i> is directly or indirectly present on <i>C</i>.
    1.89 + *
    1.90 + * <li> No annotation of type <i>AT</i> is directly or indirectly
    1.91 + * present on <i>C</i>, and <i>C</i> is a class, and <i>AT</i> is
    1.92 + * inheritable, and <i>A</i> is associated with the superclass of
    1.93 + * <i>C</i>.
    1.94   *
    1.95   * </ul>
    1.96   *
    1.97 @@ -86,9 +127,8 @@
    1.98      List<? extends AnnotationMirror> getAnnotationMirrors();
    1.99  
   1.100      /**
   1.101 -     * Returns this construct's annotation of the
   1.102 -     * specified type if such an annotation is <em>present</em>, else {@code
   1.103 -     * null}.
   1.104 +     * Returns this construct's annotation of the specified type if
   1.105 +     * such an annotation is <em>present</em>, else {@code null}.
   1.106       *
   1.107       * <p> The annotation returned by this method could contain an element
   1.108       * whose value is of type {@code Class}.
   1.109 @@ -118,9 +158,8 @@
   1.110       * @param <A>  the annotation type
   1.111       * @param annotationType  the {@code Class} object corresponding to
   1.112       *          the annotation type
   1.113 -     * @return this element's or type use's annotation for the
   1.114 -     * specified annotation type if present on this element, else
   1.115 -     * {@code null}
   1.116 +     * @return this construct's annotation for the specified
   1.117 +     * annotation type if present, else {@code null}
   1.118       *
   1.119       * @see #getAnnotationMirrors()
   1.120       * @see java.lang.reflect.AnnotatedElement#getAnnotation
   1.121 @@ -134,10 +173,16 @@
   1.122      <A extends Annotation> A getAnnotation(Class<A> annotationType);
   1.123  
   1.124      /**
   1.125 -     * Returns annotations that are <em>present</em> on this construct.
   1.126 +     * Returns annotations that are <em>associated</em> with this construct.
   1.127       *
   1.128 -     * If there are no annotations <em>present</em> on this construct,
   1.129 -     * the return value is an array of length 0.
   1.130 +     * If there are no annotations associated with this construct, the
   1.131 +     * return value is an array of length 0.
   1.132 +     *
   1.133 +     * The order of annotations which are directly or indirectly
   1.134 +     * present on a construct <i>C</i> is computed as if indirectly present
   1.135 +     * annotations on <i>C</i> are directly present on <i>C</i> in place of their
   1.136 +     * container annotation, in the order in which they appear in the
   1.137 +     * value element of the container annotation.
   1.138       *
   1.139       * The difference between this method and {@link #getAnnotation(Class)}
   1.140       * is that this method detects if its argument is a <em>repeatable
   1.141 @@ -172,8 +217,8 @@
   1.142       * @param <A>  the annotation type
   1.143       * @param annotationType  the {@code Class} object corresponding to
   1.144       *          the annotation type
   1.145 -     * @return this element's annotations for the specified annotation
   1.146 -     *         type if present on this element, else an empty array
   1.147 +     * @return this construct's annotations for the specified annotation
   1.148 +     *         type if present on this construct, else an empty array
   1.149       *
   1.150       * @see #getAnnotationMirrors()
   1.151       * @see #getAnnotation(java.lang.Class)

     2.1 --- a/src/share/classes/javax/lang/model/util/Elements.java	Wed May 22 09:59:05 2013 -0700
     2.2 +++ b/src/share/classes/javax/lang/model/util/Elements.java	Wed May 22 13:34:03 2013 -0700
     2.3 @@ -143,12 +143,13 @@
     2.4      List<? extends Element> getAllMembers(TypeElement type);
     2.5  
     2.6      /**
     2.7 -     * Returns all annotations of an element, whether
     2.8 -     * inherited or directly present.
     2.9 +     * Returns all annotations <i>present</i> on an element, whether
    2.10 +     * directly present or present via inheritance.
    2.11       *
    2.12       * @param e  the element being examined
    2.13       * @return all annotations of the element
    2.14       * @see Element#getAnnotationMirrors
    2.15 +     * @see javax.lang.model.AnnotatedConstruct
    2.16       */
    2.17      List<? extends AnnotationMirror> getAllAnnotationMirrors(Element e);
    2.18