changeset 58192:7abee91f0bb5

8225495: Note whether returned annotations are declaration annotations or type annotations Reviewed-by: jjg
author darcy
date Thu, 27 Feb 2020 10:30:08 -0800
parents 8f26915495d6
children 6e9aa02cf215
files src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java src/java.compiler/share/classes/javax/lang/model/element/Element.java src/java.compiler/share/classes/javax/lang/model/type/TypeMirror.java src/java.compiler/share/classes/javax/lang/model/util/Elements.java
diffstat 4 files changed, 70 insertions(+), 7 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java	Thu Feb 27 12:17:31 2020 -0500
+++ b/src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java	Thu Feb 27 10:30:08 2020 -0800
@@ -39,10 +39,16 @@
  * are on a <em>declaration</em>, whereas annotations on a type are on
  * a specific <em>use</em> of a type name.
  *
+ * As defined by <cite>The Java&trade; Language Specification</cite>
+ * section {@jls 9.7.4}, an annotation on an element is a
+ * <em>declaration annotation</em> and an annotation on a type is a
+ * <em>type annotation</em>.
+ *
  * The terms <em>directly present</em>, <em>present</em>,
  * <em>indirectly present</em>, and <em>associated </em> are used
- * throughout this interface to describe precisely which annotations
- * are returned by the methods defined herein.
+ * throughout this interface to describe precisely which annotations,
+ * either declaration annotations or type annotations, are returned by
+ * the methods in this interface.
  *
  * <p>In the definitions below, an annotation <i>A</i> has an
  * annotation type <i>AT</i>. If <i>AT</i> is a repeatable annotation
@@ -53,7 +59,10 @@
  *
  * <ul>
  *
- * <li><i>A</i> is explicitly or implicitly declared as applying to
+ * <li><i>A</i> is {@linkplain
+ * javax.lang.model.util.Elements#getOrigin(AnnotatedConstruct,
+ * AnnotationMirror) explicitly or implicitly}
+ * declared as applying to
  * the source code representation of <i>C</i>.
  *
  * <p>Typically, if exactly one annotation of type <i>AT</i> appears in
@@ -122,6 +131,8 @@
  * @since 1.8
  * @jls 9.6 Annotation Types
  * @jls 9.6.4.3 {@code @Inherited}
+ * @jls 9.7.4 Where Annotations May Appear
+ * @jls 9.7.5 Multiple Annotations of the Same Type
  */
 public interface AnnotatedConstruct {
     /**
--- a/src/java.compiler/share/classes/javax/lang/model/element/Element.java	Thu Feb 27 12:17:31 2020 -0500
+++ b/src/java.compiler/share/classes/javax/lang/model/element/Element.java	Thu Feb 27 10:30:08 2020 -0800
@@ -35,7 +35,6 @@
 import javax.lang.model.type.*;
 import javax.lang.model.util.*;
 
-
 /**
  * Represents a program element such as a module, package, class, or method.
  * Each element represents a static, language-level construct
@@ -268,14 +267,16 @@
     @Override
     int hashCode();
 
-
     /**
      * {@inheritDoc}
      *
-     * <p> To get inherited annotations as well, use {@link
+     * <p>To get inherited annotations as well, use {@link
      * Elements#getAllAnnotationMirrors(Element)
      * getAllAnnotationMirrors}.
      *
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @since 1.6
      */
     @Override
@@ -283,12 +284,27 @@
 
     /**
      * {@inheritDoc}
+     *
+     * <p>Note that any annotation returned by this method is a
+     * declaration annotation.
+     *
      * @since 1.6
      */
     @Override
     <A extends Annotation> A getAnnotation(Class<A> annotationType);
 
     /**
+     * {@inheritDoc}
+     *
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
+     *
+     * @since 8
+     */
+    @Override
+    <A extends Annotation> A[] getAnnotationsByType(Class<A> annotationType);
+
+    /**
      * Applies a visitor to this element.
      *
      * @param <R> the return type of the visitor's methods
--- a/src/java.compiler/share/classes/javax/lang/model/type/TypeMirror.java	Thu Feb 27 12:17:31 2020 -0500
+++ b/src/java.compiler/share/classes/javax/lang/model/type/TypeMirror.java	Thu Feb 27 10:30:08 2020 -0800
@@ -138,6 +138,39 @@
     String toString();
 
     /**
+     * {@inheritDoc}
+     *
+     * <p>Note that any annotations returned by this method are type
+     * annotations.
+     *
+     * @since 8
+     */
+    @Override
+    List<? extends AnnotationMirror> getAnnotationMirrors();
+
+    /**
+     * {@inheritDoc}
+     *
+     * <p>Note that any annotation returned by this method is a type
+     * annotation.
+     *
+     * @since 8
+     */
+    @Override
+    <A extends Annotation> A getAnnotation(Class<A> annotationType);
+
+    /**
+     * {@inheritDoc}
+     *
+     * <p>Note that any annotations returned by this method are type
+     * annotations.
+     *
+     * @since 8
+     */
+    @Override
+    <A extends Annotation> A[] getAnnotationsByType(Class<A> annotationType);
+
+    /**
      * Applies a visitor to this type.
      *
      * @param <R> the return type of the visitor's methods
--- a/src/java.compiler/share/classes/javax/lang/model/util/Elements.java	Thu Feb 27 12:17:31 2020 -0500
+++ b/src/java.compiler/share/classes/javax/lang/model/util/Elements.java	Thu Feb 27 10:30:08 2020 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, 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
@@ -514,6 +514,9 @@
      * Returns all annotations <i>present</i> on an element, whether
      * directly present or present via inheritance.
      *
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @param e  the element being examined
      * @return all annotations of the element
      * @see Element#getAnnotationMirrors