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