Types.java revision 4013:a7c2b2d0894c
1238384Sjkim/* 2238384Sjkim * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved. 3238384Sjkim * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4238384Sjkim * 5238384Sjkim * This code is free software; you can redistribute it and/or modify it 6238384Sjkim * under the terms of the GNU General Public License version 2 only, as 7238384Sjkim * published by the Free Software Foundation. Oracle designates this 8238384Sjkim * particular file as subject to the "Classpath" exception as provided 9238384Sjkim * by Oracle in the LICENSE file that accompanied this code. 10238384Sjkim * 11238384Sjkim * This code is distributed in the hope that it will be useful, but WITHOUT 12238384Sjkim * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13238384Sjkim * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14238384Sjkim * version 2 for more details (a copy is included in the LICENSE file that 15238384Sjkim * accompanied this code). 16238384Sjkim * 17238384Sjkim * You should have received a copy of the GNU General Public License version 18238384Sjkim * 2 along with this work; if not, write to the Free Software Foundation, 19238384Sjkim * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20238384Sjkim * 21238384Sjkim * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22238384Sjkim * or visit www.oracle.com if you need additional information or have any 23238384Sjkim * questions. 24238384Sjkim */ 25238384Sjkim 26238384Sjkimpackage javax.lang.model.util; 27238384Sjkim 28238384Sjkimimport java.lang.annotation.Annotation; 29238384Sjkimimport java.lang.annotation.AnnotationTypeMismatchException; 30238384Sjkimimport java.lang.annotation.IncompleteAnnotationException; 31238384Sjkimimport java.util.List; 32238384Sjkimimport javax.lang.model.element.*; 33238384Sjkimimport javax.lang.model.type.*; 34238384Sjkim 35238384Sjkim/** 36238384Sjkim * Utility methods for operating on types. 37238384Sjkim * 38238384Sjkim * <p><b>Compatibility Note:</b> Methods may be added to this interface 39238384Sjkim * in future releases of the platform. 40238384Sjkim * 41238384Sjkim * @author Joseph D. Darcy 42238384Sjkim * @author Scott Seligman 43238384Sjkim * @author Peter von der Ahé 44238384Sjkim * @see javax.annotation.processing.ProcessingEnvironment#getTypeUtils 45238384Sjkim * @since 1.6 46238384Sjkim */ 47238384Sjkimpublic interface Types { 48238384Sjkim 49238384Sjkim /** 50238384Sjkim * Returns the element corresponding to a type. 51238384Sjkim * The type may be a {@code DeclaredType} or {@code TypeVariable}. 52238384Sjkim * Returns {@code null} if the type is not one with a 53238384Sjkim * corresponding element. 54238384Sjkim * 55238384Sjkim * @param t the type to map to an element 56238384Sjkim * @return the element corresponding to the given type 57238384Sjkim */ 58238384Sjkim Element asElement(TypeMirror t); 59238384Sjkim 60238384Sjkim /** 61238384Sjkim * Tests whether two {@code TypeMirror} objects represent the same type. 62238384Sjkim * 63238384Sjkim * <p>Caveat: if either of the arguments to this method represents a 64238384Sjkim * wildcard, this method will return false. As a consequence, a wildcard 65238384Sjkim * is not the same type as itself. This might be surprising at first, 66238384Sjkim * but makes sense once you consider that an example like this must be 67238384Sjkim * rejected by the compiler: 68238384Sjkim * <pre> 69238384Sjkim * {@code List<?> list = new ArrayList<Object>();} 70238384Sjkim * {@code list.add(list.get(0));} 71238384Sjkim * </pre> 72238384Sjkim * 73238384Sjkim * <p>Since annotations are only meta-data associated with a type, 74238384Sjkim * the set of annotations on either argument is <em>not</em> taken 75238384Sjkim * into account when computing whether or not two {@code 76238384Sjkim * TypeMirror} objects are the same type. In particular, two 77238384Sjkim * {@code TypeMirror} objects can have different annotations and 78238384Sjkim * still be considered the same. 79238384Sjkim * 80238384Sjkim * @param t1 the first type 81238384Sjkim * @param t2 the second type 82238384Sjkim * @return {@code true} if and only if the two types are the same 83238384Sjkim */ 84238384Sjkim boolean isSameType(TypeMirror t1, TypeMirror t2); 85238384Sjkim 86238384Sjkim /** 87238384Sjkim * Tests whether one type is a subtype of another. 88238384Sjkim * Any type is considered to be a subtype of itself. 89238384Sjkim * 90238384Sjkim * @param t1 the first type 91238384Sjkim * @param t2 the second type 92238384Sjkim * @return {@code true} if and only if the first type is a subtype 93238384Sjkim * of the second 94238384Sjkim * @throws IllegalArgumentException if given a type for an executable, package, or module 95238384Sjkim * @jls 4.10 Subtyping 96238384Sjkim */ 97238384Sjkim boolean isSubtype(TypeMirror t1, TypeMirror t2); 98238384Sjkim 99238384Sjkim /** 100238384Sjkim * Tests whether one type is assignable to another. 101238384Sjkim * 102238384Sjkim * @param t1 the first type 103238384Sjkim * @param t2 the second type 104238384Sjkim * @return {@code true} if and only if the first type is assignable 105238384Sjkim * to the second 106238384Sjkim * @throws IllegalArgumentException if given a type for an executable, package, or module 107238384Sjkim * @jls 5.2 Assignment Conversion 108238384Sjkim */ 109238384Sjkim boolean isAssignable(TypeMirror t1, TypeMirror t2); 110238384Sjkim 111238384Sjkim /** 112238384Sjkim * Tests whether one type argument <i>contains</i> another. 113238384Sjkim * 114238384Sjkim * @param t1 the first type 115238384Sjkim * @param t2 the second type 116238384Sjkim * @return {@code true} if and only if the first type contains the second 117238384Sjkim * @throws IllegalArgumentException if given a type for an executable, package, or module 118238384Sjkim * @jls 4.5.1.1 Type Argument Containment and Equivalence 119238384Sjkim */ 120238384Sjkim boolean contains(TypeMirror t1, TypeMirror t2); 121238384Sjkim 122238384Sjkim /** 123238384Sjkim * Tests whether the signature of one method is a <i>subsignature</i> 124238384Sjkim * of another. 125238384Sjkim * 126238384Sjkim * @param m1 the first method 127238384Sjkim * @param m2 the second method 128238384Sjkim * @return {@code true} if and only if the first signature is a 129238384Sjkim * subsignature of the second 130238384Sjkim * @jls 8.4.2 Method Signature 131238384Sjkim */ 132238384Sjkim boolean isSubsignature(ExecutableType m1, ExecutableType m2); 133238384Sjkim 134238384Sjkim /** 135238384Sjkim * Returns the direct supertypes of a type. The interface types, if any, 136238384Sjkim * will appear last in the list. For an interface type with no direct 137238384Sjkim * super-interfaces, a type mirror representing {@code java.lang.Object} 138238384Sjkim * is returned. 139238384Sjkim * 140238384Sjkim * @param t the type being examined 141238384Sjkim * @return the direct supertypes, or an empty list if none 142238384Sjkim * @throws IllegalArgumentException if given a type for an executable, package, or module 143238384Sjkim * @jls 4.10 Subtyping 144238384Sjkim */ 145238384Sjkim List<? extends TypeMirror> directSupertypes(TypeMirror t); 146238384Sjkim 147238384Sjkim /** 148238384Sjkim * Returns the erasure of a type. 149238384Sjkim * 150238384Sjkim * @param t the type to be erased 151238384Sjkim * @return the erasure of the given type 152238384Sjkim * @throws IllegalArgumentException if given a type for a package or module 153238384Sjkim * @jls 4.6 Type Erasure 154238384Sjkim */ 155238384Sjkim TypeMirror erasure(TypeMirror t); 156238384Sjkim 157238384Sjkim /** 158238384Sjkim * Returns the class of a boxed value of a given primitive type. 159238384Sjkim * That is, <i>boxing conversion</i> is applied. 160238384Sjkim * 161238384Sjkim * @param p the primitive type to be converted 162238384Sjkim * @return the class of a boxed value of type {@code p} 163238384Sjkim * @jls 5.1.7 Boxing Conversion 164238384Sjkim */ 165238384Sjkim TypeElement boxedClass(PrimitiveType p); 166238384Sjkim 167238384Sjkim /** 168238384Sjkim * Returns the type (a primitive type) of unboxed values of a given type. 169238384Sjkim * That is, <i>unboxing conversion</i> is applied. 170238384Sjkim * 171238384Sjkim * @param t the type to be unboxed 172238384Sjkim * @return the type of an unboxed value of type {@code t} 173238384Sjkim * @throws IllegalArgumentException if the given type has no 174238384Sjkim * unboxing conversion 175238384Sjkim * @jls 5.1.8 Unboxing Conversion 176238384Sjkim */ 177238384Sjkim PrimitiveType unboxedType(TypeMirror t); 178238384Sjkim 179238384Sjkim /** 180238384Sjkim * Applies capture conversion to a type. 181238384Sjkim * 182238384Sjkim * @param t the type to be converted 183238384Sjkim * @return the result of applying capture conversion 184238384Sjkim * @throws IllegalArgumentException if given a type for an executable, package, or module 185238384Sjkim * @jls 5.1.10 Capture Conversion 186238384Sjkim */ 187238384Sjkim TypeMirror capture(TypeMirror t); 188238384Sjkim 189238384Sjkim /** 190238384Sjkim * Returns a primitive type. 191238384Sjkim * 192238384Sjkim * @param kind the kind of primitive type to return 193238384Sjkim * @return a primitive type 194238384Sjkim * @throws IllegalArgumentException if {@code kind} is not a primitive kind 195238384Sjkim */ 196238384Sjkim PrimitiveType getPrimitiveType(TypeKind kind); 197238384Sjkim 198238384Sjkim /** 199238384Sjkim * Returns the null type. This is the type of {@code null}. 200238384Sjkim * 201238384Sjkim * @return the null type 202238384Sjkim */ 203238384Sjkim NullType getNullType(); 204238384Sjkim 205238384Sjkim /** 206238384Sjkim * Returns a pseudo-type used where no actual type is appropriate. 207238384Sjkim * The kind of type to return may be either 208238384Sjkim * {@link TypeKind#VOID VOID} or {@link TypeKind#NONE NONE}. 209238384Sjkim * 210238384Sjkim * <p>To get the pseudo-type corresponding to a package or module, 211238384Sjkim * call {@code asType()} on the element modeling the {@linkplain 212238384Sjkim * PackageElement package} or {@linkplain ModuleElement 213238384Sjkim * module}. Names can be converted to elements for packages or 214238384Sjkim * modules using {@link Elements#getPackageElement(CharSequence)} 215238384Sjkim * or {@link Elements#getModuleElement(CharSequence)}, 216238384Sjkim * respectively. 217238384Sjkim * 218238384Sjkim * @param kind the kind of type to return 219238384Sjkim * @return a pseudo-type of kind {@code VOID} or {@code NONE} 220238384Sjkim * @throws IllegalArgumentException if {@code kind} is not valid 221238384Sjkim */ 222238384Sjkim NoType getNoType(TypeKind kind); 223238384Sjkim 224238384Sjkim /** 225238384Sjkim * Returns an array type with the specified component type. 226238384Sjkim * 227238384Sjkim * @param componentType the component type 228238384Sjkim * @return an array type with the specified component type. 229238384Sjkim * @throws IllegalArgumentException if the component type is not valid for 230238384Sjkim * an array 231238384Sjkim */ 232238384Sjkim ArrayType getArrayType(TypeMirror componentType); 233238384Sjkim 234238384Sjkim /** 235238384Sjkim * Returns a new wildcard type argument. Either of the wildcard's 236238384Sjkim * bounds may be specified, or neither, but not both. 237238384Sjkim * 238238384Sjkim * @param extendsBound the extends (upper) bound, or {@code null} if none 239238384Sjkim * @param superBound the super (lower) bound, or {@code null} if none 240238384Sjkim * @return a new wildcard 241238384Sjkim * @throws IllegalArgumentException if bounds are not valid 242238384Sjkim */ 243238384Sjkim WildcardType getWildcardType(TypeMirror extendsBound, 244238384Sjkim TypeMirror superBound); 245238384Sjkim 246238384Sjkim /** 247238384Sjkim * Returns the type corresponding to a type element and 248238384Sjkim * actual type arguments. 249238384Sjkim * Given the type element for {@code Set} and the type mirror 250238384Sjkim * for {@code String}, 251238384Sjkim * for example, this method may be used to get the 252238384Sjkim * parameterized type {@code Set<String>}. 253238384Sjkim * 254238384Sjkim * <p> The number of type arguments must either equal the 255238384Sjkim * number of the type element's formal type parameters, or must be 256238384Sjkim * zero. If zero, and if the type element is generic, 257238384Sjkim * then the type element's raw type is returned. 258238384Sjkim * 259238384Sjkim * <p> If a parameterized type is being returned, its type element 260238384Sjkim * must not be contained within a generic outer class. 261238384Sjkim * The parameterized type {@code Outer<String>.Inner<Number>}, 262238384Sjkim * for example, may be constructed by first using this 263238384Sjkim * method to get the type {@code Outer<String>}, and then invoking 264238384Sjkim * {@link #getDeclaredType(DeclaredType, TypeElement, TypeMirror...)}. 265238384Sjkim * 266238384Sjkim * @param typeElem the type element 267238384Sjkim * @param typeArgs the actual type arguments 268238384Sjkim * @return the type corresponding to the type element and 269238384Sjkim * actual type arguments 270238384Sjkim * @throws IllegalArgumentException if too many or too few 271238384Sjkim * type arguments are given, or if an inappropriate type 272238384Sjkim * argument or type element is provided 273238384Sjkim */ 274238384Sjkim DeclaredType getDeclaredType(TypeElement typeElem, TypeMirror... typeArgs); 275238384Sjkim 276238384Sjkim /** 277238384Sjkim * Returns the type corresponding to a type element 278238384Sjkim * and actual type arguments, given a 279238384Sjkim * {@linkplain DeclaredType#getEnclosingType() containing type} 280238384Sjkim * of which it is a member. 281238384Sjkim * The parameterized type {@code Outer<String>.Inner<Number>}, 282238384Sjkim * for example, may be constructed by first using 283238384Sjkim * {@link #getDeclaredType(TypeElement, TypeMirror...)} 284238384Sjkim * to get the type {@code Outer<String>}, and then invoking 285238384Sjkim * this method. 286238384Sjkim * 287238384Sjkim * <p> If the containing type is a parameterized type, 288238384Sjkim * the number of type arguments must equal the 289238384Sjkim * number of {@code typeElem}'s formal type parameters. 290238384Sjkim * If it is not parameterized or if it is {@code null}, this method is 291238384Sjkim * equivalent to {@code getDeclaredType(typeElem, typeArgs)}. 292238384Sjkim * 293238384Sjkim * @param containing the containing type, or {@code null} if none 294238384Sjkim * @param typeElem the type element 295238384Sjkim * @param typeArgs the actual type arguments 296238384Sjkim * @return the type corresponding to the type element and 297238384Sjkim * actual type arguments, contained within the given type 298238384Sjkim * @throws IllegalArgumentException if too many or too few 299238384Sjkim * type arguments are given, or if an inappropriate type 300238384Sjkim * argument, type element, or containing type is provided 301238384Sjkim */ 302238384Sjkim DeclaredType getDeclaredType(DeclaredType containing, 303238384Sjkim TypeElement typeElem, TypeMirror... typeArgs); 304238384Sjkim 305238384Sjkim /** 306238384Sjkim * Returns the type of an element when that element is viewed as 307238384Sjkim * a member of, or otherwise directly contained by, a given type. 308238384Sjkim * For example, 309238384Sjkim * when viewed as a member of the parameterized type {@code Set<String>}, 310238384Sjkim * the {@code Set.add} method is an {@code ExecutableType} 311238384Sjkim * whose parameter is of type {@code String}. 312238384Sjkim * 313238384Sjkim * @param containing the containing type 314238384Sjkim * @param element the element 315238384Sjkim * @return the type of the element as viewed from the containing type 316238384Sjkim * @throws IllegalArgumentException if the element is not a valid one 317238384Sjkim * for the given type 318238384Sjkim */ 319238384Sjkim TypeMirror asMemberOf(DeclaredType containing, Element element); 320238384Sjkim} 321238384Sjkim