OpenJDK / amber / amber
changeset 60857:da27f941f86c
8225540: In core reflection note whether returned annotations are declaration or type annotations
Reviewed-by: alanb, prappo
line wrap: on
line diff
--- a/src/java.base/share/classes/java/lang/Class.java Thu Apr 09 16:32:22 2020 -0300 +++ b/src/java.base/share/classes/java/lang/Class.java Thu Apr 09 14:16:17 2020 -0700 @@ -3779,9 +3779,14 @@ } /** + * {@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 @@ } /** + * {@inheritDoc} + * <p>Note that any annotations returned by this method are + * declaration annotations. + * * @throws NullPointerException {@inheritDoc} * @since 1.8 */ @@ -3814,13 +3823,22 @@ } /** + * {@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 @@ } /** + * {@inheritDoc} + * <p>Note that any annotations returned by this method are + * declaration annotations. + * * @throws NullPointerException {@inheritDoc} * @since 1.8 */ @@ -3845,8 +3867,13 @@ } /** + * {@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); }
--- a/src/java.base/share/classes/java/lang/Module.java Thu Apr 09 16:32:22 2020 -0300 +++ b/src/java.base/share/classes/java/lang/Module.java Thu Apr 09 14:16:17 2020 -0700 @@ -1381,6 +1381,9 @@ /** * {@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 @@ /** * {@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 @@ /** * {@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() {
--- a/src/java.base/share/classes/java/lang/Package.java Thu Apr 09 16:32:22 2020 -0300 +++ b/src/java.base/share/classes/java/lang/Package.java Thu Apr 09 14:16:17 2020 -0700 @@ -434,9 +434,14 @@ } /** + * {@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 @@ } /** + * {@inheritDoc} + * <p>Note that any annotations returned by this method are + * declaration annotations. + * * @throws NullPointerException {@inheritDoc} * @since 1.8 */ @@ -461,13 +470,21 @@ } /** + * {@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 @@ } /** + * {@inheritDoc} + * <p>Note that any annotations returned by this method are + * declaration annotations. * @since 1.5 */ + @Override public Annotation[] getDeclaredAnnotations() { return getPackageInfo().getDeclaredAnnotations(); }
--- a/src/java.base/share/classes/java/lang/reflect/AccessibleObject.java Thu Apr 09 16:32:22 2020 -0300 +++ b/src/java.base/share/classes/java/lang/reflect/AccessibleObject.java Thu Apr 09 14:16:17 2020 -0700 @@ -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 @@ 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 @@ } /** + * {@inheritDoc} + * + * <p> Note that any annotations returned by this method are + * declaration annotations. + * * @throws NullPointerException {@inheritDoc} * @since 1.8 */ @@ -536,13 +548,24 @@ } /** + * {@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 @@ } /** + * {@inheritDoc} + * + * <p> Note that any annotations returned by this method are + * declaration annotations. + * * @throws NullPointerException {@inheritDoc} * @since 1.8 */ @@ -567,8 +595,14 @@ } /** + * {@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"); }
--- a/src/java.base/share/classes/java/lang/reflect/AnnotatedElement.java Thu Apr 09 16:32:22 2020 -0300 +++ b/src/java.base/share/classes/java/lang/reflect/AnnotatedElement.java Thu Apr 09 14:16:17 2020 -0700 @@ -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™ 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 @@ * <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 @@ * * 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 @@ * * 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. *
--- a/src/java.base/share/classes/java/lang/reflect/AnnotatedType.java Thu Apr 09 16:32:22 2020 -0300 +++ b/src/java.base/share/classes/java/lang/reflect/AnnotatedType.java Thu Apr 09 14:16:17 2020 -0700 @@ -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 @@ * @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(); }
--- a/src/java.base/share/classes/java/lang/reflect/Constructor.java Thu Apr 09 16:32:22 2020 -0300 +++ b/src/java.base/share/classes/java/lang/reflect/Constructor.java Thu Apr 09 14:16:17 2020 -0700 @@ -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 @@ /** * {@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 @@ * {@inheritDoc} * @since 1.5 */ + @Override public Annotation[] getDeclaredAnnotations() { return super.getDeclaredAnnotations(); }
--- a/src/java.base/share/classes/java/lang/reflect/Executable.java Thu Apr 09 16:32:22 2020 -0300 +++ b/src/java.base/share/classes/java/lang/reflect/Executable.java Thu Apr 09 14:16:17 2020 -0700 @@ -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 @@ * ("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 @@ * {@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 @@ /** * {@inheritDoc} + * * @throws NullPointerException {@inheritDoc} */ @Override @@ -596,6 +601,7 @@ /** * {@inheritDoc} */ + @Override public Annotation[] getDeclaredAnnotations() { return AnnotationParser.toArray(declaredAnnotations()); }
--- a/src/java.base/share/classes/java/lang/reflect/Field.java Thu Apr 09 16:32:22 2020 -0300 +++ b/src/java.base/share/classes/java/lang/reflect/Field.java Thu Apr 09 14:16:17 2020 -0700 @@ -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 @@ } /** + * {@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 @@ /** * {@inheritDoc} + * * @throws NullPointerException {@inheritDoc} * @since 1.8 */ @@ -1155,6 +1159,7 @@ /** * {@inheritDoc} */ + @Override public Annotation[] getDeclaredAnnotations() { return AnnotationParser.toArray(declaredAnnotations()); }
--- a/src/java.base/share/classes/java/lang/reflect/Method.java Thu Apr 09 16:32:22 2020 -0300 +++ b/src/java.base/share/classes/java/lang/reflect/Method.java Thu Apr 09 14:16:17 2020 -0700 @@ -686,9 +686,10 @@ /** * {@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 @@ * {@inheritDoc} * @since 1.5 */ + @Override public Annotation[] getDeclaredAnnotations() { return super.getDeclaredAnnotations(); }
--- a/src/java.base/share/classes/java/lang/reflect/Modifier.java Thu Apr 09 16:32:22 2020 -0300 +++ b/src/java.base/share/classes/java/lang/reflect/Modifier.java Thu Apr 09 14:16:17 2020 -0700 @@ -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 @@ /** * 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 @@ private static final int PARAMETER_MODIFIERS = Modifier.FINAL; - /** - * - */ static final int ACCESS_MODIFIERS = Modifier.PUBLIC | Modifier.PROTECTED | Modifier.PRIVATE;
--- a/src/java.base/share/classes/java/lang/reflect/Parameter.java Thu Apr 09 16:32:22 2020 -0300 +++ b/src/java.base/share/classes/java/lang/reflect/Parameter.java Thu Apr 09 14:16:17 2020 -0700 @@ -75,6 +75,7 @@ * @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 @@ * * @return A hash code based on the executable's hash code. */ + @Override public int hashCode() { return executable.hashCode() ^ index; } @@ -120,6 +122,7 @@ * @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 @@ /** * {@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 @@ /** * {@inheritDoc} + * <p>Note that any annotations returned by this method are + * declaration annotations. + * * @throws NullPointerException {@inheritDoc} */ @Override @@ -300,14 +309,22 @@ /** * {@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 @@ } /** + * {@inheritDoc} + * <p>Note that any annotations returned by this method are + * declaration annotations. + * * @throws NullPointerException {@inheritDoc} */ @Override @@ -328,7 +349,10 @@ /** * {@inheritDoc} + * <p>Note that any annotations returned by this method are + * declaration annotations. */ + @Override public Annotation[] getAnnotations() { return getDeclaredAnnotations(); }
--- a/src/java.base/share/classes/java/lang/reflect/RecordComponent.java Thu Apr 09 16:32:22 2020 -0300 +++ b/src/java.base/share/classes/java/lang/reflect/RecordComponent.java Thu Apr 09 14:16:17 2020 -0700 @@ -180,6 +180,9 @@ } /** + * {@inheritDoc} + * <p>Note that any annotation returned by this method is a + * declaration annotation. * @throws NullPointerException {@inheritDoc} */ @Override @@ -215,6 +218,8 @@ /** * {@inheritDoc} + * <p>Note that any annotations returned by this method are + * declaration annotations. */ @Override public Annotation[] getAnnotations() { @@ -223,6 +228,8 @@ /** * {@inheritDoc} + * <p>Note that any annotations returned by this method are + * declaration annotations. */ @Override public Annotation[] getDeclaredAnnotations() { return AnnotationParser.toArray(declaredAnnotations()); }