src/share/classes/javax/lang/model/AnnotatedConstruct.java

Print this page




  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.lang.model;
  27 
  28 import java.lang.annotation.*;
  29 import java.util.List;
  30 import javax.lang.model.element.*;
  31 import javax.lang.model.type.*;
  32 
  33 /**
  34  * Represents a construct that can be annotated.
  35  *
  36  * A construct is either an {@linkplain
  37  * javax.lang.model.element.Element element} or a {@linkplain
  38  * javax.lang.model.type.TypeMirror type}.  Annotations on an element
  39  * are on a <em>declaration</em>, whereas annotations on a type are on
  40  * a specific <em>use</em> of a type name.
  41  *
  42  * The terms <em>directly present</em> and <em>present</em> are used

  43  * throughout this interface to describe precisely which annotations
  44  * are returned by methods:
  45  *
  46  * <p>An annotation <i>A</i> is <em>directly present</em> on a
  47  * construct <i>E</i> if <i>E</i> is annotated, and:






























  48  *
  49  * <ul>
  50  *
  51  * <li> for an invocation of {@code getAnnotation(Class<T>)} or
  52  * {@code getAnnotationMirrors()}, <i>E</i>'s annotations contain <i>A</i>.
  53  *
  54  * <li> for an invocation of getAnnotationsByType(Class<T>),
  55  * <i>E</i>'s annotations either contain <i>A</i> or, if the type of
  56  * <i>A</i> is repeatable, contain exactly one annotation whose value
  57  * element contains <i>A</i> and whose type is the containing
  58  * annotation type of <i>A</i>'s type.
  59  *
  60  * </ul>
  61  *
  62  * <p>An annotation A is <em>present</em> on a construct E if either:

  63  *
  64  * <ul>
  65  *  <li> <i>A</i> is <em>directly present</em> on <i>E</i>; or
  66  *
  67  *  <li> <i>A</i> is not <em>directly present</em> on <i>E</i>, and
  68  *  <i>E</i> is an element representing a class, and <i>A</i>'s type
  69  *  is inheritable, and <i>A</i> is <em>present</em> on the element
  70  *  representing the superclass of <i>E</i>.
  71  *




  72  * </ul>
  73  *
  74  * @since 1.8
  75  * @jls 9.6 Annotation Types
  76  * @jls 9.6.3.3 @Inherited
  77  */
  78 public interface AnnotatedConstruct {
  79     /**
  80      * Returns the annotations that are <em>directly present</em> on
  81      * this construct.
  82      *
  83      * @return the annotations <em>directly present</em> on this
  84      * construct; an empty list if there are none
  85      */
  86     List<? extends AnnotationMirror> getAnnotationMirrors();
  87 
  88     /**
  89      * Returns this construct's annotation of the
  90      * specified type if such an annotation is <em>present</em>, else {@code
  91      * null}.


 117      *
 118      * @param <A>  the annotation type
 119      * @param annotationType  the {@code Class} object corresponding to
 120      *          the annotation type
 121      * @return this element's or type use's annotation for the
 122      * specified annotation type if present on this element, else
 123      * {@code null}
 124      *
 125      * @see #getAnnotationMirrors()
 126      * @see java.lang.reflect.AnnotatedElement#getAnnotation
 127      * @see EnumConstantNotPresentException
 128      * @see AnnotationTypeMismatchException
 129      * @see IncompleteAnnotationException
 130      * @see MirroredTypeException
 131      * @see MirroredTypesException
 132      * @jls 9.6.1 Annotation Type Elements
 133      */
 134     <A extends Annotation> A getAnnotation(Class<A> annotationType);
 135 
 136     /**
 137      * Returns annotations that are <em>present</em> on this construct.
 138      *
 139      * If there are no annotations <em>present</em> on this construct,
 140      * the return value is an array of length 0.
 141      *
 142      * The difference between this method and {@link #getAnnotation(Class)}
 143      * is that this method detects if its argument is a <em>repeatable
 144      * annotation type</em>, and if so, attempts to find one or more
 145      * annotations of that type by "looking through" a container annotation.
 146      *
 147      * <p> The annotations returned by this method could contain an element
 148      * whose value is of type {@code Class}.
 149      * This value cannot be returned directly:  information necessary to
 150      * locate and load a class (such as the class loader to use) is
 151      * not available, and the class might not be loadable at all.
 152      * Attempting to read a {@code Class} object by invoking the relevant
 153      * method on the returned annotation
 154      * will result in a {@link MirroredTypeException},
 155      * from which the corresponding {@link TypeMirror} may be extracted.
 156      * Similarly, attempting to read a {@code Class[]}-valued element
 157      * will result in a {@link MirroredTypesException}.
 158      *
 159      * <blockquote>
 160      * <i>Note:</i> This method is unlike others in this and related




  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.lang.model;
  27 
  28 import java.lang.annotation.*;
  29 import java.util.List;
  30 import javax.lang.model.element.*;
  31 import javax.lang.model.type.*;
  32 
  33 /**
  34  * Represents a construct that can be annotated.
  35  *
  36  * A construct is either an {@linkplain
  37  * javax.lang.model.element.Element element} or a {@linkplain
  38  * javax.lang.model.type.TypeMirror type}.  Annotations on an element
  39  * are on a <em>declaration</em>, whereas annotations on a type are on
  40  * a specific <em>use</em> of a type name.
  41  *
  42  * The terms <em>directly present</em>, <em>present</em>,
  43  * <em>indirectly present</em>, and <em>associated </em> are used
  44  * throughout this interface to describe precisely which annotations
  45  * are returned by its methods.
  46  *
  47  * <p>An annotation <i>A</i> is <em>directly present</em> on a
  48  * construct <i>E</i> if either:
  49  * <ul>
  50  *
  51  * <li><i>A</i> appears exactly once in the source code representation
  52  * for <i>E</i>.
  53  *
  54  * <li><i>A</i> is the container annotation for a repeatable
  55  * annotation type <i>R</i> and the source code for <i>E</i> has
  56  * multiple annotations of type <i>R</i>.
  57  *
  58  * <li> A representation of <i>A</i> appears in the executable output
  59  * for <i>E</i>, such as the {@code RuntimeVisibleAnnotations} or
  60  * {@code RuntimeVisibleParameterAnnotations} attributes of a class
  61  * file.
  62  *
  63  * </ul>
  64  *
  65  * <p>An annotation <i>A</i> is <em>present</em> on a
  66  * construct <i>E</i> if either:
  67  * <ul>
  68  *
  69  * <li><i>A</i> is directly present on <i>E</i>.
  70  *
  71  * <li>No annotation of <i>A</i>'s type is directly present on
  72  * <i>E</i>, and <i>E</i> is a class and <i>A</i>'s type is inheritable
  73  * and <i>A</i> is present on the superclass of <i>E</i>.
  74  *
  75  * </ul>
  76  *
  77  * An annotation <i>A</i> is <em>indirectly present</em> on an element
  78  * <i>E</i> if:
  79  *
  80  * <ul>
  81  *
  82  * <li> <i>A</i>'s type is repeatable with a containing annotation type <i>C</i>

  83  *
  84  * <li> An annotation of type <i>C</i> is directly present on <i>E</i>.




  85  *
  86  * </ul>
  87  *
  88  * An annotation <i>A</i> is <em>associated</em> with an element
  89  * <i>E</i> if either:
  90  * 
  91  * <ul>

  92  *
  93  * <li> <i>A</i> is directly or indirectly present on <i>E</i>.



  94  *
  95  * <li> No annotation of <i>A</i>'s type is directly or indirectly
  96  * present on <i>E</i>, <i>E</i> is a class, and <i>A</i>'s type is
  97  * inheritable, and <i>A</i> is associated with the superclass of
  98  * <i>E</i>.
  99  * </ul>
 100  *
 101  * @since 1.8
 102  * @jls 9.6 Annotation Types
 103  * @jls 9.6.3.3 @Inherited
 104  */
 105 public interface AnnotatedConstruct {
 106     /**
 107      * Returns the annotations that are <em>directly present</em> on
 108      * this construct.
 109      *
 110      * @return the annotations <em>directly present</em> on this
 111      * construct; an empty list if there are none
 112      */
 113     List<? extends AnnotationMirror> getAnnotationMirrors();
 114 
 115     /**
 116      * Returns this construct's annotation of the
 117      * specified type if such an annotation is <em>present</em>, else {@code
 118      * null}.


 144      *
 145      * @param <A>  the annotation type
 146      * @param annotationType  the {@code Class} object corresponding to
 147      *          the annotation type
 148      * @return this element's or type use's annotation for the
 149      * specified annotation type if present on this element, else
 150      * {@code null}
 151      *
 152      * @see #getAnnotationMirrors()
 153      * @see java.lang.reflect.AnnotatedElement#getAnnotation
 154      * @see EnumConstantNotPresentException
 155      * @see AnnotationTypeMismatchException
 156      * @see IncompleteAnnotationException
 157      * @see MirroredTypeException
 158      * @see MirroredTypesException
 159      * @jls 9.6.1 Annotation Type Elements
 160      */
 161     <A extends Annotation> A getAnnotation(Class<A> annotationType);
 162 
 163     /**
 164      * Returns annotations that are <em>associated</em> with this construct.
 165      *
 166      * If there are no annotations associated with this construct, the
 167      * return value is an array of length 0.
 168      *
 169      * The difference between this method and {@link #getAnnotation(Class)}
 170      * is that this method detects if its argument is a <em>repeatable
 171      * annotation type</em>, and if so, attempts to find one or more
 172      * annotations of that type by "looking through" a container annotation.
 173      *
 174      * <p> The annotations returned by this method could contain an element
 175      * whose value is of type {@code Class}.
 176      * This value cannot be returned directly:  information necessary to
 177      * locate and load a class (such as the class loader to use) is
 178      * not available, and the class might not be loadable at all.
 179      * Attempting to read a {@code Class} object by invoking the relevant
 180      * method on the returned annotation
 181      * will result in a {@link MirroredTypeException},
 182      * from which the corresponding {@link TypeMirror} may be extracted.
 183      * Similarly, attempting to read a {@code Class[]}-valued element
 184      * will result in a {@link MirroredTypesException}.
 185      *
 186      * <blockquote>
 187      * <i>Note:</i> This method is unlike others in this and related