AnnotatedConstruct.java revision 3936:ec4be8a26914
125164Speter/* 225164Speter * Copyright (c) 2013, 2017, Oracle and/or its affiliates. All rights reserved. 325164Speter * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 425164Speter * 525164Speter * This code is free software; you can redistribute it and/or modify it 625164Speter * under the terms of the GNU General Public License version 2 only, as 725164Speter * published by the Free Software Foundation. Oracle designates this 825164Speter * particular file as subject to the "Classpath" exception as provided 925164Speter * by Oracle in the LICENSE file that accompanied this code. 1025164Speter * 1125164Speter * This code is distributed in the hope that it will be useful, but WITHOUT 1225164Speter * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1325164Speter * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1425164Speter * version 2 for more details (a copy is included in the LICENSE file that 1525164Speter * accompanied this code). 1625164Speter * 1725164Speter * You should have received a copy of the GNU General Public License version 1825164Speter * 2 along with this work; if not, write to the Free Software Foundation, 1925164Speter * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2025164Speter * 2125164Speter * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2225164Speter * or visit www.oracle.com if you need additional information or have any 2325164Speter * questions. 2425164Speter */ 2526108Sfsmp 2625164Speterpackage javax.lang.model; 2725164Speter 2825164Speterimport java.lang.annotation.*; 2925164Speterimport java.util.List; 3025164Speterimport javax.lang.model.element.*; 3125164Speterimport javax.lang.model.type.*; 3225164Speter 3325164Speter/** 3425164Speter * Represents a construct that can be annotated. 3525164Speter * 3625164Speter * A construct is either an {@linkplain 3725164Speter * javax.lang.model.element.Element element} or a {@linkplain 3825164Speter * javax.lang.model.type.TypeMirror type}. Annotations on an element 3925164Speter * are on a <em>declaration</em>, whereas annotations on a type are on 4025164Speter * a specific <em>use</em> of a type name. 4125164Speter * 4225164Speter * The terms <em>directly present</em>, <em>present</em>, 4325164Speter * <em>indirectly present</em>, and <em>associated </em> are used 4425164Speter * throughout this interface to describe precisely which annotations 4525164Speter * are returned by the methods defined herein. 4625164Speter * 4725216Sfsmp * <p>In the definitions below, an annotation <i>A</i> has an 4825164Speter * annotation type <i>AT</i>. If <i>AT</i> is a repeatable annotation 4925164Speter * type, the type of the containing annotation is <i>ATC</i>. 5025164Speter * 5125215Sfsmp * <p>Annotation <i>A</i> is <em>directly present</em> on a construct 5225215Sfsmp * <i>C</i> if either: 5325215Sfsmp * 5425215Sfsmp * <ul> 5525215Sfsmp * 5625164Speter * <li><i>A</i> is explicitly or implicitly declared as applying to 5725164Speter * the source code representation of <i>C</i>. 5825164Speter * 5925164Speter * <p>Typically, if exactly one annotation of type <i>AT</i> appears in 6025164Speter * the source code of representation of <i>C</i>, then <i>A</i> is 6125164Speter * explicitly declared as applying to <i>C</i>. 6225164Speter * 6325164Speter * If there are multiple annotations of type <i>AT</i> present on 6425164Speter * <i>C</i>, then if <i>AT</i> is repeatable annotation type, an 6525164Speter * annotation of type <i>ATC</i> is {@linkplain javax.lang.model.util.Elements#getOrigin(AnnotatedConstruct, AnnotationMirror) implicitly declared} on <i>C</i>. 6625164Speter * 6725164Speter * <li> A representation of <i>A</i> appears in the executable output 6825164Speter * for <i>C</i>, such as the {@code RuntimeVisibleAnnotations} or 6925164Speter * {@code RuntimeVisibleParameterAnnotations} attributes of a class 7025164Speter * file. 7125164Speter * 7225164Speter * </ul> 7325164Speter * 7425164Speter * <p>An annotation <i>A</i> is <em>present</em> on a 7525164Speter * construct <i>C</i> if either: 7625164Speter * <ul> 7725164Speter * 7825164Speter * <li><i>A</i> is directly present on <i>C</i>. 7925164Speter * 8025164Speter * <li>No annotation of type <i>AT</i> is directly present on 8125164Speter * <i>C</i>, and <i>C</i> is a class and <i>AT</i> is inheritable 8225164Speter * and <i>A</i> is present on the superclass of <i>C</i>. 8325164Speter * 8425164Speter * </ul> 8525164Speter * 8625164Speter * An annotation <i>A</i> is <em>indirectly present</em> on a construct 8725164Speter * <i>C</i> if both: 8825164Speter * 8925164Speter * <ul> 9025164Speter * 9125164Speter * <li><i>AT</i> is a repeatable annotation type with a containing 9225164Speter * annotation type <i>ATC</i>. 9325164Speter * 9425164Speter * <li>An annotation of type <i>ATC</i> is directly present on 9525164Speter * <i>C</i> and <i>A</i> is an annotation included in the result of 9625164Speter * calling the {@code value} method of the directly present annotation 9725164Speter * of type <i>ATC</i>. 9825164Speter * 9925164Speter * </ul> 10025164Speter * 10125164Speter * An annotation <i>A</i> is <em>associated</em> with a construct 10225164Speter * <i>C</i> if either: 10325164Speter * 10425164Speter * <ul> 10525164Speter * 10625164Speter * <li> <i>A</i> is directly or indirectly present on <i>C</i>. 10725164Speter * 10825164Speter * <li> No annotation of type <i>AT</i> is directly or indirectly 10925164Speter * present on <i>C</i>, and <i>C</i> is a class, and <i>AT</i> is 11025164Speter * inheritable, and <i>A</i> is associated with the superclass of 11125164Speter * <i>C</i>. 11225164Speter * 11325164Speter * </ul> 11425164Speter * 11525164Speter * @since 1.8 11625164Speter * @jls 9.6 Annotation Types 11725164Speter * @jls 9.6.3.3 @Inherited 11825164Speter */ 11925164Speterpublic interface AnnotatedConstruct { 12025164Speter /** 12125164Speter * Returns the annotations that are <em>directly present</em> on 12225164Speter * this construct. 12326108Sfsmp * 12425164Speter * @return the annotations <em>directly present</em> on this 12525164Speter * construct; an empty list if there are none 12625164Speter */ 12725164Speter List<? extends AnnotationMirror> getAnnotationMirrors(); 12825164Speter 12926108Sfsmp /** 13026108Sfsmp * Returns this construct's annotation of the specified type if 13125164Speter * such an annotation is <em>present</em>, else {@code null}. 13226108Sfsmp * 13326108Sfsmp * <p> The annotation returned by this method could contain an element 13425164Speter * whose value is of type {@code Class}. 13525164Speter * This value cannot be returned directly: information necessary to 13625164Speter * locate and load a class (such as the class loader to use) is 13725164Speter * not available, and the class might not be loadable at all. 13825164Speter * Attempting to read a {@code Class} object by invoking the relevant 13925164Speter * method on the returned annotation 14025164Speter * will result in a {@link MirroredTypeException}, 14125164Speter * from which the corresponding {@link TypeMirror} may be extracted. 14225164Speter * Similarly, attempting to read a {@code Class[]}-valued element 14325164Speter * will result in a {@link MirroredTypesException}. 14425164Speter * 14525164Speter * <blockquote> 14625164Speter * <i>Note:</i> This method is unlike others in this and related 14725164Speter * interfaces. It operates on runtime reflective information — 14825164Speter * representations of annotation types currently loaded into the 14925164Speter * VM — rather than on the representations defined by and used 15025164Speter * throughout these interfaces. Consequently, calling methods on 15125164Speter * the returned annotation object can throw many of the exceptions 15225164Speter * that can be thrown when calling methods on an annotation object 15325164Speter * returned by core reflection. This method is intended for 15425164Speter * callers that are written to operate on a known, fixed set of 15525164Speter * annotation types. 15625164Speter * </blockquote> 15725164Speter * 15825164Speter * @param <A> the annotation type 15925164Speter * @param annotationType the {@code Class} object corresponding to 16025164Speter * the annotation type 16125164Speter * @return this construct's annotation for the specified 16225164Speter * annotation type if present, else {@code null} 16325164Speter * 16425164Speter * @see #getAnnotationMirrors() 16525164Speter * @see java.lang.reflect.AnnotatedElement#getAnnotation 16625164Speter * @see EnumConstantNotPresentException 16725164Speter * @see AnnotationTypeMismatchException 16825164Speter * @see IncompleteAnnotationException 16925164Speter * @see MirroredTypeException 17025164Speter * @see MirroredTypesException 17125164Speter * @jls 9.6.1 Annotation Type Elements 17225164Speter */ 17325164Speter <A extends Annotation> A getAnnotation(Class<A> annotationType); 17426108Sfsmp 17526108Sfsmp /** 17626108Sfsmp * Returns annotations that are <em>associated</em> with this construct. 17726108Sfsmp * 17826108Sfsmp * If there are no annotations associated with this construct, the 17926108Sfsmp * return value is an array of length 0. 18026108Sfsmp * 18126108Sfsmp * The order of annotations which are directly or indirectly 18226108Sfsmp * present on a construct <i>C</i> is computed as if indirectly present 18325164Speter * annotations on <i>C</i> are directly present on <i>C</i> in place of their 18426101Sfsmp * container annotation, in the order in which they appear in the 18526108Sfsmp * value element of the container annotation. 18625164Speter * 18725164Speter * The difference between this method and {@link #getAnnotation(Class)} 18825164Speter * is that this method detects if its argument is a <em>repeatable 18925164Speter * annotation type</em>, and if so, attempts to find one or more 19025164Speter * annotations of that type by "looking through" a container annotation. 19125164Speter * 19225164Speter * <p> The annotations returned by this method could contain an element 19325164Speter * whose value is of type {@code Class}. 19425164Speter * This value cannot be returned directly: information necessary to 19525164Speter * locate and load a class (such as the class loader to use) is 19625164Speter * not available, and the class might not be loadable at all. 19725164Speter * Attempting to read a {@code Class} object by invoking the relevant 19825164Speter * method on the returned annotation 19925164Speter * will result in a {@link MirroredTypeException}, 20025164Speter * from which the corresponding {@link TypeMirror} may be extracted. 20125164Speter * Similarly, attempting to read a {@code Class[]}-valued element 20225164Speter * will result in a {@link MirroredTypesException}. 20325164Speter * 20425164Speter * <blockquote> 20525164Speter * <i>Note:</i> This method is unlike others in this and related 20625164Speter * interfaces. It operates on runtime reflective information — 20725164Speter * representations of annotation types currently loaded into the 20825164Speter * VM — rather than on the representations defined by and used 20925164Speter * throughout these interfaces. Consequently, calling methods on 21025164Speter * the returned annotation object can throw many of the exceptions 21125164Speter * that can be thrown when calling methods on an annotation object 21225164Speter * returned by core reflection. This method is intended for 21325164Speter * callers that are written to operate on a known, fixed set of 21425164Speter * annotation types. 21525164Speter * </blockquote> 21625164Speter * 21725164Speter * @param <A> the annotation type 21825164Speter * @param annotationType the {@code Class} object corresponding to 21925164Speter * the annotation type 22025164Speter * @return this construct's annotations for the specified annotation 22125164Speter * type if present on this construct, else an empty array 22225164Speter * 22325164Speter * @see #getAnnotationMirrors() 22425164Speter * @see #getAnnotation(Class) 22525164Speter * @see java.lang.reflect.AnnotatedElement#getAnnotationsByType(Class) 22625164Speter * @see EnumConstantNotPresentException 22725164Speter * @see AnnotationTypeMismatchException 22825164Speter * @see IncompleteAnnotationException 22925164Speter * @see MirroredTypeException 23025164Speter * @see MirroredTypesException 23125164Speter * @jls 9.6 Annotation Types 23225164Speter * @jls 9.6.1 Annotation Type Elements 23325164Speter */ 23425164Speter <A extends Annotation> A[] getAnnotationsByType(Class<A> annotationType); 23525164Speter} 23625164Speter