Tue, 05 Jul 2011 16:37:24 -0700
7025809: Provided new utility visitors supporting SourceVersion.RELEASE_8
Reviewed-by: jjg, mcimadamore
1 /*
2 * Copyright (c) 2005, 2011, 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 */
26 package javax.lang.model.util;
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;
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} <tt><i>XYZ</i></tt> that may have more than one
40 * kind, the <tt>visit<i>XYZ</i></tt> methods in this class delegate
41 * to the <tt>visit<i>XYZKind</i></tt> method corresponding to the
42 * first argument's kind. The <tt>visit<i>XYZKind</i></tt> methods
43 * call {@link #defaultAction defaultAction}, passing their arguments
44 * to {@code defaultAction}'s corresponding parameters.
45 *
46 * <p> Methods in this class may be overridden subject to their
47 * general contract. Note that annotating methods in concrete
48 * subclasses with {@link java.lang.Override @Override} will help
49 * ensure that methods are overridden as intended.
50 *
51 * <p> <b>WARNING:</b> The {@code ElementVisitor} interface
52 * implemented by this class may have methods added to it or the
53 * {@code ElementKind} {@code enum} used in this case may have
54 * constants added to it in the future to accommodate new, currently
55 * unknown, language structures added to future versions of the
56 * Java™ programming language. Therefore, methods whose names
57 * begin with {@code "visit"} may be added to this class in the
58 * future; to avoid incompatibilities, classes which extend this class
59 * should not declare any instance methods with names beginning with
60 * {@code "visit"}.
61 *
62 * <p>When such a new visit method is added, the default
63 * implementation in this class will be to call the {@link
64 * #visitUnknown visitUnknown} method. A new abstract element kind
65 * visitor class will also be introduced to correspond to the new
66 * language level; this visitor will have different default behavior
67 * for the visit method in question. When the new visitor is
68 * introduced, all or portions of this visitor may be deprecated.
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 * @since 1.6
83 */
84 @SupportedSourceVersion(RELEASE_6)
85 public class ElementKindVisitor6<R, P>
86 extends SimpleElementVisitor6<R, P> {
87 /**
88 * Constructor for concrete subclasses; uses {@code null} for the
89 * default value.
90 */
91 protected ElementKindVisitor6() {
92 super(null);
93 }
95 /**
96 * Constructor for concrete subclasses; uses the argument for the
97 * default value.
98 *
99 * @param defaultValue the value to assign to {@link #DEFAULT_VALUE}
100 */
101 protected ElementKindVisitor6(R defaultValue) {
102 super(defaultValue);
103 }
105 /**
106 * {@inheritDoc}
107 *
108 * The element argument has kind {@code PACKAGE}.
109 *
110 * @param e {@inheritDoc}
111 * @param p {@inheritDoc}
112 * @return {@inheritDoc}
113 */
114 @Override
115 public R visitPackage(PackageElement e, P p) {
116 assert e.getKind() == PACKAGE: "Bad kind on PackageElement";
117 return defaultAction(e, p);
118 }
120 /**
121 * Visits a type element, dispatching to the visit method for the
122 * specific {@linkplain ElementKind kind} of type, {@code
123 * ANNOTATION_TYPE}, {@code CLASS}, {@code ENUM}, or {@code
124 * INTERFACE}.
125 *
126 * @param e {@inheritDoc}
127 * @param p {@inheritDoc}
128 * @return the result of the kind-specific visit method
129 */
130 @Override
131 public R visitType(TypeElement e, P p) {
132 ElementKind k = e.getKind();
133 switch(k) {
134 case ANNOTATION_TYPE:
135 return visitTypeAsAnnotationType(e, p);
137 case CLASS:
138 return visitTypeAsClass(e, p);
140 case ENUM:
141 return visitTypeAsEnum(e, p);
143 case INTERFACE:
144 return visitTypeAsInterface(e, p);
146 default:
147 throw new AssertionError("Bad kind " + k + " for TypeElement" + e);
148 }
149 }
151 /**
152 * Visits an {@code ANNOTATION_TYPE} type element by calling
153 * {@code defaultAction}.
154 *
155 * @param e the element to visit
156 * @param p a visitor-specified parameter
157 * @return the result of {@code defaultAction}
158 */
159 public R visitTypeAsAnnotationType(TypeElement e, P p) {
160 return defaultAction(e, p);
161 }
163 /**
164 * Visits a {@code CLASS} type element by calling {@code
165 * defaultAction}.
166 *
167 * @param e the element to visit
168 * @param p a visitor-specified parameter
169 * @return the result of {@code defaultAction}
170 */
171 public R visitTypeAsClass(TypeElement e, P p) {
172 return defaultAction(e, p);
173 }
175 /**
176 * Visits an {@code ENUM} type element by calling {@code
177 * defaultAction}.
178 *
179 * @param e the element to visit
180 * @param p a visitor-specified parameter
181 * @return the result of {@code defaultAction}
182 */
183 public R visitTypeAsEnum(TypeElement e, P p) {
184 return defaultAction(e, p);
185 }
187 /**
188 * Visits an {@code INTERFACE} type element by calling {@code
189 * defaultAction}.
190 *.
191 * @param e the element to visit
192 * @param p a visitor-specified parameter
193 * @return the result of {@code defaultAction}
194 */
195 public R visitTypeAsInterface(TypeElement e, P p) {
196 return defaultAction(e, p);
197 }
199 /**
200 * Visits a variable element, dispatching to the visit method for
201 * the specific {@linkplain ElementKind kind} of variable, {@code
202 * ENUM_CONSTANT}, {@code EXCEPTION_PARAMETER}, {@code FIELD},
203 * {@code LOCAL_VARIABLE}, {@code PARAMETER}, or {@code RESOURCE_VARIABLE}.
204 *
205 * @param e {@inheritDoc}
206 * @param p {@inheritDoc}
207 * @return the result of the kind-specific visit method
208 */
209 @Override
210 public R visitVariable(VariableElement e, P p) {
211 ElementKind k = e.getKind();
212 switch(k) {
213 case ENUM_CONSTANT:
214 return visitVariableAsEnumConstant(e, p);
216 case EXCEPTION_PARAMETER:
217 return visitVariableAsExceptionParameter(e, p);
219 case FIELD:
220 return visitVariableAsField(e, p);
222 case LOCAL_VARIABLE:
223 return visitVariableAsLocalVariable(e, p);
225 case PARAMETER:
226 return visitVariableAsParameter(e, p);
228 case RESOURCE_VARIABLE:
229 return visitVariableAsResourceVariable(e, p);
231 default:
232 throw new AssertionError("Bad kind " + k + " for VariableElement" + e);
233 }
234 }
236 /**
237 * Visits an {@code ENUM_CONSTANT} variable element by calling
238 * {@code defaultAction}.
239 *
240 * @param e the element to visit
241 * @param p a visitor-specified parameter
242 * @return the result of {@code defaultAction}
243 */
244 public R visitVariableAsEnumConstant(VariableElement e, P p) {
245 return defaultAction(e, p);
246 }
248 /**
249 * Visits an {@code EXCEPTION_PARAMETER} variable element by calling
250 * {@code defaultAction}.
251 *
252 * @param e the element to visit
253 * @param p a visitor-specified parameter
254 * @return the result of {@code defaultAction}
255 */
256 public R visitVariableAsExceptionParameter(VariableElement e, P p) {
257 return defaultAction(e, p);
258 }
260 /**
261 * Visits a {@code FIELD} variable element by calling
262 * {@code defaultAction}.
263 *
264 * @param e the element to visit
265 * @param p a visitor-specified parameter
266 * @return the result of {@code defaultAction}
267 */
268 public R visitVariableAsField(VariableElement e, P p) {
269 return defaultAction(e, p);
270 }
272 /**
273 * Visits a {@code LOCAL_VARIABLE} variable element by calling
274 * {@code defaultAction}.
275 *
276 * @param e the element to visit
277 * @param p a visitor-specified parameter
278 * @return the result of {@code defaultAction}
279 */
280 public R visitVariableAsLocalVariable(VariableElement e, P p) {
281 return defaultAction(e, p);
282 }
284 /**
285 * Visits a {@code PARAMETER} variable element by calling
286 * {@code defaultAction}.
287 *
288 * @param e the element to visit
289 * @param p a visitor-specified parameter
290 * @return the result of {@code defaultAction}
291 */
292 public R visitVariableAsParameter(VariableElement e, P p) {
293 return defaultAction(e, p);
294 }
296 /**
297 * Visits a {@code RESOURCE_VARIABLE} variable element by calling
298 * {@code visitUnknown}.
299 *
300 * @param e the element to visit
301 * @param p a visitor-specified parameter
302 * @return the result of {@code visitUnknown}
303 *
304 * @since 1.7
305 */
306 public R visitVariableAsResourceVariable(VariableElement e, P p) {
307 return visitUnknown(e, p);
308 }
310 /**
311 * Visits an executable element, dispatching to the visit method
312 * for the specific {@linkplain ElementKind kind} of executable,
313 * {@code CONSTRUCTOR}, {@code INSTANCE_INIT}, {@code METHOD}, or
314 * {@code STATIC_INIT}.
315 *
316 * @param e {@inheritDoc}
317 * @param p {@inheritDoc}
318 * @return the result of the kind-specific visit method
319 */
320 @Override
321 public R visitExecutable(ExecutableElement e, P p) {
322 ElementKind k = e.getKind();
323 switch(k) {
324 case CONSTRUCTOR:
325 return visitExecutableAsConstructor(e, p);
327 case INSTANCE_INIT:
328 return visitExecutableAsInstanceInit(e, p);
330 case METHOD:
331 return visitExecutableAsMethod(e, p);
333 case STATIC_INIT:
334 return visitExecutableAsStaticInit(e, p);
336 default:
337 throw new AssertionError("Bad kind " + k + " for ExecutableElement" + e);
338 }
339 }
341 /**
342 * Visits a {@code CONSTRUCTOR} executable element by calling
343 * {@code defaultAction}.
344 *
345 * @param e the element to visit
346 * @param p a visitor-specified parameter
347 * @return the result of {@code defaultAction}
348 */
349 public R visitExecutableAsConstructor(ExecutableElement e, P p) {
350 return defaultAction(e, p);
351 }
353 /**
354 * Visits an {@code INSTANCE_INIT} executable element by calling
355 * {@code defaultAction}.
356 *
357 * @param e the element to visit
358 * @param p a visitor-specified parameter
359 * @return the result of {@code defaultAction}
360 */
361 public R visitExecutableAsInstanceInit(ExecutableElement e, P p) {
362 return defaultAction(e, p);
363 }
365 /**
366 * Visits a {@code METHOD} executable element by calling
367 * {@code defaultAction}.
368 *
369 * @param e the element to visit
370 * @param p a visitor-specified parameter
371 * @return the result of {@code defaultAction}
372 */
373 public R visitExecutableAsMethod(ExecutableElement e, P p) {
374 return defaultAction(e, p);
375 }
377 /**
378 * Visits a {@code STATIC_INIT} executable element by calling
379 * {@code defaultAction}.
380 *
381 * @param e the element to visit
382 * @param p a visitor-specified parameter
383 * @return the result of {@code defaultAction}
384 */
385 public R visitExecutableAsStaticInit(ExecutableElement e, P p) {
386 return defaultAction(e, p);
387 }
390 /**
391 * {@inheritDoc}
392 *
393 * The element argument has kind {@code TYPE_PARAMETER}.
394 *
395 * @param e {@inheritDoc}
396 * @param p {@inheritDoc}
397 * @return {@inheritDoc}
398 */
399 @Override
400 public R visitTypeParameter(TypeParameterElement e, P p) {
401 assert e.getKind() == TYPE_PARAMETER: "Bad kind on TypeParameterElement";
402 return defaultAction(e, p);
403 }
404 }