duke@1: /* jjg@1521: * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved. duke@1: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. duke@1: * duke@1: * This code is free software; you can redistribute it and/or modify it duke@1: * under the terms of the GNU General Public License version 2 only, as ohair@554: * published by the Free Software Foundation. Oracle designates this duke@1: * particular file as subject to the "Classpath" exception as provided ohair@554: * by Oracle in the LICENSE file that accompanied this code. duke@1: * duke@1: * This code is distributed in the hope that it will be useful, but WITHOUT duke@1: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or duke@1: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License duke@1: * version 2 for more details (a copy is included in the LICENSE file that duke@1: * accompanied this code). duke@1: * duke@1: * You should have received a copy of the GNU General Public License version duke@1: * 2 along with this work; if not, write to the Free Software Foundation, duke@1: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. duke@1: * ohair@554: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ohair@554: * or visit www.oracle.com if you need additional information or have any ohair@554: * questions. duke@1: */ duke@1: duke@1: package javax.lang.model.util; duke@1: jjg@1521: import java.lang.annotation.Annotation; jjg@1521: import java.lang.annotation.AnnotationTypeMismatchException; jjg@1521: import java.lang.annotation.IncompleteAnnotationException; duke@1: import java.util.List; duke@1: import javax.lang.model.element.*; duke@1: import javax.lang.model.type.*; duke@1: duke@1: /** duke@1: * Utility methods for operating on types. duke@1: * duke@1: *
Compatibility Note: Methods may be added to this interface duke@1: * in future releases of the platform. duke@1: * duke@1: * @author Joseph D. Darcy duke@1: * @author Scott Seligman duke@1: * @author Peter von der Ahé duke@1: * @see javax.annotation.processing.ProcessingEnvironment#getTypeUtils duke@1: * @since 1.6 duke@1: */ duke@1: public interface Types { duke@1: duke@1: /** duke@1: * Returns the element corresponding to a type. duke@1: * The type may be a {@code DeclaredType} or {@code TypeVariable}. duke@1: * Returns {@code null} if the type is not one with a duke@1: * corresponding element. duke@1: * darcy@1725: * @param t the type to map to an element duke@1: * @return the element corresponding to the given type duke@1: */ duke@1: Element asElement(TypeMirror t); duke@1: duke@1: /** duke@1: * Tests whether two {@code TypeMirror} objects represent the same type. duke@1: * jjg@1645: *
Since annotations are only meta-data associated with a type, jjg@1645: * the set of annotations on either argument is not taken jjg@1645: * into account when computing whether or not two {@code jjg@1645: * TypeMirror} objects are the same type. In particular, two jjg@1645: * {@code TypeMirror} objects can have different annotations and jjg@1645: * still be considered the same. jjg@1645: * duke@1: *
Caveat: if either of the arguments to this method represents a duke@1: * wildcard, this method will return false. As a consequence, a wildcard duke@1: * is not the same type as itself. This might be surprising at first, duke@1: * but makes sense once you consider that an example like this must be duke@1: * rejected by the compiler: duke@1: *
duke@1: * {@code List> list = new ArrayListduke@1: * duke@1: * @param t1 the first type duke@1: * @param t2 the second type duke@1: * @return {@code true} if and only if the two types are the same duke@1: */ duke@1: boolean isSameType(TypeMirror t1, TypeMirror t2); duke@1: duke@1: /** duke@1: * Tests whether one type is a subtype of another. duke@1: * Any type is considered to be a subtype of itself. duke@1: * duke@1: * @param t1 the first type duke@1: * @param t2 the second type duke@1: * @return {@code true} if and only if the first type is a subtype duke@1: * of the second duke@1: * @throws IllegalArgumentException if given an executable or package type jjh@972: * @jls 4.10 Subtyping duke@1: */ duke@1: boolean isSubtype(TypeMirror t1, TypeMirror t2); duke@1: duke@1: /** duke@1: * Tests whether one type is assignable to another. duke@1: * duke@1: * @param t1 the first type duke@1: * @param t2 the second type duke@1: * @return {@code true} if and only if the first type is assignable duke@1: * to the second duke@1: * @throws IllegalArgumentException if given an executable or package type jjh@972: * @jls 5.2 Assignment Conversion duke@1: */ duke@1: boolean isAssignable(TypeMirror t1, TypeMirror t2); duke@1: duke@1: /** duke@1: * Tests whether one type argument contains another. duke@1: * duke@1: * @param t1 the first type duke@1: * @param t2 the second type duke@1: * @return {@code true} if and only if the first type contains the second duke@1: * @throws IllegalArgumentException if given an executable or package type jjh@972: * @jls 4.5.1.1 Type Argument Containment and Equivalence duke@1: */ duke@1: boolean contains(TypeMirror t1, TypeMirror t2); duke@1: duke@1: /** duke@1: * Tests whether the signature of one method is a subsignature duke@1: * of another. duke@1: * duke@1: * @param m1 the first method duke@1: * @param m2 the second method duke@1: * @return {@code true} if and only if the first signature is a duke@1: * subsignature of the second jjh@972: * @jls 8.4.2 Method Signature duke@1: */ duke@1: boolean isSubsignature(ExecutableType m1, ExecutableType m2); duke@1: duke@1: /** duke@1: * Returns the direct supertypes of a type. The interface types, if any, duke@1: * will appear last in the list. duke@1: * duke@1: * @param t the type being examined duke@1: * @return the direct supertypes, or an empty list if none duke@1: * @throws IllegalArgumentException if given an executable or package type duke@1: */ duke@1: List extends TypeMirror> directSupertypes(TypeMirror t); duke@1: duke@1: /** duke@1: * Returns the erasure of a type. duke@1: * duke@1: * @param t the type to be erased duke@1: * @return the erasure of the given type duke@1: * @throws IllegalArgumentException if given a package type jjh@972: * @jls 4.6 Type Erasure duke@1: */ duke@1: TypeMirror erasure(TypeMirror t); duke@1: duke@1: /** duke@1: * Returns the class of a boxed value of a given primitive type. duke@1: * That is, boxing conversion is applied. duke@1: * duke@1: * @param p the primitive type to be converted duke@1: * @return the class of a boxed value of type {@code p} jjh@972: * @jls 5.1.7 Boxing Conversion duke@1: */ duke@1: TypeElement boxedClass(PrimitiveType p); duke@1: duke@1: /** duke@1: * Returns the type (a primitive type) of unboxed values of a given type. duke@1: * That is, unboxing conversion is applied. duke@1: * duke@1: * @param t the type to be unboxed duke@1: * @return the type of an unboxed value of type {@code t} duke@1: * @throws IllegalArgumentException if the given type has no duke@1: * unboxing conversion jjh@972: * @jls 5.1.8 Unboxing Conversion duke@1: */ duke@1: PrimitiveType unboxedType(TypeMirror t); duke@1: duke@1: /** duke@1: * Applies capture conversion to a type. duke@1: * duke@1: * @param t the type to be converted duke@1: * @return the result of applying capture conversion duke@1: * @throws IllegalArgumentException if given an executable or package type jjh@972: * @jls 5.1.10 Capture Conversion duke@1: */ duke@1: TypeMirror capture(TypeMirror t); duke@1: duke@1: /** duke@1: * Returns a primitive type. duke@1: * duke@1: * @param kind the kind of primitive type to return duke@1: * @return a primitive type duke@1: * @throws IllegalArgumentException if {@code kind} is not a primitive kind duke@1: */ duke@1: PrimitiveType getPrimitiveType(TypeKind kind); duke@1: duke@1: /** duke@1: * Returns the null type. This is the type of {@code null}. duke@1: * duke@1: * @return the null type duke@1: */ duke@1: NullType getNullType(); duke@1: duke@1: /** duke@1: * Returns a pseudo-type used where no actual type is appropriate. duke@1: * The kind of type to return may be either duke@1: * {@link TypeKind#VOID VOID} or {@link TypeKind#NONE NONE}. duke@1: * For packages, use duke@1: * {@link Elements#getPackageElement(CharSequence)}{@code .asType()} duke@1: * instead. duke@1: * duke@1: * @param kind the kind of type to return duke@1: * @return a pseudo-type of kind {@code VOID} or {@code NONE} duke@1: * @throws IllegalArgumentException if {@code kind} is not valid duke@1: */ duke@1: NoType getNoType(TypeKind kind); duke@1: duke@1: /** duke@1: * Returns an array type with the specified component type. duke@1: * duke@1: * @param componentType the component type duke@1: * @return an array type with the specified component type. duke@1: * @throws IllegalArgumentException if the component type is not valid for duke@1: * an array duke@1: */ duke@1: ArrayType getArrayType(TypeMirror componentType); duke@1: duke@1: /** duke@1: * Returns a new wildcard type argument. Either of the wildcard's duke@1: * bounds may be specified, or neither, but not both. duke@1: * duke@1: * @param extendsBound the extends (upper) bound, or {@code null} if none duke@1: * @param superBound the super (lower) bound, or {@code null} if none duke@1: * @return a new wildcard duke@1: * @throws IllegalArgumentException if bounds are not valid duke@1: */ duke@1: WildcardType getWildcardType(TypeMirror extendsBound, duke@1: TypeMirror superBound); duke@1: duke@1: /** duke@1: * Returns the type corresponding to a type element and duke@1: * actual type arguments. duke@1: * Given the type element for {@code Set} and the type mirror duke@1: * for {@code String}, duke@1: * for example, this method may be used to get the duke@1: * parameterized type {@code Set
The number of type arguments must either equal the duke@1: * number of the type element's formal type parameters, or must be duke@1: * zero. If zero, and if the type element is generic, duke@1: * then the type element's raw type is returned. duke@1: * duke@1: *
If a parameterized type is being returned, its type element
duke@1: * must not be contained within a generic outer class.
duke@1: * The parameterized type {@code Outer If the containing type is a parameterized type,
duke@1: * the number of type arguments must equal the
duke@1: * number of {@code typeElem}'s formal type parameters.
duke@1: * If it is not parameterized or if it is {@code null}, this method is
duke@1: * equivalent to {@code getDeclaredType(typeElem, typeArgs)}.
duke@1: *
duke@1: * @param containing the containing type, or {@code null} if none
duke@1: * @param typeElem the type element
duke@1: * @param typeArgs the actual type arguments
duke@1: * @return the type corresponding to the type element and
duke@1: * actual type arguments, contained within the given type
duke@1: * @throws IllegalArgumentException if too many or too few
duke@1: * type arguments are given, or if an inappropriate type
duke@1: * argument, type element, or containing type is provided
duke@1: */
duke@1: DeclaredType getDeclaredType(DeclaredType containing,
duke@1: TypeElement typeElem, TypeMirror... typeArgs);
duke@1:
duke@1: /**
duke@1: * Returns the type of an element when that element is viewed as
duke@1: * a member of, or otherwise directly contained by, a given type.
duke@1: * For example,
duke@1: * when viewed as a member of the parameterized type {@code Set