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