author | darcy |
Wed, 22 Feb 2017 12:01:15 -0800 | |
changeset 44014 | 56d15b6333fc |
parent 25874 | 83c19f00452c |
permissions | -rw-r--r-- |
10 | 1 |
/* |
44014
56d15b6333fc
8175335: Improve handling of module types in javax.lang.model.util.Types
darcy
parents:
25874
diff
changeset
|
2 |
* Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved. |
10 | 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 |
|
5520 | 7 |
* published by the Free Software Foundation. Oracle designates this |
10 | 8 |
* particular file as subject to the "Classpath" exception as provided |
5520 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
10 | 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 |
* |
|
5520 | 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. |
|
10 | 24 |
*/ |
25 |
||
26 |
package javax.lang.model.util; |
|
27 |
||
15385 | 28 |
import java.lang.annotation.Annotation; |
29 |
import java.lang.annotation.AnnotationTypeMismatchException; |
|
30 |
import java.lang.annotation.IncompleteAnnotationException; |
|
10 | 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 |
* |
|
17548 | 55 |
* @param t the type to map to an element |
10 | 56 |
* @return the element corresponding to the given type |
57 |
*/ |
|
58 |
Element asElement(TypeMirror t); |
|
59 |
||
60 |
/** |
|
61 |
* Tests whether two {@code TypeMirror} objects represent the same type. |
|
62 |
* |
|
63 |
* <p>Caveat: if either of the arguments to this method represents a |
|
64 |
* wildcard, this method will return false. As a consequence, a wildcard |
|
65 |
* is not the same type as itself. This might be surprising at first, |
|
66 |
* but makes sense once you consider that an example like this must be |
|
67 |
* rejected by the compiler: |
|
68 |
* <pre> |
|
69 |
* {@code List<?> list = new ArrayList<Object>();} |
|
70 |
* {@code list.add(list.get(0));} |
|
71 |
* </pre> |
|
72 |
* |
|
22156
8eefa8ab3f41
8030080: Correct misstatement in JSR 269 MR (in javax.lang.model)
darcy
parents:
17548
diff
changeset
|
73 |
* <p>Since annotations are only meta-data associated with a type, |
8eefa8ab3f41
8030080: Correct misstatement in JSR 269 MR (in javax.lang.model)
darcy
parents:
17548
diff
changeset
|
74 |
* the set of annotations on either argument is <em>not</em> taken |
8eefa8ab3f41
8030080: Correct misstatement in JSR 269 MR (in javax.lang.model)
darcy
parents:
17548
diff
changeset
|
75 |
* into account when computing whether or not two {@code |
8eefa8ab3f41
8030080: Correct misstatement in JSR 269 MR (in javax.lang.model)
darcy
parents:
17548
diff
changeset
|
76 |
* TypeMirror} objects are the same type. In particular, two |
8eefa8ab3f41
8030080: Correct misstatement in JSR 269 MR (in javax.lang.model)
darcy
parents:
17548
diff
changeset
|
77 |
* {@code TypeMirror} objects can have different annotations and |
8eefa8ab3f41
8030080: Correct misstatement in JSR 269 MR (in javax.lang.model)
darcy
parents:
17548
diff
changeset
|
78 |
* still be considered the same. |
8eefa8ab3f41
8030080: Correct misstatement in JSR 269 MR (in javax.lang.model)
darcy
parents:
17548
diff
changeset
|
79 |
* |
10 | 80 |
* @param t1 the first type |
81 |
* @param t2 the second type |
|
82 |
* @return {@code true} if and only if the two types are the same |
|
83 |
*/ |
|
84 |
boolean isSameType(TypeMirror t1, TypeMirror t2); |
|
85 |
||
86 |
/** |
|
87 |
* Tests whether one type is a subtype of another. |
|
88 |
* Any type is considered to be a subtype of itself. |
|
89 |
* |
|
90 |
* @param t1 the first type |
|
91 |
* @param t2 the second type |
|
92 |
* @return {@code true} if and only if the first type is a subtype |
|
93 |
* of the second |
|
44014
56d15b6333fc
8175335: Improve handling of module types in javax.lang.model.util.Types
darcy
parents:
25874
diff
changeset
|
94 |
* @throws IllegalArgumentException if given a type for an executable, package, or module |
9303
eae35c201e19
7032975: API files in javax.annotation.processing need to be updated for references to JLS
jjh
parents:
8235
diff
changeset
|
95 |
* @jls 4.10 Subtyping |
10 | 96 |
*/ |
97 |
boolean isSubtype(TypeMirror t1, TypeMirror t2); |
|
98 |
||
99 |
/** |
|
100 |
* Tests whether one type is assignable to another. |
|
101 |
* |
|
102 |
* @param t1 the first type |
|
103 |
* @param t2 the second type |
|
104 |
* @return {@code true} if and only if the first type is assignable |
|
105 |
* to the second |
|
44014
56d15b6333fc
8175335: Improve handling of module types in javax.lang.model.util.Types
darcy
parents:
25874
diff
changeset
|
106 |
* @throws IllegalArgumentException if given a type for an executable, package, or module |
9303
eae35c201e19
7032975: API files in javax.annotation.processing need to be updated for references to JLS
jjh
parents:
8235
diff
changeset
|
107 |
* @jls 5.2 Assignment Conversion |
10 | 108 |
*/ |
109 |
boolean isAssignable(TypeMirror t1, TypeMirror t2); |
|
110 |
||
111 |
/** |
|
112 |
* Tests whether one type argument <i>contains</i> another. |
|
113 |
* |
|
114 |
* @param t1 the first type |
|
115 |
* @param t2 the second type |
|
116 |
* @return {@code true} if and only if the first type contains the second |
|
44014
56d15b6333fc
8175335: Improve handling of module types in javax.lang.model.util.Types
darcy
parents:
25874
diff
changeset
|
117 |
* @throws IllegalArgumentException if given a type for an executable, package, or module |
9303
eae35c201e19
7032975: API files in javax.annotation.processing need to be updated for references to JLS
jjh
parents:
8235
diff
changeset
|
118 |
* @jls 4.5.1.1 Type Argument Containment and Equivalence |
10 | 119 |
*/ |
120 |
boolean contains(TypeMirror t1, TypeMirror t2); |
|
121 |
||
122 |
/** |
|
123 |
* Tests whether the signature of one method is a <i>subsignature</i> |
|
124 |
* of another. |
|
125 |
* |
|
126 |
* @param m1 the first method |
|
127 |
* @param m2 the second method |
|
128 |
* @return {@code true} if and only if the first signature is a |
|
129 |
* subsignature of the second |
|
9303
eae35c201e19
7032975: API files in javax.annotation.processing need to be updated for references to JLS
jjh
parents:
8235
diff
changeset
|
130 |
* @jls 8.4.2 Method Signature |
10 | 131 |
*/ |
132 |
boolean isSubsignature(ExecutableType m1, ExecutableType m2); |
|
133 |
||
134 |
/** |
|
23804
b5632efbc768
8034933: Update documentation for Types.directSupertypes to clarify behavior
pgovereau
parents:
22156
diff
changeset
|
135 |
* Returns the direct supertypes of a type. The interface types, if any, |
b5632efbc768
8034933: Update documentation for Types.directSupertypes to clarify behavior
pgovereau
parents:
22156
diff
changeset
|
136 |
* will appear last in the list. For an interface type with no direct |
b5632efbc768
8034933: Update documentation for Types.directSupertypes to clarify behavior
pgovereau
parents:
22156
diff
changeset
|
137 |
* super-interfaces, a type mirror representing {@code java.lang.Object} |
b5632efbc768
8034933: Update documentation for Types.directSupertypes to clarify behavior
pgovereau
parents:
22156
diff
changeset
|
138 |
* is returned. |
10 | 139 |
* |
140 |
* @param t the type being examined |
|
141 |
* @return the direct supertypes, or an empty list if none |
|
44014
56d15b6333fc
8175335: Improve handling of module types in javax.lang.model.util.Types
darcy
parents:
25874
diff
changeset
|
142 |
* @throws IllegalArgumentException if given a type for an executable, package, or module |
23804
b5632efbc768
8034933: Update documentation for Types.directSupertypes to clarify behavior
pgovereau
parents:
22156
diff
changeset
|
143 |
* @jls 4.10 Subtyping |
10 | 144 |
*/ |
145 |
List<? extends TypeMirror> directSupertypes(TypeMirror t); |
|
146 |
||
147 |
/** |
|
148 |
* Returns the erasure of a type. |
|
149 |
* |
|
150 |
* @param t the type to be erased |
|
151 |
* @return the erasure of the given type |
|
44014
56d15b6333fc
8175335: Improve handling of module types in javax.lang.model.util.Types
darcy
parents:
25874
diff
changeset
|
152 |
* @throws IllegalArgumentException if given a type for a package or module |
9303
eae35c201e19
7032975: API files in javax.annotation.processing need to be updated for references to JLS
jjh
parents:
8235
diff
changeset
|
153 |
* @jls 4.6 Type Erasure |
10 | 154 |
*/ |
155 |
TypeMirror erasure(TypeMirror t); |
|
156 |
||
157 |
/** |
|
158 |
* Returns the class of a boxed value of a given primitive type. |
|
159 |
* That is, <i>boxing conversion</i> is applied. |
|
160 |
* |
|
161 |
* @param p the primitive type to be converted |
|
162 |
* @return the class of a boxed value of type {@code p} |
|
9303
eae35c201e19
7032975: API files in javax.annotation.processing need to be updated for references to JLS
jjh
parents:
8235
diff
changeset
|
163 |
* @jls 5.1.7 Boxing Conversion |
10 | 164 |
*/ |
165 |
TypeElement boxedClass(PrimitiveType p); |
|
166 |
||
167 |
/** |
|
168 |
* Returns the type (a primitive type) of unboxed values of a given type. |
|
169 |
* That is, <i>unboxing conversion</i> is applied. |
|
170 |
* |
|
171 |
* @param t the type to be unboxed |
|
172 |
* @return the type of an unboxed value of type {@code t} |
|
173 |
* @throws IllegalArgumentException if the given type has no |
|
174 |
* unboxing conversion |
|
9303
eae35c201e19
7032975: API files in javax.annotation.processing need to be updated for references to JLS
jjh
parents:
8235
diff
changeset
|
175 |
* @jls 5.1.8 Unboxing Conversion |
10 | 176 |
*/ |
177 |
PrimitiveType unboxedType(TypeMirror t); |
|
178 |
||
179 |
/** |
|
180 |
* Applies capture conversion to a type. |
|
181 |
* |
|
182 |
* @param t the type to be converted |
|
183 |
* @return the result of applying capture conversion |
|
44014
56d15b6333fc
8175335: Improve handling of module types in javax.lang.model.util.Types
darcy
parents:
25874
diff
changeset
|
184 |
* @throws IllegalArgumentException if given a type for an executable, package, or module |
9303
eae35c201e19
7032975: API files in javax.annotation.processing need to be updated for references to JLS
jjh
parents:
8235
diff
changeset
|
185 |
* @jls 5.1.10 Capture Conversion |
10 | 186 |
*/ |
187 |
TypeMirror capture(TypeMirror t); |
|
188 |
||
189 |
/** |
|
190 |
* Returns a primitive type. |
|
191 |
* |
|
192 |
* @param kind the kind of primitive type to return |
|
193 |
* @return a primitive type |
|
194 |
* @throws IllegalArgumentException if {@code kind} is not a primitive kind |
|
195 |
*/ |
|
196 |
PrimitiveType getPrimitiveType(TypeKind kind); |
|
197 |
||
198 |
/** |
|
199 |
* Returns the null type. This is the type of {@code null}. |
|
200 |
* |
|
201 |
* @return the null type |
|
202 |
*/ |
|
203 |
NullType getNullType(); |
|
204 |
||
205 |
/** |
|
206 |
* Returns a pseudo-type used where no actual type is appropriate. |
|
207 |
* The kind of type to return may be either |
|
208 |
* {@link TypeKind#VOID VOID} or {@link TypeKind#NONE NONE}. |
|
44014
56d15b6333fc
8175335: Improve handling of module types in javax.lang.model.util.Types
darcy
parents:
25874
diff
changeset
|
209 |
* |
56d15b6333fc
8175335: Improve handling of module types in javax.lang.model.util.Types
darcy
parents:
25874
diff
changeset
|
210 |
* <p>To get the pseudo-type corresponding to a package or module, |
56d15b6333fc
8175335: Improve handling of module types in javax.lang.model.util.Types
darcy
parents:
25874
diff
changeset
|
211 |
* call {@code asType()} on the element modeling the {@linkplain |
56d15b6333fc
8175335: Improve handling of module types in javax.lang.model.util.Types
darcy
parents:
25874
diff
changeset
|
212 |
* PackageElement package} or {@linkplain ModuleElement |
56d15b6333fc
8175335: Improve handling of module types in javax.lang.model.util.Types
darcy
parents:
25874
diff
changeset
|
213 |
* module}. Names can be converted to elements for packages or |
56d15b6333fc
8175335: Improve handling of module types in javax.lang.model.util.Types
darcy
parents:
25874
diff
changeset
|
214 |
* modules using {@link Elements#getPackageElement(CharSequence)} |
56d15b6333fc
8175335: Improve handling of module types in javax.lang.model.util.Types
darcy
parents:
25874
diff
changeset
|
215 |
* or {@link Elements#getModuleElement(CharSequence)}, |
56d15b6333fc
8175335: Improve handling of module types in javax.lang.model.util.Types
darcy
parents:
25874
diff
changeset
|
216 |
* respectively. |
10 | 217 |
* |
218 |
* @param kind the kind of type to return |
|
219 |
* @return a pseudo-type of kind {@code VOID} or {@code NONE} |
|
220 |
* @throws IllegalArgumentException if {@code kind} is not valid |
|
221 |
*/ |
|
222 |
NoType getNoType(TypeKind kind); |
|
223 |
||
224 |
/** |
|
225 |
* Returns an array type with the specified component type. |
|
226 |
* |
|
227 |
* @param componentType the component type |
|
228 |
* @return an array type with the specified component type. |
|
229 |
* @throws IllegalArgumentException if the component type is not valid for |
|
230 |
* an array |
|
231 |
*/ |
|
232 |
ArrayType getArrayType(TypeMirror componentType); |
|
233 |
||
234 |
/** |
|
235 |
* Returns a new wildcard type argument. Either of the wildcard's |
|
236 |
* bounds may be specified, or neither, but not both. |
|
237 |
* |
|
238 |
* @param extendsBound the extends (upper) bound, or {@code null} if none |
|
239 |
* @param superBound the super (lower) bound, or {@code null} if none |
|
240 |
* @return a new wildcard |
|
241 |
* @throws IllegalArgumentException if bounds are not valid |
|
242 |
*/ |
|
243 |
WildcardType getWildcardType(TypeMirror extendsBound, |
|
244 |
TypeMirror superBound); |
|
245 |
||
246 |
/** |
|
247 |
* Returns the type corresponding to a type element and |
|
248 |
* actual type arguments. |
|
249 |
* Given the type element for {@code Set} and the type mirror |
|
250 |
* for {@code String}, |
|
251 |
* for example, this method may be used to get the |
|
252 |
* parameterized type {@code Set<String>}. |
|
253 |
* |
|
254 |
* <p> The number of type arguments must either equal the |
|
255 |
* number of the type element's formal type parameters, or must be |
|
256 |
* zero. If zero, and if the type element is generic, |
|
257 |
* then the type element's raw type is returned. |
|
258 |
* |
|
259 |
* <p> If a parameterized type is being returned, its type element |
|
260 |
* must not be contained within a generic outer class. |
|
261 |
* The parameterized type {@code Outer<String>.Inner<Number>}, |
|
262 |
* for example, may be constructed by first using this |
|
263 |
* method to get the type {@code Outer<String>}, and then invoking |
|
264 |
* {@link #getDeclaredType(DeclaredType, TypeElement, TypeMirror...)}. |
|
265 |
* |
|
266 |
* @param typeElem the type element |
|
267 |
* @param typeArgs the actual type arguments |
|
268 |
* @return the type corresponding to the type element and |
|
269 |
* actual type arguments |
|
270 |
* @throws IllegalArgumentException if too many or too few |
|
271 |
* type arguments are given, or if an inappropriate type |
|
272 |
* argument or type element is provided |
|
273 |
*/ |
|
274 |
DeclaredType getDeclaredType(TypeElement typeElem, TypeMirror... typeArgs); |
|
275 |
||
276 |
/** |
|
277 |
* Returns the type corresponding to a type element |
|
278 |
* and actual type arguments, given a |
|
279 |
* {@linkplain DeclaredType#getEnclosingType() containing type} |
|
280 |
* of which it is a member. |
|
281 |
* The parameterized type {@code Outer<String>.Inner<Number>}, |
|
282 |
* for example, may be constructed by first using |
|
283 |
* {@link #getDeclaredType(TypeElement, TypeMirror...)} |
|
284 |
* to get the type {@code Outer<String>}, and then invoking |
|
285 |
* this method. |
|
286 |
* |
|
287 |
* <p> If the containing type is a parameterized type, |
|
288 |
* the number of type arguments must equal the |
|
289 |
* number of {@code typeElem}'s formal type parameters. |
|
290 |
* If it is not parameterized or if it is {@code null}, this method is |
|
291 |
* equivalent to {@code getDeclaredType(typeElem, typeArgs)}. |
|
292 |
* |
|
293 |
* @param containing the containing type, or {@code null} if none |
|
294 |
* @param typeElem the type element |
|
295 |
* @param typeArgs the actual type arguments |
|
296 |
* @return the type corresponding to the type element and |
|
297 |
* actual type arguments, contained within the given type |
|
298 |
* @throws IllegalArgumentException if too many or too few |
|
299 |
* type arguments are given, or if an inappropriate type |
|
300 |
* argument, type element, or containing type is provided |
|
301 |
*/ |
|
302 |
DeclaredType getDeclaredType(DeclaredType containing, |
|
303 |
TypeElement typeElem, TypeMirror... typeArgs); |
|
304 |
||
305 |
/** |
|
306 |
* Returns the type of an element when that element is viewed as |
|
307 |
* a member of, or otherwise directly contained by, a given type. |
|
308 |
* For example, |
|
309 |
* when viewed as a member of the parameterized type {@code Set<String>}, |
|
310 |
* the {@code Set.add} method is an {@code ExecutableType} |
|
311 |
* whose parameter is of type {@code String}. |
|
312 |
* |
|
313 |
* @param containing the containing type |
|
314 |
* @param element the element |
|
315 |
* @return the type of the element as viewed from the containing type |
|
316 |
* @throws IllegalArgumentException if the element is not a valid one |
|
317 |
* for the given type |
|
318 |
*/ |
|
319 |
TypeMirror asMemberOf(DeclaredType containing, Element element); |
|
320 |
} |