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