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