TypeVisitor.java revision 3870:f5dc63258a43 
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 */
25
26package javax.lang.model.type;
27
28import javax.lang.model.element.*;
29
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 <code>visit<i>XYZ</i></code>
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&trade; 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&eacute;
76 * @since 1.6
77 */
78public 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);
86
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);
93
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);
101
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);
109
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);
117
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);
125
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);
133
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);
141
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);
149
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);
157
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);
165
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);
177
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);
187
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}
198