8225540: In core reflection note whether returned annotations are dec…

…laration or type annotations

Reviewed-by: alanb, prappo

src/java.base/share/classes/java/lang/Class.java

@@ -3779,9 +3779,14 @@ public <U> Class<? extends U> asSubclass(Class<U> clazz) {
     }
 
     /**
+     * {@inheritDoc}
+     * <p>Note that any annotation returned by this method is a
+     * declaration annotation.
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.5
      */
+    @Override
     @SuppressWarnings("unchecked")
     public <A extends Annotation> A getAnnotation(Class<A> annotationClass) {
         Objects.requireNonNull(annotationClass);
@@ -3800,6 +3805,10 @@ public boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)
     }
 
     /**
+     * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.8
      */
@@ -3814,13 +3823,22 @@ public <A extends Annotation> A[] getAnnotationsByType(Class<A> annotationClass)
     }
 
     /**
+     * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @since 1.5
      */
+    @Override
     public Annotation[] getAnnotations() {
         return AnnotationParser.toArray(annotationData().annotations);
     }
 
     /**
+     * {@inheritDoc}
+     * <p>Note that any annotation returned by this method is a
+     * declaration annotation.
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.8
      */
@@ -3833,6 +3851,10 @@ public <A extends Annotation> A getDeclaredAnnotation(Class<A> annotationClass)
     }
 
     /**
+     * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.8
      */
@@ -3845,8 +3867,13 @@ public <A extends Annotation> A[] getDeclaredAnnotationsByType(Class<A> annotati
     }
 
     /**
+     * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @since 1.5
      */
+    @Override
     public Annotation[] getDeclaredAnnotations()  {
         return AnnotationParser.toArray(annotationData().declaredAnnotations);
     }

src/java.base/share/classes/java/lang/Module.java

@@ -1381,6 +1381,9 @@ private static Module findModule(String target,
     /**
      * {@inheritDoc}
      * This method returns {@code null} when invoked on an unnamed module.
+     *
+     * <p> Note that any annotation returned by this method is a
+     * declaration annotation.
      */
     @Override
     public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
@@ -1390,6 +1393,9 @@ public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
     /**
      * {@inheritDoc}
      * This method returns an empty array when invoked on an unnamed module.
+     *
+     * <p> Note that any annotations returned by this method are
+     * declaration annotations.
      */
     @Override
     public Annotation[] getAnnotations() {
@@ -1399,6 +1405,9 @@ public Annotation[] getAnnotations() {
     /**
      * {@inheritDoc}
      * This method returns an empty array when invoked on an unnamed module.
+     *
+     * <p> Note that any annotations returned by this method are
+     * declaration annotations.
      */
     @Override
     public Annotation[] getDeclaredAnnotations() {

src/java.base/share/classes/java/lang/Package.java

@@ -434,9 +434,14 @@ class PackageInfoProxy {}
     }
 
     /**
+     * {@inheritDoc}
+     * <p>Note that any annotation returned by this method is a
+     * declaration annotation.
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.5
      */
+    @Override
     public <A extends Annotation> A getAnnotation(Class<A> annotationClass) {
         return getPackageInfo().getAnnotation(annotationClass);
     }
@@ -452,6 +457,10 @@ public boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)
     }
 
     /**
+     * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.8
      */
@@ -461,13 +470,21 @@ public  <A extends Annotation> A[] getAnnotationsByType(Class<A> annotationClass
     }
 
     /**
+     * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
      * @since 1.5
      */
+    @Override
     public Annotation[] getAnnotations() {
         return getPackageInfo().getAnnotations();
     }
 
     /**
+     * {@inheritDoc}
+     * <p>Note that any annotation returned by this method is a
+     * declaration annotation.
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.8
      */
@@ -486,8 +503,12 @@ public <A extends Annotation> A[] getDeclaredAnnotationsByType(Class<A> annotati
     }
 
     /**
+     * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
      * @since 1.5
      */
+    @Override
     public Annotation[] getDeclaredAnnotations()  {
         return getPackageInfo().getDeclaredAnnotations();
     }

src/java.base/share/classes/java/lang/reflect/AccessibleObject.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 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
@@ -509,15 +509,22 @@ protected AccessibleObject() {}
             new ReflectionFactory.GetReflectionFactoryAction());
 
     /**
+     * {@inheritDoc}
+     *
+     * <p> Note that any annotation returned by this method is a
+     * declaration annotation.
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.5
      */
+    @Override
     public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
         throw new AssertionError("All subclasses should override this method");
     }
 
     /**
      * {@inheritDoc}
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.5
      */
@@ -527,6 +534,11 @@ public boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)
     }
 
     /**
+     * {@inheritDoc}
+     *
+     * <p> Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.8
      */
@@ -536,13 +548,24 @@ public <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass)
     }
 
     /**
+     * {@inheritDoc}
+     *
+     * <p> Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @since 1.5
      */
