src/share/classes/java/lang/reflect/AnnotatedElement.java

Print this page

        

*** 41,96 **** * 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. * ! * <p>The terms <em>directly present</em> and <em>present</em> are used ! * throughout this interface to describe precisely which annotations are ! * returned by methods: * * <ul> ! * <li>An annotation A is <em>directly present</em> on an element E if E is ! * associated with a RuntimeVisibleAnnotations or ! * RuntimeVisibleParameterAnnotations attribute, and: * * <ul> - * <li>for an invocation of {@code get[Declared]Annotation(Class<T>)} or - * {@code get[Declared]Annotations()}, the attribute contains A. * ! * <li>for an invocation of {@code get[Declared]AnnotationsByType(Class<T>)}, the ! * attribute either contains A or, if the type of A is repeatable, contains ! * exactly one annotation whose value element contains A and whose type is the ! * containing annotation type of A's type (JLS 9.6). * </ul> * ! * <p> ! * <li>An annotation A is <em>present</em> on an element E if either: * * <ul> - * <li>A is <em>directly present</em> on E; or * ! * <li>A is not <em>directly present</em> on E, and E is a class, and A's type ! * is inheritable (JLS 9.6.3.3), and A is <em>present</em> on the superclass of ! * E. * </ul> * * </ul> * * <p>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 * by calling the relevant Class-returning method on the returned annotation * will result in a {@link TypeNotPresentException}. * * <p>Similarly, attempting to read an enum-valued member will result in * a {@link EnumConstantNotPresentException} if the enum constant in the * annotation is no longer present in the enum type. * ! * <p>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}. * * <p>Finally, attempting to read a member whose definition has evolved * incompatibly will result in a {@link * java.lang.annotation.AnnotationTypeMismatchException} or an * {@link java.lang.annotation.IncompleteAnnotationException}. --- 41,121 ---- * 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. * ! * <p>The terms <em>directly present</em>, <em>directly present</em>, ! * <em>present</em>, and <em>associated</em> are used throughout this ! * interface to describe precisely which annotations are returned by ! * methods: * * <ul> ! * ! * <li> An annotation <i>A</i> is <em>directly present</em> on an ! * element <i>E</i> if <i>E</i> has a {@code ! * RuntimeVisibleAnnotations} or {@code ! * RuntimeVisibleParameterAnnotations} or {@code ! * RuntimeVisibleTypeAnnotations} attribute, and the attribute ! * contains <i>A</i>. ! * ! * <li>An annotation <i>A</i> is <em>indirectly present</em> on an ! * element <i>E</i> if <i>E</i> has a {@code RuntimeVisibleAnnotations} or ! * {@code RuntimeVisibleParameterAnnotations} or {@code RuntimeVisibleTypeAnnotations} ! * attribute, and <i>A</i> 's type is repeatable, and the attribute contains ! * exactly one annotation whose value element contains <i>A</i> and whose ! * type is the containing annotation type of <i>A</i> 's type. ! * ! * <li>An annotation <i>A</i> is present on an element <i>E</i> if either: * * <ul> * ! * <li><i>A</i> is directly present on <i>E</i>; or ! * ! * <li>No annotation of <i>A</i> 's type is directly present on ! * <i>E</i>, and <i>E</i> is a class, and <i>A</i> 's type is ! * inheritable, and <i>A</i> is present on the superclass of <i>E</i>. ! * * </ul> * ! * <li>An annotation <i>A</i> is <em>associated</em> with an element <i>E</i> ! * if either: * * <ul> * ! * <li><i>A</i> is directly or indirectly present on <i>E</i>; or ! * ! * <li>No annotation of <i>A</i> 's type is directly or indirectly ! * present on <i>E</i>, and <i>E</i> is a class, and <i>A</i>'s type ! * is inheritable, and <i>A</i> is associated with the superclass of ! * <i>E</i>. ! * * </ul> * * </ul> * + * For an invocation of {@code get[Declared]AnnotationsByType( Class < + * T >)}, the order of annotations which are directly or indirectly + * present on an element <i>E</i> is computed as if indirectly present + * annotations on <i>E</i> are directly present on <i>E</i> in place + * of their container annotation, in the order in which they appear in + * the value element of the container annotation. + * <p>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 * by calling the relevant Class-returning method on the returned annotation * will result in a {@link TypeNotPresentException}. * * <p>Similarly, attempting to read an enum-valued member will result in * a {@link EnumConstantNotPresentException} if the enum constant in the * annotation is no longer present in the enum type. * ! * <p>If an annotation type <i>T</i> is (meta-)annotated with an ! * {@code @Repeatable} annotation whose value element indicates a type ! * <i>TC</i>, but <i>TC</i> does not declare a {@code value()} method ! * with a return type of <i>T</i>{@code []}, then an exception of type ! * {@link java.lang.annotation.AnnotationFormatError} is thrown. * * <p>Finally, attempting to read a member whose definition has evolved * incompatibly will result in a {@link * java.lang.annotation.AnnotationTypeMismatchException} or an * {@link java.lang.annotation.IncompleteAnnotationException}.
*** 104,114 **** * @author Josh Bloch */ public interface AnnotatedElement { /** * Returns true if an annotation for the specified type ! * is present on this element, else false. This method * is designed primarily for convenient access to marker annotations. * * <p>The truth value returned by this method is equivalent to: * {@code getAnnotation(annotationClass) != null} * --- 129,139 ---- * @author Josh Bloch */ public interface AnnotatedElement { /** * Returns true if an annotation for the specified type ! * is <em>present</em> on this element, else false. This method * is designed primarily for convenient access to marker annotations. * * <p>The truth value returned by this method is equivalent to: * {@code getAnnotation(annotationClass) != null} *
*** 126,136 **** return getAnnotation(annotationClass) != null; } /** * Returns this element's annotation for the specified type if ! * such an annotation is present, else null. * * @param <T> the type of the annotation to query for and return if present * @param annotationClass the Class object corresponding to the * annotation type * @return this element's annotation for the specified annotation type if --- 151,161 ---- return getAnnotation(annotationClass) != null; } /** * Returns this element's annotation for the specified type if ! * such an annotation is <em>present</em>, else null. * * @param <T> the type of the annotation to query for and return if present * @param annotationClass the Class object corresponding to the * annotation type * @return this element's annotation for the specified annotation type if
*** 139,151 **** * @since 1.5 */ <T extends Annotation> T getAnnotation(Class<T> annotationClass); /** ! * Returns annotations that are <em>present</em> on this element. * ! * If there are no annotations <em>present</em> on 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 <em>repeatable * annotation type</em> (JLS 9.6), and if so, attempts to find one or --- 164,176 ---- * @since 1.5 */ <T extends Annotation> T getAnnotation(Class<T> annotationClass); /** ! * Returns annotations that are <em>associated</em> with this element. * ! * If there are no annotations <em>associated</em> 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 <em>repeatable * annotation type</em> (JLS 9.6), and if so, attempts to find one or
*** 157,167 **** * * @param <T> the type of the annotation to query for and return if 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 * @throws NullPointerException if the given annotation class is null * @since 1.8 */ <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass); --- 182,192 ---- * * @param <T> the type of the annotation to query for and return if present * @param annotationClass the Class object corresponding to the * annotation type * @return all this element's annotations for the specified annotation type if ! * associated with this element, else an array of length zero * @throws NullPointerException if the given annotation class is null * @since 1.8 */ <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass);
*** 179,198 **** */ Annotation[] getAnnotations(); /** * Returns this element's annotation for the specified type if ! * such an annotation is present, else null. * * This method ignores inherited annotations. (Returns null if no * annotations are directly present on this element.) * ! * @param <T> the type of the annotation to query for and return if 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 * @throws NullPointerException if the given annotation class is null * @since 1.8 */ <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass); --- 204,223 ---- */ Annotation[] getAnnotations(); /** * Returns this element's annotation for the specified type if ! * such an annotation is <em>directly present</em>, else null. * * This method ignores inherited annotations. (Returns null if no * annotations are directly present on this element.) * ! * @param <T> 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 ! * directly present on this element, else null * @throws NullPointerException if the given annotation class is null * @since 1.8 */ <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass);
*** 215,225 **** * @param <T> the type of the annotation to query for and return * if directly 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 * @throws NullPointerException if the given annotation class is null * @since 1.8 */ <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass); --- 240,250 ---- * @param <T> the type of the annotation to query for and return * if directly present * @param annotationClass the Class object corresponding to the * annotation type * @return all this element's annotations for the specified annotation type if ! * directly present on this element, else an array of length zero * @throws NullPointerException if the given annotation class is null * @since 1.8 */ <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass);