1 /*
   2  * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  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 {@code 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}.
  92      *
  93      * <p> The annotation returned by this method could contain an element
  94      * whose value is of type {@code Class}.
  95      * This value cannot be returned directly:  information necessary to
  96      * locate and load a class (such as the class loader to use) is
  97      * not available, and the class might not be loadable at all.
  98      * Attempting to read a {@code Class} object by invoking the relevant
  99      * method on the returned annotation
 100      * will result in a {@link MirroredTypeException},
 101      * from which the corresponding {@link TypeMirror} may be extracted.
 102      * Similarly, attempting to read a {@code Class[]}-valued element
 103      * will result in a {@link MirroredTypesException}.
 104      *
 105      * <blockquote>
 106      * <i>Note:</i> This method is unlike others in this and related
 107      * interfaces.  It operates on runtime reflective information &mdash;
 108      * representations of annotation types currently loaded into the
 109      * VM &mdash; rather than on the representations defined by and used
 110      * throughout these interfaces.  Consequently, calling methods on
 111      * the returned annotation object can throw many of the exceptions
 112      * that can be thrown when calling methods on an annotation object
 113      * returned by core reflection.  This method is intended for
 114      * callers that are written to operate on a known, fixed set of
 115      * annotation types.
 116      * </blockquote>
 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
 161      * interfaces.  It operates on runtime reflective information &mdash;
 162      * representations of annotation types currently loaded into the
 163      * VM &mdash; rather than on the representations defined by and used
 164      * throughout these interfaces.  Consequently, calling methods on
 165      * the returned annotation object can throw many of the exceptions
 166      * that can be thrown when calling methods on an annotation object
 167      * returned by core reflection.  This method is intended for
 168      * callers that are written to operate on a known, fixed set of
 169      * annotation types.
 170      * </blockquote>
 171      *
 172      * @param <A>  the annotation type
 173      * @param annotationType  the {@code Class} object corresponding to
 174      *          the annotation type
 175      * @return this element's annotations for the specified annotation
 176      *         type if present on this element, else an empty array
 177      *
 178      * @see #getAnnotationMirrors()
 179      * @see #getAnnotation(java.lang.Class)
 180      * @see java.lang.reflect.AnnotatedElement#getAnnotationsByType
 181      * @see EnumConstantNotPresentException
 182      * @see AnnotationTypeMismatchException
 183      * @see IncompleteAnnotationException
 184      * @see MirroredTypeException
 185      * @see MirroredTypesException
 186      * @jls 9.6 Annotation Types
 187      * @jls 9.6.1 Annotation Type Elements
 188      */
 189     <A extends Annotation> A[] getAnnotationsByType(Class<A> annotationType);
 190 }