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