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.util; 27 28import java.lang.annotation.Annotation; 29import java.lang.annotation.AnnotationTypeMismatchException; 30import java.lang.annotation.IncompleteAnnotationException; 31import java.util.List; 32import javax.lang.model.element.*; 33import 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 */ 47public 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 * @param t the type to map to an element 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 * 73 * <p>Since annotations are only meta-data associated with a type, 74 * the set of annotations on either argument is <em>not</em> taken 75 * into account when computing whether or not two {@code 76 * TypeMirror} objects are the same type. In particular, two 77 * {@code TypeMirror} objects can have different annotations and 78 * still be considered the same. 79 * 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 94 * @throws IllegalArgumentException if given a type for an executable, package, or module 95 * @jls 4.10 Subtyping 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 106 * @throws IllegalArgumentException if given a type for an executable, package, or module 107 * @jls 5.2 Assignment Conversion 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 117 * @throws IllegalArgumentException if given a type for an executable, package, or module 118 * @jls 4.5.1.1 Type Argument Containment and Equivalence 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 130 * @jls 8.4.2 Method Signature 131 */ 132 boolean isSubsignature(ExecutableType m1, ExecutableType m2); 133 134 /** 135 * Returns the direct supertypes of a type. The interface types, if any, 136 * will appear last in the list. For an interface type with no direct 137 * super-interfaces, a type mirror representing {@code java.lang.Object} 138 * is returned. 139 * 140 * @param t the type being examined 141 * @return the direct supertypes, or an empty list if none 142 * @throws IllegalArgumentException if given a type for an executable, package, or module 143 * @jls 4.10 Subtyping 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 152 * @throws IllegalArgumentException if given a type for a package or module 153 * @jls 4.6 Type Erasure 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} 163 * @jls 5.1.7 Boxing Conversion 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 175 * @jls 5.1.8 Unboxing Conversion 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 184 * @throws IllegalArgumentException if given a type for an executable, package, or module 185 * @jls 5.1.10 Capture Conversion 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}. 209 * 210 * <p>To get the pseudo-type corresponding to a package or module, 211 * call {@code asType()} on the element modeling the {@linkplain 212 * PackageElement package} or {@linkplain ModuleElement 213 * module}. Names can be converted to elements for packages or 214 * modules using {@link Elements#getPackageElement(CharSequence)} 215 * or {@link Elements#getModuleElement(CharSequence)}, 216 * respectively. 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} 321