AnnotationValueVisitor.java revision 3895:4a937fde7b91
1221828Sgrehan/* 2221828Sgrehan * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved. 3221828Sgrehan * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4221828Sgrehan * 5221828Sgrehan * This code is free software; you can redistribute it and/or modify it 6221828Sgrehan * under the terms of the GNU General Public License version 2 only, as 7221828Sgrehan * published by the Free Software Foundation. Oracle designates this 8221828Sgrehan * particular file as subject to the "Classpath" exception as provided 9221828Sgrehan * by Oracle in the LICENSE file that accompanied this code. 10221828Sgrehan * 11221828Sgrehan * This code is distributed in the hope that it will be useful, but WITHOUT 12221828Sgrehan * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13221828Sgrehan * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14221828Sgrehan * version 2 for more details (a copy is included in the LICENSE file that 15221828Sgrehan * accompanied this code). 16221828Sgrehan * 17221828Sgrehan * You should have received a copy of the GNU General Public License version 18221828Sgrehan * 2 along with this work; if not, write to the Free Software Foundation, 19221828Sgrehan * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20221828Sgrehan * 21221828Sgrehan * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22221828Sgrehan * or visit www.oracle.com if you need additional information or have any 23221828Sgrehan * questions. 24221828Sgrehan */ 25221828Sgrehan 26221828Sgrehanpackage javax.lang.model.element; 27221828Sgrehan 28221828Sgrehan 29221828Sgrehanimport java.util.List; 30221828Sgrehan 31221828Sgrehanimport javax.lang.model.type.TypeMirror; 32221828Sgrehan 33221828Sgrehan 34221828Sgrehan/** 35221828Sgrehan * A visitor of the values of annotation type elements, using a 36221828Sgrehan * variant of the visitor design pattern. Unlike a standard visitor 37244013Sgrehan * which dispatches based on the concrete type of a member of a type 38221828Sgrehan * hierarchy, this visitor dispatches based on the type of data 39221828Sgrehan * stored; there are no distinct subclasses for storing, for example, 40221828Sgrehan * {@code boolean} values versus {@code int} values. Classes 41221828Sgrehan * implementing this interface are used to operate on a value when the 42221828Sgrehan * type of that value is unknown at compile time. When a visitor is 43221828Sgrehan * passed to a value's {@link AnnotationValue#accept accept} method, 44221828Sgrehan * the <code>visit<i>Xyz</i></code> method applicable to that value is 45221828Sgrehan * invoked. 46221828Sgrehan * 47221828Sgrehan * <p> Classes implementing this interface may or may not throw a 48221828Sgrehan * {@code NullPointerException} if the additional parameter {@code p} 49256390Sgrehan * is {@code null}; see documentation of the implementing class for 50221828Sgrehan * details. 51244167Sgrehan * 52221828Sgrehan * <p> <b>WARNING:</b> It is possible that methods will be added to 53221828Sgrehan * this interface to accommodate new, currently unknown, language 54221828Sgrehan * structures added to future versions of the Java™ programming 55256390Sgrehan * language. Therefore, visitor classes directly implementing this 56256390Sgrehan * interface may be source incompatible with future versions of the 57256390Sgrehan * platform. To avoid this source incompatibility, visitor 58256390Sgrehan * implementations are encouraged to instead extend the appropriate 59221828Sgrehan * abstract visitor class that implements this interface. However, an 60221828Sgrehan * API should generally use this visitor interface as the type for 61221828Sgrehan * parameters, return type, etc. rather than one of the abstract 62221828Sgrehan * classes. 63221828Sgrehan * 64221828Sgrehan * <p>Note that methods to accommodate new language constructs could 65256390Sgrehan * be added in a source <em>compatible</em> way if they were added as 66221828Sgrehan * <em>default methods</em>. However, default methods are only 67256390Sgrehan * available on Java SE 8 and higher releases and the {@code 68256390Sgrehan * javax.lang.model.*} packages bundled in Java SE 8 were required to 69257128Sgrehan * also be runnable on Java SE 7. Therefore, default methods 70257128Sgrehan * were <em>not</em> used when extending {@code javax.lang.model.*} 71257128Sgrehan * to cover Java SE 8 language features. However, default methods 72257128Sgrehan * are used in subsequent revisions of the {@code javax.lang.model.*} 73221828Sgrehan * packages that are only required to run on Java SE 8 and higher 74221828Sgrehan * platform versions. 75221828Sgrehan * 76221828Sgrehan * @param <R> the return type of this visitor's methods 77257128Sgrehan * @param <P> the type of the additional parameter to this visitor's methods. 78257128Sgrehan * @author Joseph D. Darcy 79253440Sgrehan * @author Scott Seligman 80221828Sgrehan * @author Peter von der Ahé 81221828Sgrehan * @since 1.6 82253440Sgrehan */ 83221828Sgrehanpublic interface AnnotationValueVisitor<R, P> { 84221828Sgrehan /** 85221828Sgrehan * Visits an annotation value. 86221828Sgrehan * @param av the value to visit 87221828Sgrehan * @param p a visitor-specified parameter 88221828Sgrehan * @return a visitor-specified result 89221828Sgrehan */ 90221828Sgrehan R visit(AnnotationValue av, P p); 91221828Sgrehan 92221828Sgrehan /** 93221828Sgrehan * A convenience method equivalent to {@code visit(av, null)}. 94221828Sgrehan * 95221828Sgrehan * @implSpec The default implementation is {@code visit(av, null)}. 96221828Sgrehan * 97221828Sgrehan * @param av the value to visit 98221828Sgrehan * @return a visitor-specified result 99247342Sneel */ 100247342Sneel default R visit(AnnotationValue av) { 101256390Sgrehan return visit(av, null); 102247342Sneel } 103221828Sgrehan 104221828Sgrehan /** 105221828Sgrehan * Visits a {@code boolean} value in an annotation. 106221828Sgrehan * @param b the value being visited 107221828Sgrehan * @param p a visitor-specified parameter 108221828Sgrehan * @return the result of the visit 109221828Sgrehan */ 110221828Sgrehan R visitBoolean(boolean b, P p); 111221828Sgrehan 112221828Sgrehan /** 113221828Sgrehan * Visits a {@code byte} value in an annotation. 114221828Sgrehan * @param b the value being visited 115221828Sgrehan * @param p a visitor-specified parameter 116221828Sgrehan * @return the result of the visit 117221828Sgrehan */ 118221828Sgrehan R visitByte(byte b, P p); 119253440Sgrehan 120253440Sgrehan /** 121221828Sgrehan * Visits a {@code char} value in an annotation. 122221828Sgrehan * @param c the value being visited 123256390Sgrehan * @param p a visitor-specified parameter 124221828Sgrehan * @return the result of the visit 125221828Sgrehan */ 126253440Sgrehan R visitChar(char c, P p); 127253440Sgrehan 128253440Sgrehan /** 129253440Sgrehan * Visits a {@code double} value in an annotation. 130246214Sneel * @param d the value being visited 131253440Sgrehan * @param p a visitor-specified parameter 132253440Sgrehan * @return the result of the visit 133253440Sgrehan */ 134253440Sgrehan R visitDouble(double d, P p); 135253440Sgrehan 136253440Sgrehan /** 137253440Sgrehan * Visits a {@code float} value in an annotation. 138253440Sgrehan * @param f the value being visited 139253440Sgrehan * @param p a visitor-specified parameter 140253440Sgrehan * @return the result of the visit 141246214Sneel */ 142221828Sgrehan R visitFloat(float f, P p); 143253440Sgrehan 144221828Sgrehan /** 145253440Sgrehan * Visits an {@code int} value in an annotation. 146221828Sgrehan * @param i the value being visited 147253440Sgrehan * @param p a visitor-specified parameter 148253440Sgrehan * @return the result of the visit 149221828Sgrehan */ 150221828Sgrehan R visitInt(int i, P p); 151221828Sgrehan 152253440Sgrehan /** 153221828Sgrehan * Visits a {@code long} value in an annotation. 154221828Sgrehan * @param i the value being visited 155221828Sgrehan * @param p a visitor-specified parameter 156253440Sgrehan * @return the result of the visit 157221828Sgrehan */ 158221828Sgrehan R visitLong(long i, P p); 159253440Sgrehan 160221828Sgrehan /** 161253440Sgrehan * Visits a {@code short} value in an annotation. 162253440Sgrehan * @param s the value being visited 163221828Sgrehan * @param p a visitor-specified parameter 164253440Sgrehan * @return the result of the visit 165221828Sgrehan */ 166253440Sgrehan R visitShort(short s, P p); 167253440Sgrehan 168253440Sgrehan /** 169253440Sgrehan * Visits a string value in an annotation. 170253440Sgrehan * @param s the value being visited 171253440Sgrehan * @param p a visitor-specified parameter 172253440Sgrehan * @return the result of the visit 173253440Sgrehan */ 174255890Sgrehan R visitString(String s, P p); 175221828Sgrehan 176253440Sgrehan /** 177253440Sgrehan * Visits a type value in an annotation. 178253440Sgrehan * @param t the value being visited 179221828Sgrehan * @param p a visitor-specified parameter 180253440Sgrehan * @return the result of the visit 181253440Sgrehan */ 182253440Sgrehan R visitType(TypeMirror t, P p); 183221828Sgrehan 184221828Sgrehan /** 185247342Sneel * Visits an {@code enum} value in an annotation. 186247342Sneel * @param c the value being visited 187247342Sneel * @param p a visitor-specified parameter 188247342Sneel * @return the result of the visit 189247342Sneel */ 190247342Sneel R visitEnumConstant(VariableElement c, P p); 191221828Sgrehan 192221828Sgrehan /** 193221828Sgrehan * Visits an annotation value in an annotation. 194253440Sgrehan * @param a the value being visited 195253440Sgrehan * @param p a visitor-specified parameter 196221828Sgrehan * @return the result of the visit 197221828Sgrehan */ 198256390Sgrehan R visitAnnotation(AnnotationMirror a, P p); 199221828Sgrehan 200221828Sgrehan /** 201221828Sgrehan * Visits an array value in an annotation. 202253440Sgrehan * @param vals the value being visited 203253440Sgrehan * @param p a visitor-specified parameter 204221828Sgrehan * @return the result of the visit 205221828Sgrehan */ 206221828Sgrehan R visitArray(List<? extends AnnotationValue> vals, P p); 207256390Sgrehan 208221828Sgrehan /** 209256390Sgrehan * Visits an unknown kind of annotation value. 210256390Sgrehan * This can occur if the language evolves and new kinds 211253440Sgrehan * of value can be stored in an annotation. 212256390Sgrehan * @param av the unknown value being visited 213256390Sgrehan * @param p a visitor-specified parameter 214253440Sgrehan * @return the result of the visit 215256390Sgrehan * @throws UnknownAnnotationValueException 216256390Sgrehan * a visitor implementation may optionally throw this exception 217256390Sgrehan */ 218256390Sgrehan R visitUnknown(AnnotationValue av, P p); 219256390Sgrehan} 220256390Sgrehan