Hello,
Please review the changes to fix
JDK-8225540: In core reflection note whether returned annotations
are declaration or type annotations
http://cr.openjdk.java.net/~darcy/8225540.1/
This is a sibling fix to JDK-8225495 already done over in
javax.lang.model. In brief, the purpose of the change is to make
explicit whether declaration annotations (that is traditional
annotations in the platform since JDK 5.0) or type annotations (added in
JDK 8) are being returned by the various annotation-returning methods.
The distinctions between the two kinds of annotations are discussed in
the cited sections of JLS.
The root interface of types that can return annotations is
AnnotatedElement. Some of the wording developed for JDK-8225495 is
borrowed and repurposed as a general explanation in AnnotatedElement.
The implementation specification of the default method for
AnnotatedElement.isAnnotationPresetn is pull out to properly use an
@implSpec tag. The AnnotatedType interface and its subinterfaces return
type annotations; the other class and interfaces return declaration
annotations.
For AnnotatedType, the three methods on AnnotatedElement that do *not*
have default methods are overriden for the sole purpose of adding a note
stating any return annotations are *type* annotations. The specs of the
default methods rely on the behavior of the non-default methods so this
implicitly implies the results of the other methods are type annotations
too.
Since there is no common superclass of the various classes which can
return declaration annotations, analogous notes are spread through many
classes including
* java.lang.Class
* java.lang.Package
* java.lang.Module
* java.reflect.{AccessibleObject, Executable, Constructor, Method,
Field, Parameter, RecordComponent}
These classes are also updated to use @Override consistently for the
annotation-related methods; @Override couldn't initially be used on
interface methods implemented by a class.
The Executable.getParameterAnnotations method also get a note to state
it returns declaration annotations.
I'll update copyright and reflow paragraphs before pushing.
Thanks,
-Joe
