1 /* 2 * Copyright (c) 2013, 2020, 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>, <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 the methods defined herein. 46 * 47 * <p>In the definitions below, an annotation <i>A</i> has an 48 * annotation type <i>AT</i>. If <i>AT</i> is a repeatable annotation 49 * type, the type of the containing annotation is <i>ATC</i>. 50 * 51 * <p>Annotation <i>A</i> is <em>directly present</em> on a construct 52 * <i>C</i> if either: 53 * 54 * <ul> 55 * 56 * <li><i>A</i> is explicitly or implicitly declared as applying to 57 * the source code representation of <i>C</i>. 58 * 59 * <p>Typically, if exactly one annotation of type <i>AT</i> appears in 60 * the source code of representation of <i>C</i>, then <i>A</i> is 61 * explicitly declared as applying to <i>C</i>. 62 * 63 * An annotation of type <i>AT</i> on a {@linkplain 64 * RecordComponentElement record component} can be implicitly propagated 65 * down to affiliated mandated members. Type annotations modifying the 66 * type of a record component can be also propagated to mandated 67 * members. Propagation of the annotations to mandated members is 68 * governed by rules given in the <cite>The Java™ Language 69 * Specification</cite>. 70 * 71 * If there are multiple annotations of type <i>AT</i> present on 72 * <i>C</i>, then if <i>AT</i> is repeatable annotation type, an 73 * annotation of type <i>ATC</i> is {@linkplain javax.lang.model.util.Elements#getOrigin(AnnotatedConstruct, AnnotationMirror) implicitly declared} on <i>C</i>. 74 * <li> A representation of <i>A</i> appears in the executable output 75 * for <i>C</i>, such as the {@code RuntimeVisibleAnnotations} or 76 * {@code RuntimeVisibleParameterAnnotations} attributes of a class 77 * file. 78 * 79 * </ul> 80 * 81 * <p>An annotation <i>A</i> is <em>present</em> on a 82 * construct <i>C</i> if either: 83 * <ul> 84 * 85 * <li><i>A</i> is directly present on <i>C</i>. 86 * 87 * <li>No annotation of type <i>AT</i> is directly present on 88 * <i>C</i>, and <i>C</i> is a class and <i>AT</i> is inheritable 89 * and <i>A</i> is present on the superclass of <i>C</i>. 90 * 91 * </ul> 92 * 93 * An annotation <i>A</i> is <em>indirectly present</em> on a construct 94 * <i>C</i> if both: 95 * 96 * <ul> 97 * 98 * <li><i>AT</i> is a repeatable annotation type with a containing 99 * annotation type <i>ATC</i>. 100 * 101 * <li>An annotation of type <i>ATC</i> is directly present on 102 * <i>C</i> and <i>A</i> is an annotation included in the result of 103 * calling the {@code value} method of the directly present annotation 104 * of type <i>ATC</i>. 105 * 106 * </ul> 107 * 108 * An annotation <i>A</i> is <em>associated</em> with a construct 109 * <i>C</i> if either: 110 * 111 * <ul> 112 * 113 * <li> <i>A</i> is directly or indirectly present on <i>C</i>. 114 * 115 * <li> No annotation of type <i>AT</i> is directly or indirectly 116 * present on <i>C</i>, and <i>C</i> is a class, and <i>AT</i> is 117 * inheritable, and <i>A</i> is associated with the superclass of 118 * <i>C</i>. 119 * 120 * </ul> 121 * 122 * @since 1.8 123 * @jls 9.6 Annotation Types 124 * @jls 9.6.4.3 {@code @Inherited} 125 */ 126 public interface AnnotatedConstruct { 127 /** 128 * Returns the annotations that are <em>directly present</em> on 129 * this construct. 130 * 131 * @return the annotations <em>directly present</em> on this 132 * construct; an empty list if there are none 133 */ 134 List<? extends AnnotationMirror> getAnnotationMirrors(); 135 136 /** 137 * Returns this construct's annotation of the specified type if 138 * such an annotation is <em>present</em>, else {@code null}. 139 * 140 * <p> The annotation returned by this method could contain an element 141 * whose value is of type {@code Class}. 142 * This value cannot be returned directly: information necessary to 143 * locate and load a class (such as the class loader to use) is 144 * not available, and the class might not be loadable at all. 145 * Attempting to read a {@code Class} object by invoking the relevant 146 * method on the returned annotation 147 * will result in a {@link MirroredTypeException}, 148 * from which the corresponding {@link TypeMirror} may be extracted. 149 * Similarly, attempting to read a {@code Class[]}-valued element 150 * will result in a {@link MirroredTypesException}. 151 * 152 * <blockquote> 153 * <i>Note:</i> This method is unlike others in this and related 154 * interfaces. It operates on runtime reflective information — 155 * representations of annotation types currently loaded into the 156 * VM — rather than on the representations defined by and used 157 * throughout these interfaces. Consequently, calling methods on 158 * the returned annotation object can throw many of the exceptions 159 * that can be thrown when calling methods on an annotation object 160 * returned by core reflection. This method is intended for 161 * callers that are written to operate on a known, fixed set of 162 * annotation types. 163 * </blockquote> 164 * 165 * @param <A> the annotation type 166 * @param annotationType the {@code Class} object corresponding to 167 * the annotation type 168 * @return this construct's annotation for the specified 169 * annotation type if present, else {@code null} 170 * 171 * @see #getAnnotationMirrors() 172 * @see java.lang.reflect.AnnotatedElement#getAnnotation 173 * @see EnumConstantNotPresentException 174 * @see AnnotationTypeMismatchException 175 * @see IncompleteAnnotationException 176 * @see MirroredTypeException 177 * @see MirroredTypesException 178 * @jls 9.6.1 Annotation Type Elements 179 */ 180 <A extends Annotation> A getAnnotation(Class<A> annotationType); 181 182 /** 183 * Returns annotations that are <em>associated</em> with this construct. 184 * 185 * If there are no annotations associated with this construct, the 186 * return value is an array of length 0. 187 * 188 * The order of annotations which are directly or indirectly 189 * present on a construct <i>C</i> is computed as if indirectly present 190 * annotations on <i>C</i> are directly present on <i>C</i> in place of their 191 * container annotation, in the order in which they appear in the 192 * value element of the container annotation. 193 * 194 * The difference between this method and {@link #getAnnotation(Class)} 195 * is that this method detects if its argument is a <em>repeatable 196 * annotation type</em>, and if so, attempts to find one or more 197 * annotations of that type by "looking through" a container annotation. 198 * 199 * <p> The annotations returned by this method could contain an element 200 * whose value is of type {@code Class}. 201 * This value cannot be returned directly: information necessary to 202 * locate and load a class (such as the class loader to use) is 203 * not available, and the class might not be loadable at all. 204 * Attempting to read a {@code Class} object by invoking the relevant 205 * method on the returned annotation 206 * will result in a {@link MirroredTypeException}, 207 * from which the corresponding {@link TypeMirror} may be extracted. 208 * Similarly, attempting to read a {@code Class[]}-valued element 209 * will result in a {@link MirroredTypesException}. 210 * 211 * <blockquote> 212 * <i>Note:</i> This method is unlike others in this and related 213 * interfaces. It operates on runtime reflective information — 214 * representations of annotation types currently loaded into the 215 * VM — rather than on the representations defined by and used 216 * throughout these interfaces. Consequently, calling methods on 217 * the returned annotation object can throw many of the exceptions 218 * that can be thrown when calling methods on an annotation object 219 * returned by core reflection. This method is intended for 220 * callers that are written to operate on a known, fixed set of 221 * annotation types. 222 * </blockquote> 223 * 224 * @param <A> the annotation type 225 * @param annotationType the {@code Class} object corresponding to 226 * the annotation type 227 * @return this construct's annotations for the specified annotation 228 * type if present on this construct, else an empty array 229 * 230 * @see #getAnnotationMirrors() 231 * @see #getAnnotation(Class) 232 * @see java.lang.reflect.AnnotatedElement#getAnnotationsByType(Class) 233 * @see EnumConstantNotPresentException 234 * @see AnnotationTypeMismatchException 235 * @see IncompleteAnnotationException 236 * @see MirroredTypeException 237 * @see MirroredTypesException 238 * @jls 9.6 Annotation Types 239 * @jls 9.6.1 Annotation Type Elements 240 */ 241 <A extends Annotation> A[] getAnnotationsByType(Class<A> annotationType); 242 }