1 /* 2 * Copyright (c) 2005, 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.element; 27 28 29 import java.util.List; 30 import javax.lang.model.type.TypeMirror; 31 import javax.lang.model.util.*; 32 33 /** 34 * A visitor of the values of annotation type elements, using a 35 * variant of the visitor design pattern. Unlike a standard visitor 36 * which dispatches based on the concrete type of a member of a type 37 * hierarchy, this visitor dispatches based on the type of data 38 * stored; there are no distinct subclasses for storing, for example, 39 * {@code boolean} values versus {@code int} values. Classes 40 * implementing this interface are used to operate on a value when the 41 * type of that value is unknown at compile time. When a visitor is 42 * passed to a value's {@link AnnotationValue#accept accept} method, 43 * the <code>visit<i>Xyz</i></code> method applicable to that value is 44 * invoked. 45 * 46 * <p> Classes implementing this interface may or may not throw a 47 * {@code NullPointerException} if the additional parameter {@code p} 48 * is {@code null}; see documentation of the implementing class for 49 * details. 50 * 51 * <p> <b>WARNING:</b> It is possible that methods will be added to 52 * this interface to accommodate new, currently unknown, language 53 * structures added to future versions of the Java™ programming 54 * language. Therefore, visitor classes directly implementing this 55 * interface may be source incompatible with future versions of the 56 * platform. To avoid this source incompatibility, visitor 57 * implementations are encouraged to instead extend the appropriate 58 * abstract visitor class that implements this interface. However, an 59 * API should generally use this visitor interface as the type for 60 * parameters, return type, etc. rather than one of the abstract 61 * classes. 62 * 63 * <p>Note that methods to accommodate new language constructs could 64 * be added in a source <em>compatible</em> way if they were added as 65 * <em>default methods</em>. However, default methods are only 66 * available on Java SE 8 and higher releases and the {@code 67 * javax.lang.model.*} packages bundled in Java SE 8 were required to 68 * also be runnable on Java SE 7. Therefore, default methods 69 * were <em>not</em> used when extending {@code javax.lang.model.*} 70 * to cover Java SE 8 language features. However, default methods 71 * are used in subsequent revisions of the {@code javax.lang.model.*} 72 * packages that are only required to run on Java SE 8 and higher 73 * platform versions. 74 * 75 * @apiNote 76 * 77 * There are several families of classes implementing this visitor 78 * interface in the {@linkplain javax.lang.model.util util 79 * package}. The families follow a naming pattern along the lines of 80 * {@code FooVisitor}<i>N</i> where <i>N</i> indicates the 81 * {@linkplain javax.lang.model.SourceVersion source version} the 82 * visitor is appropriate for. 83 * 84 * In particular, a {@code FooVisitor}<i>N</i> is expected to handle 85 * all language constructs present in source version <i>N</i>. If 86 * there are no new language constructs added in version 87 * <i>N</i> + 1 (or subsequent releases), {@code 88 * FooVisitor}<i>N</i> may also handle that later source version; in 89 * that case, the {@link 90 * javax.annotation.processing.SupportedSourceVersion 91 * SupportedSourceVersion} annotation on the {@code 92 * FooVisitor}<i>N</i> class will indicate a later version. 93 * 94 * When visiting an annotation value representing a language construct 95 * introduced <strong>after</strong> source version <i>N</i>, a {@code 96 * FooVisitor}<i>N</i> will throw an {@link 97 * UnknownAnnotationValueException} unless that behavior is overridden. 98 * 99 * <p>When choosing which member of a visitor family to subclass, 100 * subclassing the most recent one increases the range of source 101 * versions covered. When choosing which visitor family to subclass, 102 * consider their built-in capabilities: 103 * 104 * <ul> 105 * 106 * <li>{@link AbstractAnnotationValueVisitor6 107 * AbstractAnnotationValueVisitor}s: Skeletal visitor implementations. 108 * 109 * <li>{@link SimpleAnnotationValueVisitor6 110 * SimpleAnnotationValueVisitor}s: Support default actions and a 111 * default return value. 112 * 113 * </ul> 114 * 115 * @param <R> the return type of this visitor's methods 116 * @param <P> the type of the additional parameter to this visitor's methods. 117 * @author Joseph D. Darcy 118 * @author Scott Seligman 119 * @author Peter von der Ahé 120 * @since 1.6 121 */ 122 public interface AnnotationValueVisitor<R, P> { 123 /** 124 * Visits an annotation value. 125 * @param av the value to visit 126 * @param p a visitor-specified parameter 127 * @return a visitor-specified result 128 */ 129 R visit(AnnotationValue av, P p); 130 131 /** 132 * A convenience method equivalent to {@code visit(av, null)}. 133 * 134 * @implSpec The default implementation is {@code visit(av, null)}. 135 * 136 * @param av the value to visit 137 * @return a visitor-specified result 138 */ 139 default R visit(AnnotationValue av) { 140 return visit(av, null); 141 } 142 143 /** 144 * Visits a {@code boolean} value in an annotation. 145 * @param b the value being visited 146 * @param p a visitor-specified parameter 147 * @return the result of the visit 148 */ 149 R visitBoolean(boolean b, P p); 150 151 /** 152 * Visits a {@code byte} value in an annotation. 153 * @param b the value being visited 154 * @param p a visitor-specified parameter 155 * @return the result of the visit 156 */ 157 R visitByte(byte b, P p); 158 159 /** 160 * Visits a {@code char} value in an annotation. 161 * @param c the value being visited 162 * @param p a visitor-specified parameter 163 * @return the result of the visit 164 */ 165 R visitChar(char c, P p); 166 167 /** 168 * Visits a {@code double} value in an annotation. 169 * @param d the value being visited 170 * @param p a visitor-specified parameter 171 * @return the result of the visit 172 */ 173 R visitDouble(double d, P p); 174 175 /** 176 * Visits a {@code float} value in an annotation. 177 * @param f the value being visited 178 * @param p a visitor-specified parameter 179 * @return the result of the visit 180 */ 181 R visitFloat(float f, P p); 182 183 /** 184 * Visits an {@code int} value in an annotation. 185 * @param i the value being visited 186 * @param p a visitor-specified parameter 187 * @return the result of the visit 188 */ 189 R visitInt(int i, P p); 190 191 /** 192 * Visits a {@code long} value in an annotation. 193 * @param i the value being visited 194 * @param p a visitor-specified parameter 195 * @return the result of the visit 196 */ 197 R visitLong(long i, P p); 198 199 /** 200 * Visits a {@code short} value in an annotation. 201 * @param s the value being visited 202 * @param p a visitor-specified parameter 203 * @return the result of the visit 204 */ 205 R visitShort(short s, P p); 206 207 /** 208 * Visits a string value in an annotation. 209 * @param s the value being visited 210 * @param p a visitor-specified parameter 211 * @return the result of the visit 212 */ 213 R visitString(String s, P p); 214 215 /** 216 * Visits a type value in an annotation. 217 * @param t the value being visited 218 * @param p a visitor-specified parameter 219 * @return the result of the visit 220 */ 221 R visitType(TypeMirror t, P p); 222 223 /** 224 * Visits an {@code enum} value in an annotation. 225 * @param c the value being visited 226 * @param p a visitor-specified parameter 227 * @return the result of the visit 228 */ 229 R visitEnumConstant(VariableElement c, P p); 230 231 /** 232 * Visits an annotation value in an annotation. 233 * @param a the value being visited 234 * @param p a visitor-specified parameter 235 * @return the result of the visit 236 */ 237 R visitAnnotation(AnnotationMirror a, P p); 238 239 /** 240 * Visits an array value in an annotation. 241 * @param vals the value being visited 242 * @param p a visitor-specified parameter 243 * @return the result of the visit 244 */ 245 R visitArray(List<? extends AnnotationValue> vals, P p); 246 247 /** 248 * Visits an unknown kind of annotation value. 249 * This can occur if the language evolves and new kinds 250 * of value can be stored in an annotation. 251 * @param av the unknown value being visited 252 * @param p a visitor-specified parameter 253 * @return the result of the visit 254 * @throws UnknownAnnotationValueException 255 * a visitor implementation may optionally throw this exception 256 */ 257 R visitUnknown(AnnotationValue av, P p); 258 }