1 /*
2 * Copyright (c) 2005, 2006, 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.util;
27
28 import java.util.List;
29 import javax.lang.model.element.*;
30 import javax.lang.model.type.*;
31
32 /**
33 * Utility methods for operating on types.
34 *
35 * <p><b>Compatibility Note:</b> Methods may be added to this interface
36 * in future releases of the platform.
37 *
38 * @author Joseph D. Darcy
39 * @author Scott Seligman
40 * @author Peter von der Ahé
41 * @see javax.annotation.processing.ProcessingEnvironment#getTypeUtils
42 * @since 1.6
43 */
44 public interface Types {
45
46 /**
47 * Returns the element corresponding to a type.
48 * The type may be a {@code DeclaredType} or {@code TypeVariable}.
49 * Returns {@code null} if the type is not one with a
50 * corresponding element.
51 *
52 * @return the element corresponding to the given type
53 */
54 Element asElement(TypeMirror t);
55
56 /**
57 * Tests whether two {@code TypeMirror} objects represent the same type.
58 *
59 * <p>Caveat: if either of the arguments to this method represents a
60 * wildcard, this method will return false. As a consequence, a wildcard
61 * is not the same type as itself. This might be surprising at first,
62 * but makes sense once you consider that an example like this must be
63 * rejected by the compiler:
64 * <pre>
65 * {@code List<?> list = new ArrayList<Object>();}
66 * {@code list.add(list.get(0));}
67 * </pre>
68 *
69 * @param t1 the first type
70 * @param t2 the second type
71 * @return {@code true} if and only if the two types are the same
72 */
73 boolean isSameType(TypeMirror t1, TypeMirror t2);
74
75 /**
76 * Tests whether one type is a subtype of another.
77 * Any type is considered to be a subtype of itself.
78 *
79 * @param t1 the first type
80 * @param t2 the second type
81 * @return {@code true} if and only if the first type is a subtype
82 * of the second
83 * @throws IllegalArgumentException if given an executable or package type
84 * @jls3 4.10 Subtyping
85 */
86 boolean isSubtype(TypeMirror t1, TypeMirror t2);
87
88 /**
89 * Tests whether one type is assignable to another.
90 *
91 * @param t1 the first type
92 * @param t2 the second type
93 * @return {@code true} if and only if the first type is assignable
94 * to the second
95 * @throws IllegalArgumentException if given an executable or package type
96 * @jls3 5.2 Assignment Conversion
97 */
98 boolean isAssignable(TypeMirror t1, TypeMirror t2);
99
100 /**
101 * Tests whether one type argument <i>contains</i> another.
102 *
103 * @param t1 the first type
104 * @param t2 the second type
105 * @return {@code true} if and only if the first type contains the second
106 * @throws IllegalArgumentException if given an executable or package type
107 * @jls3 4.5.1.1 Type Argument Containment and Equivalence
108 */
109 boolean contains(TypeMirror t1, TypeMirror t2);
110
111 /**
112 * Tests whether the signature of one method is a <i>subsignature</i>
113 * of another.
114 *
115 * @param m1 the first method
116 * @param m2 the second method
117 * @return {@code true} if and only if the first signature is a
118 * subsignature of the second
119 * @jls3 8.4.2 Method Signature
120 */
121 boolean isSubsignature(ExecutableType m1, ExecutableType m2);
122
123 /**
124 * Returns the direct supertypes of a type. The interface types, if any,
125 * will appear last in the list.
126 *
127 * @param t the type being examined
128 * @return the direct supertypes, or an empty list if none
129 * @throws IllegalArgumentException if given an executable or package type
130 */
131 List<? extends TypeMirror> directSupertypes(TypeMirror t);
132
133 /**
134 * Returns the erasure of a type.
135 *
136 * @param t the type to be erased
137 * @return the erasure of the given type
138 * @throws IllegalArgumentException if given a package type
139 * @jls3 4.6 Type Erasure
140 */
141 TypeMirror erasure(TypeMirror t);
142
143 /**
144 * Returns the class of a boxed value of a given primitive type.
145 * That is, <i>boxing conversion</i> is applied.
146 *
147 * @param p the primitive type to be converted
148 * @return the class of a boxed value of type {@code p}
149 * @jls3 5.1.7 Boxing Conversion
150 */
151 TypeElement boxedClass(PrimitiveType p);
152
153 /**
154 * Returns the type (a primitive type) of unboxed values of a given type.
155 * That is, <i>unboxing conversion</i> is applied.
156 *
157 * @param t the type to be unboxed
158 * @return the type of an unboxed value of type {@code t}
159 * @throws IllegalArgumentException if the given type has no
160 * unboxing conversion
161 * @jls3 5.1.8 Unboxing Conversion
162 */
163 PrimitiveType unboxedType(TypeMirror t);
164
165 /**
166 * Applies capture conversion to a type.
167 *
168 * @param t the type to be converted
169 * @return the result of applying capture conversion
170 * @throws IllegalArgumentException if given an executable or package type
171 * @jls3 5.1.10 Capture Conversion
172 */
173 TypeMirror capture(TypeMirror t);
174
175 /**
176 * Returns a primitive type.
177 *
178 * @param kind the kind of primitive type to return
179 * @return a primitive type
180 * @throws IllegalArgumentException if {@code kind} is not a primitive kind
181 */
182 PrimitiveType getPrimitiveType(TypeKind kind);
183
184 /**
185 * Returns the null type. This is the type of {@code null}.
186 *
187 * @return the null type
188 */
189 NullType getNullType();
190
191 /**
192 * Returns a pseudo-type used where no actual type is appropriate.
193 * The kind of type to return may be either
194 * {@link TypeKind#VOID VOID} or {@link TypeKind#NONE NONE}.
195 * For packages, use
196 * {@link Elements#getPackageElement(CharSequence)}{@code .asType()}
197 * instead.
198 *
199 * @param kind the kind of type to return
200 * @return a pseudo-type of kind {@code VOID} or {@code NONE}
201 * @throws IllegalArgumentException if {@code kind} is not valid
202 */
203 NoType getNoType(TypeKind kind);
204
205 /**
206 * Returns an array type with the specified component type.
207 *
208 * @param componentType the component type
209 * @return an array type with the specified component type.
210 * @throws IllegalArgumentException if the component type is not valid for
211 * an array
212 */
213 ArrayType getArrayType(TypeMirror componentType);
214
215 /**
216 * Returns a new wildcard type argument. Either of the wildcard's
217 * bounds may be specified, or neither, but not both.
218 *
219 * @param extendsBound the extends (upper) bound, or {@code null} if none
220 * @param superBound the super (lower) bound, or {@code null} if none
221 * @return a new wildcard
222 * @throws IllegalArgumentException if bounds are not valid
223 */
224 WildcardType getWildcardType(TypeMirror extendsBound,
225 TypeMirror superBound);
226
227 /**
228 * Returns the type corresponding to a type element and
229 * actual type arguments.
230 * Given the type element for {@code Set} and the type mirror
231 * for {@code String},
232 * for example, this method may be used to get the
233 * parameterized type {@code Set<String>}.
234 *
235 * <p> The number of type arguments must either equal the
236 * number of the type element's formal type parameters, or must be
237 * zero. If zero, and if the type element is generic,
238 * then the type element's raw type is returned.
239 *
240 * <p> If a parameterized type is being returned, its type element
241 * must not be contained within a generic outer class.
242 * The parameterized type {@code Outer<String>.Inner<Number>},
243 * for example, may be constructed by first using this
244 * method to get the type {@code Outer<String>}, and then invoking
245 * {@link #getDeclaredType(DeclaredType, TypeElement, TypeMirror...)}.
246 *
247 * @param typeElem the type element
248 * @param typeArgs the actual type arguments
249 * @return the type corresponding to the type element and
250 * actual type arguments
251 * @throws IllegalArgumentException if too many or too few
252 * type arguments are given, or if an inappropriate type
253 * argument or type element is provided
254 */
255 DeclaredType getDeclaredType(TypeElement typeElem, TypeMirror... typeArgs);
256
257 /**
258 * Returns the type corresponding to a type element
259 * and actual type arguments, given a
260 * {@linkplain DeclaredType#getEnclosingType() containing type}
261 * of which it is a member.
262 * The parameterized type {@code Outer<String>.Inner<Number>},
263 * for example, may be constructed by first using
264 * {@link #getDeclaredType(TypeElement, TypeMirror...)}
265 * to get the type {@code Outer<String>}, and then invoking
266 * this method.
267 *
268 * <p> If the containing type is a parameterized type,
269 * the number of type arguments must equal the
270 * number of {@code typeElem}'s formal type parameters.
271 * If it is not parameterized or if it is {@code null}, this method is
272 * equivalent to {@code getDeclaredType(typeElem, typeArgs)}.
273 *
274 * @param containing the containing type, or {@code null} if none
275 * @param typeElem the type element
276 * @param typeArgs the actual type arguments
277 * @return the type corresponding to the type element and
278 * actual type arguments, contained within the given type
279 * @throws IllegalArgumentException if too many or too few
280 * type arguments are given, or if an inappropriate type
281 * argument, type element, or containing type is provided
282 */
283 DeclaredType getDeclaredType(DeclaredType containing,
284 TypeElement typeElem, TypeMirror... typeArgs);
285
286 /**
287 * Returns the type of an element when that element is viewed as
288 * a member of, or otherwise directly contained by, a given type.
289 * For example,
290 * when viewed as a member of the parameterized type {@code Set<String>},
291 * the {@code Set.add} method is an {@code ExecutableType}
292 * whose parameter is of type {@code String}.
293 *
294 * @param containing the containing type
295 * @param element the element
296 * @return the type of the element as viewed from the containing type
297 * @throws IllegalArgumentException if the element is not a valid one
298 * for the given type
299 */
300 TypeMirror asMemberOf(DeclaredType containing, Element element);
301 }