Skip to content
Permalink
Browse files

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

…laration or type annotations

Reviewed-by: alanb, prappo
  • Loading branch information
jddarcy committed Apr 9, 2020
1 parent b7d5172 commit 455d2e7cea03424717faf3826221213f30eca26d
@@ -3779,9 +3779,14 @@ private String cannotCastMsg(Object obj) {
}

/**
* {@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 boolean isAnnotationPresent(Class<? extends Annotation> 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 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
*/
@@ -3845,8 +3867,13 @@ public boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)
}

/**
* {@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);
}
@@ -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 @@ private static Module findModule(String target,
/**
* {@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 @@ private static Module findModule(String target,
/**
* {@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() {
@@ -434,9 +434,14 @@ public String toString() {
}

/**
* {@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 boolean isAnnotationPresent(Class<? extends Annotation> 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 boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)
}

/**
* {@inheritDoc}
* <p>Note that any annotations returned by this method are
* declaration annotations.
* @since 1.5
*/
@Override
public Annotation[] getDeclaredAnnotations() {
return getPackageInfo().getDeclaredAnnotations();
}
@@ -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 boolean isAnnotationPresent(Class<? extends Annotation> 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 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
*/
@@ -567,8 +595,14 @@ public boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)
}

/**
* {@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");
}
@@ -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 @@
* <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 boolean isAnnotationPresent(Class<? extends Annotation> 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.
*
@@ -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();
}

0 comments on commit 455d2e7

Please sign in to comment.