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 import javax.lang.model.util.*;
29
30 /**
31 * A visitor of program elements, in the style of the visitor design
32 * pattern. Classes implementing this interface are used to operate
33 * on an element when the kind of element is unknown at compile time.
34 * When a visitor is passed to an element's {@link Element#accept
35 * accept} method, the <code>visit<i>Xyz</i></code> method most applicable
36 * to that element is invoked.
37 *
38 * <p> Classes implementing this interface may or may not throw a
39 * {@code NullPointerException} if the additional parameter {@code p}
40 * is {@code null}; see documentation of the implementing class for
41 * details.
42 *
43 * <p> <b>WARNING:</b> It is possible that methods will be added to
44 * this interface to accommodate new, currently unknown, language
45 * structures added to future versions of the Java™ programming
46 * language. Therefore, visitor classes directly implementing this
47 * interface may be source incompatible with future versions of the
48 * platform. To avoid this source incompatibility, visitor
49 * implementations are encouraged to instead extend the appropriate
50 * abstract visitor class that implements this interface. However, an
51 * API should generally use this visitor interface as the type for
52 * parameters, return type, etc. rather than one of the abstract
53 * classes.
54 *
55 * <p>Note that methods to accommodate new language constructs could
56 * be added in a source <em>compatible</em> way if they were added as
57 * <em>default methods</em>. However, default methods are only
58 * available on Java SE 8 and higher releases and the {@code
59 * javax.lang.model.*} packages bundled in Java SE 8 were required to
60 * also be runnable on Java SE 7. Therefore, default methods
61 * were <em>not</em> used when extending {@code javax.lang.model.*}
62 * to cover Java SE 8 language features. However, default methods
63 * are used in subsequent revisions of the {@code javax.lang.model.*}
64 * packages that are only required to run on Java SE 8 and higher
65 * platform versions.
66 *
67 * @apiNote
68 *
69 * There are several families of classes implementing this visitor
70 * interface in the {@linkplain javax.lang.model.util util
71 * package}. The families follow a naming pattern along the lines of
72 * {@code FooVisitor}<i>N</i> where <i>N</i> indicates the
73 * {@linkplain javax.lang.model.SourceVersion source version} the
74 * visitor is appropriate for.
75 *
76 * In particular, a {@code FooVisitor}<i>N</i> is expected to handle
77 * all language constructs present in source version <i>N</i>. If
78 * there are no new language constructs added in version
79 * <i>N</i> + 1 (or subsequent releases), {@code
80 * FooVisitor}<i>N</i> may also handle that later source version; in
81 * that case, the {@link
82 * javax.annotation.processing.SupportedSourceVersion
83 * SupportedSourceVersion} annotation on the {@code
84 * FooVisitor}<i>N</i> class will indicate a later version.
85 *
86 * When visiting an element representing a language construct
87 * introduced <strong>after</strong> source version <i>N</i>, a {@code
88 * FooVisitor}<i>N</i> will throw an {@link UnknownElementException}
89 * unless that behavior is overridden.
90 *
91 * <p>When choosing which member of a visitor family to subclass,
92 * subclassing the most recent one increases the range of source
93 * versions covered. When choosing which visitor family to subclass,
94 * consider their built-in capabilities:
95 *
96 * <ul>
97 *
98 * <li>{@link AbstractElementVisitor6 AbstractElementVisitor}s:
99 * Skeletal visitor implementations.
100 *
101 * <li>{@link SimpleElementVisitor6 SimpleElementVisitor}s: Support
102 * default actions and a default return value.
103 *
104 * <li>{@link ElementKindVisitor6 ElementKindVisitor}s: Visit methods
105 * provided on a {@linkplain Element#getKind per-kind} granularity as
106 * some categories of elements can have more than one kind.
107 *
108 * <li>{@link ElementScanner6 ElementScanner}s: Scanners are visitors
109 * which traverse an element and the elements {@linkplain
110 * Element#getEnclosedElements enclosed} by it and associated with it.
111 *
112 * </ul>
113 *
114 * @param <R> the return type of this visitor's methods. Use {@link
115 * Void} for visitors that do not need to return results.
116 * @param <P> the type of the additional parameter to this visitor's
117 * methods. Use {@code Void} for visitors that do not need an
118 * additional parameter.
119 *
120 * @author Joseph D. Darcy
121 * @author Scott Seligman
122 * @author Peter von der Ahé
123 * @since 1.6
124 */
125 public interface ElementVisitor<R, P> {
126 /**
127 * Visits an element.
128 * @param e the element to visit
129 * @param p a visitor-specified parameter
130 * @return a visitor-specified result
131 */
132 R visit(Element e, P p);
133
134 /**
135 * A convenience method equivalent to {@code visit(e, null)}.
136 *
137 * @implSpec The default implementation is {@code visit(e, null)}.
138 *
139 * @param e the element to visit
140 * @return a visitor-specified result
141 */
142 default R visit(Element e) {
143 return visit(e, null);
144 }
145
146 /**
147 * Visits a package element.
148 * @param e the element to visit
149 * @param p a visitor-specified parameter
150 * @return a visitor-specified result
151 */
152 R visitPackage(PackageElement e, P p);
153
154 /**
155 * Visits a type element.
156 * @param e the element to visit
157 * @param p a visitor-specified parameter
158 * @return a visitor-specified result
159 */
160 R visitType(TypeElement e, P p);
161
162 /**
163 * Visits a variable element.
164 * @param e the element to visit
165 * @param p a visitor-specified parameter
166 * @return a visitor-specified result
167 */
168 R visitVariable(VariableElement e, P p);
169
170 /**
171 * Visits an executable element.
172 * @param e the element to visit
173 * @param p a visitor-specified parameter
174 * @return a visitor-specified result
175 */
176 R visitExecutable(ExecutableElement e, P p);
177
178 /**
179 * Visits a type parameter element.
180 * @param e the element to visit
181 * @param p a visitor-specified parameter
182 * @return a visitor-specified result
183 */
184 R visitTypeParameter(TypeParameterElement e, P p);
185
186 /**
187 * Visits an unknown kind of element.
188 * This can occur if the language evolves and new kinds
189 * of elements are added to the {@code Element} hierarchy.
190 *
191 * @param e the element to visit
192 * @param p a visitor-specified parameter
193 * @return a visitor-specified result
194 * @throws UnknownElementException
195 * a visitor implementation may optionally throw this exception
196 */
197 R visitUnknown(Element e, P p);
198
199 /**
200 * Visits a module element.
201 *
202 * @implSpec The default implementation visits a {@code
203 * ModuleElement} by calling {@code visitUnknown(e, p)}.
204 *
205 * @param e the element to visit
206 * @param p a visitor-specified parameter
207 * @return a visitor-specified result
208 * @since 9
209 * @spec JPMS
210 */
211 default R visitModule(ModuleElement e, P p) {
212 return visitUnknown(e, p);
213 }
214
215 /**
216 * {@preview Associated with records, a preview feature of the Java language.
217 *
218 * This method is associated with <i>records</i>, a preview
219 * feature of the Java language. Preview features
220 * may be removed in a future release, or upgraded to permanent
221 * features of the Java language.}
222 *
223 * Visits a record component element.
224 *
225 * @implSpec The default implementation visits a {@code
226 * RecordComponentElement} by calling {@code visitUnknown(e, p)}.
227 *
228 * @param e the element to visit
229 * @param p a visitor-specified parameter
230 * @return a visitor-specified result
231 * @since 14
232 */
233 @jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.RECORDS,
234 essentialAPI=false)
235 @SuppressWarnings("preview")
236 default R visitRecordComponent(RecordComponentElement e, P p) {
237 return visitUnknown(e, p);
238 }
239 }