8225540: In core reflection note whether returned annotations are declaration or type annotations

Reviewed-by: alanb, prappo

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

@@ -3779,9 +3779,14 @@ public final class Class<T> implements java.io.Serializable,
     }
 
     /**
+     * {@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 final class Class<T> implements java.io.Serializable,
     }
 
     /**
+     * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.8
      */
@@ -3814,13 +3823,22 @@ public final class Class<T> implements java.io.Serializable,
     }
 
     /**
+     * {@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 final class Class<T> implements java.io.Serializable,
     }
 
     /**
+     * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.8
      */
@@ -3845,8 +3867,13 @@ public final class Class<T> implements java.io.Serializable,
     }
 
     /**
+     * {@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 @@ public final class Module implements AnnotatedElement {
     /**
      * {@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 final class Module implements AnnotatedElement {
     /**
      * {@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 final class Module implements AnnotatedElement {
     /**
      * {@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 @@ public class Package extends NamedPackage implements java.lang.reflect.Annotated
     }
 
     /**
+     * {@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 class Package extends NamedPackage implements java.lang.reflect.Annotated
     }
 
     /**
+     * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.8
      */
@@ -461,13 +470,21 @@ public class Package extends NamedPackage implements java.lang.reflect.Annotated
     }
 
     /**
+     * {@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 class Package extends NamedPackage implements java.lang.reflect.Annotated
     }
 
     /**
+     * {@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 @@ public class AccessibleObject implements AnnotatedElement {
             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 class AccessibleObject implements AnnotatedElement {
     }
 
     /**
+     * {@inheritDoc}
+     *
+     * <p> Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.8
      */
@@ -536,13 +548,24 @@ public class AccessibleObject implements AnnotatedElement {
     }
 
     /**
+     * {@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 class AccessibleObject implements AnnotatedElement {
     }
 
     /**
+     * {@inheritDoc}
+     *
+     * <p> Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.8
      */
@@ -567,8 +595,14 @@ public class AccessibleObject implements AnnotatedElement {
     }
 
     /**
+     * {@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.AnnotationSupport;
 import sun.reflect.annotation.AnnotationType;
 
 /**
- * Represents an annotated element of the program currently running in this
+ * Represents an annotated construct of the program currently running
- * VM.  This interface allows annotations to be read reflectively.  All
+ * 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
+ * serializable. The arrays returned by methods of this interface may
- * by callers without affecting the arrays returned to other callers.
+ * 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
+ * either method is a repeatable annotation type (JLS {@jls 9.6}),
- * method will "look through" a container annotation (JLS 9.7), if
+ * then the method will "look through" a container annotation (JLS
- * present, and return any annotations inside the container. Container
+ * {@jls 9.7}), if present, and return any annotations inside the
- * annotations may be generated at compile-time to wrap multiple
+ * container. Container annotations may be generated at compile-time
- * annotations of the argument type.
+ * 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
+     * @implSpec The default implementation returns {@code
-     * above.
+     * getAnnotation(annotationClass) != null}.
      *
      * @param annotationClass the Class object corresponding to the
      *        annotation type
@@ -310,7 +328,7 @@ public interface AnnotatedElement {
      *
      * 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 @@ public interface AnnotatedElement {
      *
      * 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 @@ public interface AnnotatedType extends AnnotatedElement {
      * @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();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 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
@@ -576,9 +576,11 @@ public final class Constructor<T> extends Executable {
 
     /**
      * {@inheritDoc}
+     *
      * @throws NullPointerException  {@inheritDoc}
      * @since 1.5
      */
+    @Override
     public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
         return super.getAnnotation(annotationClass);
     }
