Mon, 18 Mar 2013 14:40:32 -0700
8008425: Remove interim new javax.lang.model API for type-annotations
Reviewed-by: darcy
1 /*
2 * Copyright (c) 2005, 2013, 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.type;
28 import javax.lang.model.element.*;
30 /**
31 * A visitor of types, in the style of the
32 * visitor design pattern. Classes implementing this
33 * interface are used to operate on a type when the kind of
34 * type is unknown at compile time. When a visitor is passed to a
35 * type's {@link TypeMirror#accept accept} method, the <tt>visit<i>XYZ</i></tt>
36 * method most applicable to that type 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 are required to
60 * also be runnable on Java SE 7. Therefore, default methods
61 * <em>cannot</em> be used when extending {@code javax.lang.model.*}
62 * to cover Java SE 8 language features. However, default methods may
63 * be 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 * @param <R> the return type of this visitor's methods. Use {@link
68 * Void} for visitors that do not need to return results.
69 * @param <P> the type of the additional parameter to this visitor's
70 * methods. Use {@code Void} for visitors that do not need an
71 * additional parameter.
72 *
73 * @author Joseph D. Darcy
74 * @author Scott Seligman
75 * @author Peter von der Ahé
76 * @since 1.6
77 */
78 public interface TypeVisitor<R, P> {
79 /**
80 * Visits a type.
81 * @param t the type to visit
82 * @param p a visitor-specified parameter
83 * @return a visitor-specified result
84 */
85 R visit(TypeMirror t, P p);
87 /**
88 * A convenience method equivalent to {@code v.visit(t, null)}.
89 * @param t the element to visit
90 * @return a visitor-specified result
91 */
92 R visit(TypeMirror t);
94 /**
95 * Visits a primitive type.
96 * @param t the type to visit
97 * @param p a visitor-specified parameter
98 * @return a visitor-specified result
99 */
100 R visitPrimitive(PrimitiveType t, P p);
102 /**
103 * Visits the null type.
104 * @param t the type to visit
105 * @param p a visitor-specified parameter
106 * @return a visitor-specified result
107 */
108 R visitNull(NullType t, P p);
110 /**
111 * Visits an array type.
112 * @param t the type to visit
113 * @param p a visitor-specified parameter
114 * @return a visitor-specified result
115 */
116 R visitArray(ArrayType t, P p);
118 /**
119 * Visits a declared type.
120 * @param t the type to visit
121 * @param p a visitor-specified parameter
122 * @return a visitor-specified result
123 */
124 R visitDeclared(DeclaredType t, P p);
126 /**
127 * Visits an error type.
128 * @param t the type to visit
129 * @param p a visitor-specified parameter
130 * @return a visitor-specified result
131 */
132 R visitError(ErrorType t, P p);
134 /**
135 * Visits a type variable.
136 * @param t the type to visit
137 * @param p a visitor-specified parameter
138 * @return a visitor-specified result
139 */
140 R visitTypeVariable(TypeVariable t, P p);
142 /**
143 * Visits a wildcard type.
144 * @param t the type to visit
145 * @param p a visitor-specified parameter
146 * @return a visitor-specified result
147 */
148 R visitWildcard(WildcardType t, P p);
150 /**
151 * Visits an executable type.
152 * @param t the type to visit
153 * @param p a visitor-specified parameter
154 * @return a visitor-specified result
155 */
156 R visitExecutable(ExecutableType t, P p);
158 /**
159 * Visits a {@link NoType} instance.
160 * @param t the type to visit
161 * @param p a visitor-specified parameter
162 * @return a visitor-specified result
163 */
164 R visitNoType(NoType t, P p);
166 /**
167 * Visits an unknown kind of type.
168 * This can occur if the language evolves and new kinds
169 * of types are added to the {@code TypeMirror} hierarchy.
170 * @param t the type to visit
171 * @param p a visitor-specified parameter
172 * @return a visitor-specified result
173 * @throws UnknownTypeException
174 * a visitor implementation may optionally throw this exception
175 */
176 R visitUnknown(TypeMirror t, P p);
178 /**
179 * Visits a union type.
180 *
181 * @param t the type to visit
182 * @param p a visitor-specified parameter
183 * @return a visitor-specified result
184 * @since 1.7
185 */
186 R visitUnion(UnionType t, P p);
188 /**
189 * Visits an intersection type.
190 *
191 * @param t the type to visit
192 * @param p a visitor-specified parameter
193 * @return a visitor-specified result
194 * @since 1.8
195 */
196 R visitIntersection(IntersectionType t, P p);
197 }