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.util;
27
28 import javax.lang.model.element.*;
29 import static javax.lang.model.element.ElementKind.*;
30 import javax.annotation.processing.SupportedSourceVersion;
31 import static javax.lang.model.SourceVersion.*;
32 import javax.lang.model.SourceVersion;
33
34
35 /**
36 * A visitor of program elements based on their {@linkplain
37 * ElementKind kind} with default behavior appropriate for the {@link
38 * SourceVersion#RELEASE_6 RELEASE_6} source version. For {@linkplain
39 * Element elements} <code><i>Xyz</i></code> that may have more than one
40 * kind, the <code>visit<i>Xyz</i></code> methods in this class delegate
41 * to the <code>visit<i>Xyz</i>As<i>Kind</i></code> method corresponding to the
42 * first argument's kind. The <code>visit<i>Xyz</i>As<i>Kind</i></code> methods
43 * call {@link #defaultAction defaultAction}, passing their arguments
44 * to {@code defaultAction}'s corresponding parameters.
45 *
46 * @apiNote
47 * Methods in this class may be overridden subject to their general
48 * contract.
49 *
50 * <p id=note_for_subclasses><strong>WARNING:</strong> The {@code
51 * ElementVisitor} interface implemented by this class may have
52 * methods added to it or the {@link ElementKind ElementKind enum}
53 * used in this class may have constants added to it in the future to
54 * accommodate new, currently unknown, language structures added to
55 * future versions of the Java programming language.
56 * Therefore, methods whose names begin with {@code "visit"} may be
57 * added to this class in the future; to avoid incompatibilities,
58 * classes and subclasses which extend this class should not declare
59 * any instance methods with names beginning with {@code "visit"}.</p>
60 *
61 * <p>When such a new visit method is added, the default
62 * implementation in this class will be to directly or indirectly call
63 * the {@link #visitUnknown visitUnknown} method. A new abstract
64 * element kind visitor class will also be introduced to correspond to
65 * the new language level; this visitor will have different default
66 * behavior for the visit method in question. When a new visitor is
67 * introduced, portions of this visitor class may be deprecated,
68 * including its constructors.
69 *
70 * @param <R> the return type of this visitor's methods. Use {@link
71 * Void} for visitors that do not need to return results.
72 * @param <P> the type of the additional parameter to this visitor's
73 * methods. Use {@code Void} for visitors that do not need an
74 * additional parameter.
75 *
76 * @author Joseph D. Darcy
77 * @author Scott Seligman
78 * @author Peter von der Ahé
79 *
80 * @see ElementKindVisitor7
81 * @see ElementKindVisitor8
82 * @see ElementKindVisitor9
83 * @see ElementKindVisitor14
84 * @since 1.6
85 */
86 @SupportedSourceVersion(RELEASE_6)
87 public class ElementKindVisitor6<R, P>
88 extends SimpleElementVisitor6<R, P> {
89 /**
90 * Constructor for concrete subclasses; uses {@code null} for the
91 * default value.
92 * @deprecated Release 6 is obsolete; update to a visitor for a newer
93 * release level.
94 */
95 @Deprecated(since="9")
96 protected ElementKindVisitor6() {
97 super(null);
98 }
99
100 /**
101 * Constructor for concrete subclasses; uses the argument for the
102 * default value.
103 *
104 * @param defaultValue the value to assign to {@link #DEFAULT_VALUE}
105 * @deprecated Release 6 is obsolete; update to a visitor for a newer
106 * release level.
107 */
108 @Deprecated(since="9")
109 protected ElementKindVisitor6(R defaultValue) {
110 super(defaultValue);
111 }
112
113 /**
114 * {@inheritDoc}
115 *
116 * The element argument has kind {@code PACKAGE}.
117 *
118 * @implSpec This implementation calls {@code defaultAction}.
119 *
120 * @param e {@inheritDoc}
121 * @param p {@inheritDoc}
122 * @return {@inheritDoc}
123 */
124 @Override
125 public R visitPackage(PackageElement e, P p) {
126 assert e.getKind() == PACKAGE: "Bad kind on PackageElement";
127 return defaultAction(e, p);
128 }
129
130 /**
131 * {@inheritDoc}
132 *
133 * @implSpec This implementation dispatches to the visit method for the
134 * specific {@linkplain ElementKind kind} of type, {@code
135 * ANNOTATION_TYPE}, {@code CLASS}, {@code ENUM}, or {@code
136 * INTERFACE}.
137 *
138 * @param e {@inheritDoc}
139 * @param p {@inheritDoc}
140 * @return the result of the kind-specific visit method
141 */
142 @SuppressWarnings("preview")
143 @Override
144 public R visitType(TypeElement e, P p) {
145 ElementKind k = e.getKind();
146 switch(k) {
147 case ANNOTATION_TYPE:
148 return visitTypeAsAnnotationType(e, p);
149
150 case CLASS:
151 return visitTypeAsClass(e, p);
152
153 case ENUM:
154 return visitTypeAsEnum(e, p);
155
156 case INTERFACE:
157 return visitTypeAsInterface(e, p);
158
159 case RECORD:
160 return visitTypeAsRecord(e, p);
161
162 default:
163 throw new AssertionError("Bad kind " + k + " for TypeElement" + e);
164 }
165 }
166
167 /**
168 * Visits an {@code ANNOTATION_TYPE} type element.
169 *
170 * @implSpec This implementation calls {@code defaultAction}.
171 *
172 * @param e the element to visit
173 * @param p a visitor-specified parameter
174 * @return the result of {@code defaultAction}
175 */
176 public R visitTypeAsAnnotationType(TypeElement e, P p) {
177 return defaultAction(e, p);
178 }
179
180 /**
181 * Visits a {@code CLASS} type element.
182 *
183 * @implSpec This implementation calls {@code defaultAction}.
184 *
185 * @param e the element to visit
186 * @param p a visitor-specified parameter
187 * @return the result of {@code defaultAction}
188 */
189 public R visitTypeAsClass(TypeElement e, P p) {
190 return defaultAction(e, p);
191 }
192
193 /**
194 * Visits an {@code ENUM} type element.
195 *
196 * @implSpec This implementation calls {@code defaultAction}.
197 *
198 * @param e the element to visit
199 * @param p a visitor-specified parameter
200 * @return the result of {@code defaultAction}
201 */
202 public R visitTypeAsEnum(TypeElement e, P p) {
203 return defaultAction(e, p);
204 }
205
206 /**
207 * Visits an {@code INTERFACE} type element.
208 *
209 * @implSpec This implementation calls {@code defaultAction}.
210 *.
211 * @param e the element to visit
212 * @param p a visitor-specified parameter
213 * @return the result of {@code defaultAction}
214 */
215 public R visitTypeAsInterface(TypeElement e, P p) {
216 return defaultAction(e, p);
217 }
218
219 /**
220 * {@preview Associated with records, a preview feature of the Java language.
221 *
222 * This method is associated with <i>records</i>, a preview
223 * feature of the Java language. Preview features
224 * may be removed in a future release, or upgraded to permanent
225 * features of the Java language.}
226 *
227 * Visits a {@code RECORD} type element.
228 *
229 * @implSpec This implementation calls {@code visitUnknown}.
230 *.
231 * @param e the element to visit
232 * @param p a visitor-specified parameter
233 * @return the result of {@code visitUnknown}
234 *
235 * @since 14
236 */
237 @jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.RECORDS,
238 essentialAPI=false)
239 public R visitTypeAsRecord(TypeElement e, P p) {
240 return visitUnknown(e, p);
241 }
242
243 /**
244 * Visits a variable element
245 *
246 * @implSpec This implementation dispatches to the visit method for
247 * the specific {@linkplain ElementKind kind} of variable, {@code
248 * ENUM_CONSTANT}, {@code EXCEPTION_PARAMETER}, {@code FIELD},
249 * {@code LOCAL_VARIABLE}, {@code PARAMETER}, or {@code RESOURCE_VARIABLE}.
250 *
251 * @param e {@inheritDoc}
252 * @param p {@inheritDoc}
253 * @return the result of the kind-specific visit method
254 */
255 @Override
256 public R visitVariable(VariableElement e, P p) {
257 ElementKind k = e.getKind();
258 switch(k) {
259 case ENUM_CONSTANT:
260 return visitVariableAsEnumConstant(e, p);
261
262 case EXCEPTION_PARAMETER:
263 return visitVariableAsExceptionParameter(e, p);
264
265 case FIELD:
266 return visitVariableAsField(e, p);
267
268 case LOCAL_VARIABLE:
269 return visitVariableAsLocalVariable(e, p);
270
271 case PARAMETER:
272 return visitVariableAsParameter(e, p);
273
274 case RESOURCE_VARIABLE:
275 return visitVariableAsResourceVariable(e, p);
276
277 case BINDING_VARIABLE:
278 return visitVariableAsBindingVariable(e, p);
279
280 default:
281 throw new AssertionError("Bad kind " + k + " for VariableElement" + e);
282 }
283 }
284
285 /**
286 * Visits an {@code ENUM_CONSTANT} variable element.
287 *
288 * @implSpec This implementation calls {@code defaultAction}.
289 *.
290 * @param e the element to visit
291 * @param p a visitor-specified parameter
292 * @return the result of {@code defaultAction}
293 */
294 public R visitVariableAsEnumConstant(VariableElement e, P p) {
295 return defaultAction(e, p);
296 }
297
298 /**
299 * Visits an {@code EXCEPTION_PARAMETER} variable element.
300 *
301 * @implSpec This implementation calls {@code defaultAction}.
302 *.
303 * @param e the element to visit
304 * @param p a visitor-specified parameter
305 * @return the result of {@code defaultAction}
306 */
307 public R visitVariableAsExceptionParameter(VariableElement e, P p) {
308 return defaultAction(e, p);
309 }
310
311 /**
312 * Visits a {@code FIELD} variable element.
313 *
314 * @implSpec This implementation calls {@code defaultAction}.
315 *.
316 * @param e the element to visit
317 * @param p a visitor-specified parameter
318 * @return the result of {@code defaultAction}
319 */
320 public R visitVariableAsField(VariableElement e, P p) {
321 return defaultAction(e, p);
322 }
323
324 /**
325 * Visits a {@code LOCAL_VARIABLE} variable element.
326 *
327 * @implSpec This implementation calls {@code defaultAction}.
328 *
329 * @param e the element to visit
330 * @param p a visitor-specified parameter
331 * @return the result of {@code defaultAction}
332 */
333 public R visitVariableAsLocalVariable(VariableElement e, P p) {
334 return defaultAction(e, p);
335 }
336
337 /**
338 * Visits a {@code PARAMETER} variable element.
339 *
340 * @implSpec This implementation calls {@code defaultAction}.
341 *
342 * @param e the element to visit
343 * @param p a visitor-specified parameter
344 * @return the result of {@code defaultAction}
345 */
346 public R visitVariableAsParameter(VariableElement e, P p) {
347 return defaultAction(e, p);
348 }
349
350 /**
351 * Visits a {@code RESOURCE_VARIABLE} variable element.
352 *
353 * @implSpec This implementation calls {@code visitUnknown}.
354 *
355 * @param e the element to visit
356 * @param p a visitor-specified parameter
357 * @return the result of {@code visitUnknown}
358 *
359 * @since 1.7
360 */
361 public R visitVariableAsResourceVariable(VariableElement e, P p) {
362 return visitUnknown(e, p);
363 }
364
365 /**
366 * Visits a {@code BINDING_VARIABLE} variable element.
367 *
368 * @implSpec This implementation calls {@code visitUnknown}.
369 *
370 * @param e the element to visit
371 * @param p a visitor-specified parameter
372 * @return the result of {@code visitUnknown}
373 *
374 * @since 14
375 */
376 public R visitVariableAsBindingVariable(VariableElement e, P p) {
377 return visitUnknown(e, p);
378 }
379
380 /**
381 * {@inheritDoc}
382 *
383 * @implSpec This implementation dispatches to the visit method
384 * for the specific {@linkplain ElementKind kind} of executable,
385 * {@code CONSTRUCTOR}, {@code INSTANCE_INIT}, {@code METHOD}, or
386 * {@code STATIC_INIT}.
387 *
388 * @param e {@inheritDoc}
389 * @param p {@inheritDoc}
390 * @return the result of the kind-specific visit method
391 */
392 @Override
393 public R visitExecutable(ExecutableElement e, P p) {
394 ElementKind k = e.getKind();
395 switch(k) {
396 case CONSTRUCTOR:
397 return visitExecutableAsConstructor(e, p);
398
399 case INSTANCE_INIT:
400 return visitExecutableAsInstanceInit(e, p);
401
402 case METHOD:
403 return visitExecutableAsMethod(e, p);
404
405 case STATIC_INIT:
406 return visitExecutableAsStaticInit(e, p);
407
408 default:
409 throw new AssertionError("Bad kind " + k + " for ExecutableElement" + e);
410 }
411 }
412
413 /**
414 * Visits a {@code CONSTRUCTOR} executable element.
415 *
416 * @implSpec This implementation calls {@code defaultAction}.
417 *
418 * @param e the element to visit
419 * @param p a visitor-specified parameter
420 * @return the result of {@code defaultAction}
421 */
422 public R visitExecutableAsConstructor(ExecutableElement e, P p) {
423 return defaultAction(e, p);
424 }
425
426 /**
427 * Visits an {@code INSTANCE_INIT} executable element.
428 *
429 * @implSpec This implementation calls {@code defaultAction}.
430 *
431 * @param e the element to visit
432 * @param p a visitor-specified parameter
433 * @return the result of {@code defaultAction}
434 */
435 public R visitExecutableAsInstanceInit(ExecutableElement e, P p) {
436 return defaultAction(e, p);
437 }
438
439 /**
440 * Visits a {@code METHOD} executable element.
441 *
442 * @implSpec This implementation calls {@code defaultAction}.
443 *
444 * @param e the element to visit
445 * @param p a visitor-specified parameter
446 * @return the result of {@code defaultAction}
447 */
448 public R visitExecutableAsMethod(ExecutableElement e, P p) {
449 return defaultAction(e, p);
450 }
451
452 /**
453 * Visits a {@code STATIC_INIT} executable element.
454 *
455 * @implSpec This implementation calls {@code defaultAction}.
456 *
457 * @param e the element to visit
458 * @param p a visitor-specified parameter
459 * @return the result of {@code defaultAction}
460 */
461 public R visitExecutableAsStaticInit(ExecutableElement e, P p) {
462 return defaultAction(e, p);
463 }
464
465 /**
466 * {@inheritDoc}
467 *
468 * The element argument has kind {@code TYPE_PARAMETER}.
469 *
470 * @implSpec This implementation calls {@code defaultAction}.
471 *
472 * @param e {@inheritDoc}
473 * @param p {@inheritDoc}
474 * @return {@inheritDoc}
475 */
476 @Override
477 public R visitTypeParameter(TypeParameterElement e, P p) {
478 assert e.getKind() == TYPE_PARAMETER: "Bad kind on TypeParameterElement";
479 return defaultAction(e, p);
480 }
481 }