@@ -587,6 +589,7 @@ public final class Constructor<T> extends Executable {
      * {@inheritDoc}
      * @since 1.5
      */
+    @Override
     public Annotation[] getDeclaredAnnotations()  {
         return super.getDeclaredAnnotations();
     }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2019, 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
@@ -544,6 +544,9 @@ public abstract class Executable extends AccessibleObject
      * ("synthetic") to the parameter list for a method.  See {@link
      * java.lang.reflect.Parameter} for more information.
      *
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @see java.lang.reflect.Parameter
      * @see java.lang.reflect.Parameter#getAnnotations
      * @return an array of arrays that represent the annotations on
@@ -577,6 +580,7 @@ public abstract class Executable extends AccessibleObject
      * {@inheritDoc}
      * @throws NullPointerException  {@inheritDoc}
      */
+    @Override
     public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
         Objects.requireNonNull(annotationClass);
         return annotationClass.cast(declaredAnnotations().get(annotationClass));
@@ -584,6 +588,7 @@ public abstract class Executable extends AccessibleObject
 
     /**
      * {@inheritDoc}
+     *
      * @throws NullPointerException {@inheritDoc}
      */
     @Override
@@ -596,6 +601,7 @@ public abstract class Executable extends AccessibleObject
     /**
      * {@inheritDoc}
      */
+    @Override
     public Annotation[] getDeclaredAnnotations()  {
         return AnnotationParser.toArray(declaredAnnotations());
     }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 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
@@ -1132,9 +1132,12 @@ class Field extends AccessibleObject implements Member {
     }
 
     /**
+     * {@inheritDoc}
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.5
      */
+    @Override
     public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
         Objects.requireNonNull(annotationClass);
         return annotationClass.cast(declaredAnnotations().get(annotationClass));
@@ -1142,6 +1145,7 @@ class Field extends AccessibleObject implements Member {
 
     /**
      * {@inheritDoc}
+     *
      * @throws NullPointerException {@inheritDoc}
      * @since 1.8
      */
@@ -1155,6 +1159,7 @@ class Field extends AccessibleObject implements Member {
     /**
      * {@inheritDoc}
      */
+    @Override
     public Annotation[] getDeclaredAnnotations()  {
         return AnnotationParser.toArray(declaredAnnotations());
     }

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

@@ -686,9 +686,10 @@ public final class Method extends Executable {
 
     /**
      * {@inheritDoc}
-     * @throws NullPointerException  {@inheritDoc}
+     * @throws NullPointerException {@inheritDoc}
      * @since 1.5
      */
+    @Override
     public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
         return super.getAnnotation(annotationClass);
     }
@@ -697,6 +698,7 @@ public final class Method extends Executable {
      * {@inheritDoc}
      * @since 1.5
      */
+    @Override
     public Annotation[] getDeclaredAnnotations()  {
         return super.getDeclaredAnnotations();
     }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 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
@@ -377,7 +377,7 @@ public class Modifier {
 
     /**
      * The Java source modifiers that can be applied to a method.
-     * @jls8.4.3  Method Modifiers
+     * @jls 8.4.3  Method Modifiers
      */
     private static final int METHOD_MODIFIERS =
         Modifier.PUBLIC         | Modifier.PROTECTED    | Modifier.PRIVATE |
@@ -400,9 +400,6 @@ public class Modifier {
     private static final int PARAMETER_MODIFIERS =
         Modifier.FINAL;
 
-    /**
-     *
-     */
     static final int ACCESS_MODIFIERS =
         Modifier.PUBLIC | Modifier.PROTECTED | Modifier.PRIVATE;
 

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

@@ -75,6 +75,7 @@ public final class Parameter implements AnnotatedElement {
      * @param obj The object to compare.
      * @return Whether or not this is equal to the argument.
      */
+    @Override
     public boolean equals(Object obj) {
         if(obj instanceof Parameter) {
             Parameter other = (Parameter)obj;
@@ -90,6 +91,7 @@ public final class Parameter implements AnnotatedElement {
      *
      * @return A hash code based on the executable's hash code.
      */
+    @Override
     public int hashCode() {
         return executable.hashCode() ^ index;
     }
@@ -120,6 +122,7 @@ public final class Parameter implements AnnotatedElement {
      * @return A string representation of the parameter and associated
      * information.
      */
+    @Override
     public String toString() {
         final StringBuilder sb = new StringBuilder();
         final Type type = getParameterizedType();
@@ -280,8 +283,11 @@ public final class Parameter implements AnnotatedElement {
 
     /**
      * {@inheritDoc}
+     * <p>Note that any annotation returned by this method is a
+     * declaration annotation.
      * @throws NullPointerException {@inheritDoc}
      */
+    @Override
     public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
         Objects.requireNonNull(annotationClass);
         return annotationClass.cast(declaredAnnotations().get(annotationClass));
@@ -289,6 +295,9 @@ public final class Parameter implements AnnotatedElement {
 
     /**
      * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @throws NullPointerException {@inheritDoc}
      */
     @Override
@@ -300,14 +309,22 @@ public final class Parameter implements AnnotatedElement {
 
     /**
      * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
      */
+    @Override
     public Annotation[] getDeclaredAnnotations() {
         return executable.getParameterAnnotations()[index];
     }
 
     /**
+     * {@inheritDoc}
+     * <p>Note that any annotation returned by this method is a
+     * declaration annotation.
+     *
      * @throws NullPointerException {@inheritDoc}
      */
+    @Override
     public <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass) {
         // Only annotations on classes are inherited, for all other
         // objects getDeclaredAnnotation is the same as
@@ -316,6 +333,10 @@ public final class Parameter implements AnnotatedElement {
     }
 
     /**
+     * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
+     *
      * @throws NullPointerException {@inheritDoc}
      */
     @Override
@@ -328,7 +349,10 @@ public final class Parameter implements AnnotatedElement {
 
     /**
      * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
      */
+    @Override
     public Annotation[] getAnnotations() {
         return getDeclaredAnnotations();
     }

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

@@ -180,6 +180,9 @@ public final class RecordComponent implements AnnotatedElement {
     }
 
     /**
+     * {@inheritDoc}
+     * <p>Note that any annotation returned by this method is a
+     * declaration annotation.
      * @throws NullPointerException {@inheritDoc}
      */
     @Override
@@ -215,6 +218,8 @@ public final class RecordComponent implements AnnotatedElement {
 
     /**
      * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
      */
     @Override
     public Annotation[] getAnnotations() {
@@ -223,6 +228,8 @@ public final class RecordComponent implements AnnotatedElement {
 
     /**
      * {@inheritDoc}
+     * <p>Note that any annotations returned by this method are
+     * declaration annotations.
      */
     @Override
     public Annotation[] getDeclaredAnnotations() { return AnnotationParser.toArray(declaredAnnotations()); }