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