TypeVisitor.java revision 3895:4a937fde7b91 
1/*
2 * Copyright (c) 2005, 2017, 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 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 * @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 visit(t, null)}.
89     *
90     * @implSpec The default implementation is {@code visit(t, null)}.
91     *
92     * @param t the element to visit
93     * @return  a visitor-specified result
94     */
95    default R visit(TypeMirror t) {
96        return visit(t, null);
97    }
98
99    /**
100     * Visits a primitive type.
101     * @param t the type to visit
102     * @param p a visitor-specified parameter
103     * @return  a visitor-specified result
104     */
105    R visitPrimitive(PrimitiveType t, P p);
106
107    /**
108     * Visits the null type.
109     * @param t the type to visit
110     * @param p a visitor-specified parameter
111     * @return  a visitor-specified result
112     */
113    R visitNull(NullType t, P p);
114
115    /**
116     * Visits an array type.
117     * @param t the type to visit
118     * @param p a visitor-specified parameter
119     * @return  a visitor-specified result
120     */
121    R visitArray(ArrayType t, P p);
122
123    /**
124     * Visits a declared type.
125     * @param t the type to visit
126     * @param p a visitor-specified parameter
127     * @return  a visitor-specified result
128     */
129    R visitDeclared(DeclaredType t, P p);
130
131    /**
132     * Visits an error type.
133     * @param t the type to visit
134     * @param p a visitor-specified parameter
135     * @return  a visitor-specified result
136     */
137    R visitError(ErrorType t, P p);
138
139    /**
140     * Visits a type variable.
141     * @param t the type to visit
142     * @param p a visitor-specified parameter
143     * @return  a visitor-specified result
144     */
145    R visitTypeVariable(TypeVariable t, P p);
146
147    /**
148     * Visits a wildcard type.
149     * @param t the type to visit
150     * @param p a visitor-specified parameter
151     * @return  a visitor-specified result
152     */
153    R visitWildcard(WildcardType t, P p);
154
155    /**
156     * Visits an executable type.
157     * @param t the type to visit
158     * @param p a visitor-specified parameter
159     * @return  a visitor-specified result
160     */
161    R visitExecutable(ExecutableType t, P p);
162
163    /**
164     * Visits a {@link NoType} instance.
165     * @param t the type to visit
166     * @param p a visitor-specified parameter
167     * @return  a visitor-specified result
168     */
169    R visitNoType(NoType t, P p);
170
171    /**
172     * Visits an unknown kind of type.
173     * This can occur if the language evolves and new kinds
174     * of types are added to the {@code TypeMirror} hierarchy.
175     * @param t the type to visit
176     * @param p a visitor-specified parameter
177     * @return  a visitor-specified result
178     * @throws UnknownTypeException
179     *  a visitor implementation may optionally throw this exception
180     */
181    R visitUnknown(TypeMirror t, P p);
182
183    /**
184     * Visits a union type.
185     *
186     * @param t the type to visit
187     * @param p a visitor-specified parameter
188     * @return  a visitor-specified result
189     * @since 1.7
190     */
191    R visitUnion(UnionType t, P p);
192
193    /**
194     * Visits an intersection type.
195     *
196     * @param t the type to visit
197     * @param p a visitor-specified parameter
198     * @return  a visitor-specified result
199     * @since 1.8
200     */
201    R visitIntersection(IntersectionType t, P p);
202}
203