+    @Override
     public Annotation[] getAnnotations() {
         return getDeclaredAnnotations();
     }
 
     /**
+     * {@inheritDoc}
+     *
+     * <p> Note that any annotation returned by this method is a
+     * declaration annotation.
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.8
      */
@@ -555,6 +578,11 @@ public <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass)
     }
 
     /**
+     * {@inheritDoc}
+     *
+     * <p> Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.8
      */
@@ -567,8 +595,14 @@ public <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotati
     }
 
     /**
+     * {@inheritDoc}
+     *
+     * <p> Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @since 1.5
      */
+    @Override
     public Annotation[] getDeclaredAnnotations()  {
         throw new AssertionError("All subclasses should override this method");
     }

src/java.base/share/classes/java/lang/reflect/AnnotatedElement.java

@@ -38,20 +38,38 @@
 import sun.reflect.annotation.AnnotationType;
 
 /**
- * Represents an annotated element of the program currently running in this
- * VM.  This interface allows annotations to be read reflectively.  All
+ * Represents an annotated construct of the program currently running
+ * in this VM.
+ *
+ * A construct is either an element or a type. Annotations on an
+ * element 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>.
+ *
+ * Note that any annotations returned by methods on the {@link
+ * AnnotatedType AnnotatedType} interface and its subinterfaces are
+ * type annotations as the entity being potentially annotated is a
+ * type. Annotations returned by methods outside of the {@code
+ * AnnotatedType} hierarchy are declaration annotations.
+ *
+ * <p>This interface allows annotations to be read reflectively.  All
  * annotations returned by methods in this interface are immutable and
- * serializable. The arrays returned by methods of this interface may be modified
- * by callers without affecting 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.
  *
  * <p>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), 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.
+ * either method is a repeatable annotation type (JLS {@jls 9.6}),
+ * then the method will "look through" a container annotation (JLS
+ * {@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.
  *
  * <p>The terms <em>directly present</em>, <em>indirectly present</em>,
  * <em>present</em>, and <em>associated</em> are used throughout this
@@ -260,8 +278,8 @@ public interface AnnotatedElement {
      * <p>The truth value returned by this method is equivalent to:
      * {@code getAnnotation(annotationClass) != null}
      *
-     * <p>The body of the default method is specified to be the code
-     * above.
+     * @implSpec The default implementation returns {@code
+     * getAnnotation(annotationClass) != null}.
      *
      * @param annotationClass the Class object corresponding to the
      *        annotation type
@@ -310,7 +328,7 @@ default boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)
      *
      * The difference between this method and {@link #getAnnotation(Class)}
      * is that this method detects if its argument is a <em>repeatable
-     * annotation type</em> (JLS 9.6), and if so, attempts to find one or
+     * annotation type</em> (JLS {@jls 9.6}), and if so, attempts to find one or
      * more annotations of that type by "looking through" a container
      * annotation.
      *
@@ -406,7 +424,7 @@ default <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass)
      *
      * The difference between this method and {@link
      * #getDeclaredAnnotation(Class)} is that this method detects if its
-     * argument is a <em>repeatable annotation type</em> (JLS 9.6), and if so,
+     * argument is a <em>repeatable annotation type</em> (JLS {@jls 9.6}), and if so,
      * attempts to find one or more annotations of that type by "looking
      * through" a container annotation if one is present.
      *

src/java.base/share/classes/java/lang/reflect/AnnotatedType.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 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
@@ -25,12 +25,18 @@
 
 package java.lang.reflect;
 
+import java.lang.annotation.Annotation;
+
 /**
  * {@code AnnotatedType} represents the potentially annotated use of a type in
  * the program currently running in this VM. The use may be of any type in the
  * Java programming language, including an array type, a parameterized type, a
  * type variable, or a wildcard type.
  *
+ * Note that any annotations returned by methods on this interface are
+ * <em>type annotations</em> (JLS {@jls 9.7.4}) as the entity being
+ * potentially annotated is a type.
+ *
  * @since 1.8
  */
 public interface AnnotatedType extends AnnotatedElement {
@@ -72,4 +78,30 @@ default AnnotatedType getAnnotatedOwnerType() {
      * @return the type this annotated type represents
      */
     public Type getType();
+
+    /**
+     * {@inheritDoc}
+     * <p>Note that any annotation returned by this method is a type
+     * annotation.
+     *
+     * @throws NullPointerException {@inheritDoc}
+     */
+    @Override
+    <T extends Annotation> T getAnnotation(Class<T> annotationClass);
+
+    /**
+     * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are type
+     * annotations.
+     */
+    @Override
+    Annotation[] getAnnotations();
+
+    /**
+     * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are type
+     * annotations.
+     */
+    @Override
+    Annotation[] getDeclaredAnnotations();
 }