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 
  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&eacute;
  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      * @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 Contexts
 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 Type Arguments of Parameterized Types
 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 }