--- old/src/share/classes/java/lang/reflect/AnnotatedElement.java 2013-07-11 22:57:50.000000000 -0700 +++ new/src/share/classes/java/lang/reflect/AnnotatedElement.java 2013-07-11 22:57:49.000000000 -0700 @@ -32,49 +32,101 @@ * Represents an annotated element of the program currently running in this * VM. This interface allows annotations to be read reflectively. All * annotations returned by methods in this interface are immutable and - * serializable. It is permissible for the caller to modify the - * arrays returned by accessors for array-valued enum members; it will - * have no affect on 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. * *

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) which was generated at - * compile-time to wrap multiple annotations of the argument type. - * - *

The terms directly present and present are used - * throughout this interface to describe precisely which annotations are - * returned by methods: + * 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. + * + *

The terms directly present, indirectly present, + * present, and associated are used throughout this + * interface to describe precisely which annotations are returned by + * methods: * *

* + *

The table below summarizes which kind of annotation presence + * different methods in this interface examine. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Overview of kind of presence detected by different AnnotatedElement methods
Kind of Presence
MethodDirectly PresentIndirectly PresentPresentAssociated
{@code T}{@link #getAnnotation(Class) getAnnotation(Class<T>)} + * X
{@code Annotation[]}{@link #getAnnotations getAnnotations()} + * X
{@code T[]}{@link #getAnnotationsByType(Class) getAnnotationsByType(Class<T>)} + * X
{@code T}{@link #getDeclaredAnnotation(Class) getDeclaredAnnotation(Class<T>)} + * X
{@code Annotation[]}{@link #getDeclaredAnnotations getDeclaredAnnotations()} + * X
{@code T[]}{@link #getDeclaredAnnotationsByType(Class) getDeclaredAnnotationsByType(Class<T>)} + * XX
+ * + *

For an invocation of {@code get[Declared]AnnotationsByType( Class < + * T >)}, the order of annotations which are directly or indirectly + * present on an element E is computed as if indirectly present + * annotations on E are directly present on E in place + * of their container annotation, in the order in which they appear in + * the value element of the container annotation. + *

If an annotation returned by a method in this interface contains * (directly or indirectly) a {@link Class}-valued member referring to * a class that is not accessible in this VM, attempting to read the class @@ -85,10 +137,11 @@ * a {@link EnumConstantNotPresentException} if the enum constant in the * annotation is no longer present in the enum type. * - *

Attempting to read annotations of a repeatable annotation type T - * that are contained in an annotation whose type is not, in fact, the - * containing annotation type of T, will result in an {@link - * AnnotationFormatError}. + *

If an annotation type T is (meta-)annotated with an + * {@code @Repeatable} annotation whose value element indicates a type + * TC, but TC does not declare a {@code value()} method + * with a return type of T{@code []}, then an exception of type + * {@link java.lang.annotation.AnnotationFormatError} is thrown. * *

Finally, attempting to read a member whose definition has evolved * incompatibly will result in a {@link @@ -106,7 +159,7 @@ public interface AnnotatedElement { /** * Returns true if an annotation for the specified type - * is present on this element, else false. This method + * is present on this element, else false. This method * is designed primarily for convenient access to marker annotations. * *

The truth value returned by this method is equivalent to: @@ -128,7 +181,7 @@ /** * Returns this element's annotation for the specified type if - * such an annotation is present, else null. + * such an annotation is present, else null. * * @param the type of the annotation to query for and return if present * @param annotationClass the Class object corresponding to the @@ -146,6 +199,20 @@ * If there are no annotations present on this element, the return * value is an array of length 0. * + * The caller of this method is free to modify the returned array; it will + * have no effect on the arrays returned to other callers. + * + * @return annotations present on this element + * @since 1.5 + */ + Annotation[] getAnnotations(); + + /** + * Returns annotations that are associated with this element. + * + * If there are no annotations associated with this element, the return + * value is an array of length 0. + * * The difference between this method and {@link #getAnnotation(Class)} * is that this method detects if its argument is a repeatable * annotation type (JLS 9.6), and if so, attempts to find one or @@ -159,65 +226,54 @@ * @param annotationClass the Class object corresponding to the * annotation type * @return all this element's annotations for the specified annotation type if - * present on this element, else an array of length zero + * associated with this element, else an array of length zero * @throws NullPointerException if the given annotation class is null * @since 1.8 */ T[] getAnnotationsByType(Class annotationClass); /** - * Returns annotations that are present on this element. - * - * If there are no annotations present on this element, the return - * value is an array of length 0. - * - * The caller of this method is free to modify the returned array; it will - * have no effect on the arrays returned to other callers. - * - * @return annotations present on this element - * @since 1.5 - */ - Annotation[] getAnnotations(); - - /** * Returns this element's annotation for the specified type if - * such an annotation is present, else null. + * such an annotation is directly present, else null. * * This method ignores inherited annotations. (Returns null if no * annotations are directly present on this element.) * - * @param the type of the annotation to query for and return if present + * @param the type of the annotation to query for and return if directly present * @param annotationClass the Class object corresponding to the * annotation type * @return this element's annotation for the specified annotation type if - * present on this element, else null + * directly present on this element, else null * @throws NullPointerException if the given annotation class is null * @since 1.8 */ T getDeclaredAnnotation(Class annotationClass); /** - * Returns annotations that are directly present on this element. - * This method ignores inherited annotations. - * - * If there are no annotations directly present on this element, - * the return value is an array of length 0. + * Returns this element's annotation(s) for the specified type if + * such annotations are either directly present or + * indirectly present. This method ignores inherited + * annotations. + * + * If there are no specified annotations directly or indirectly + * present on this element, the return value is an array of length + * 0. * * The difference between this method and {@link * #getDeclaredAnnotation(Class)} is that this method detects if its * argument is a repeatable annotation type (JLS 9.6), and if so, * attempts to find one or more annotations of that type by "looking - * through" a container annotation. + * through" a container annotation if one is present. * * The caller of this method is free to modify the returned array; it will * have no effect on the arrays returned to other callers. * * @param the type of the annotation to query for and return - * if directly present + * if directly or indirectly present * @param annotationClass the Class object corresponding to the * annotation type * @return all this element's annotations for the specified annotation type if - * present on this element, else an array of length zero + * directly or indirectly present on this element, else an array of length zero * @throws NullPointerException if the given annotation class is null * @since 1.8 */