https://openjdk.java.net/ 
/*
 * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.lang.model.util;

import java.lang.annotation.Annotation;
import java.lang.annotation.AnnotationTypeMismatchException;
import java.lang.annotation.IncompleteAnnotationException;
import java.util.List;
import javax.lang.model.element.*;
import javax.lang.model.type.*;


Utility methods for operating on types.

Compatibility Note: Methods may be added to this interface
in future releases of the platform.

Author:Joseph D. Darcy, Scott Seligman, Peter von der Ahé
See Also:
Since:1.6
/**
 * Utility methods for operating on types.
 *
 * <p><b>Compatibility Note:</b> Methods may be added to this interface
 * in future releases of the platform.
 *
 * @author Joseph D. Darcy
 * @author Scott Seligman
 * @author Peter von der Ah&eacute;
 * @see javax.annotation.processing.ProcessingEnvironment#getTypeUtils
 * @since 1.6
 */
public interface Types {

    
Returns the element corresponding to a type. The type may be a DeclaredType or TypeVariable. Returns null if the type is not one with a corresponding element. 
Params:
  • t – the type to map to an element
Returns:the element corresponding to the given type
/**
     * Returns the element corresponding to a type.
     * The type may be a {@code DeclaredType} or {@code TypeVariable}.
     * Returns {@code null} if the type is not one with a
     * corresponding element.
     *
     * @param t the type to map to an element
     * @return the element corresponding to the given type
     */
    Element asElement(TypeMirror t);

    
Tests whether two TypeMirror objects represent the same type. 
Caveat: if either of the arguments to this method represents a
wildcard, this method will return false.  As a consequence, a wildcard
is not the same type as itself.  This might be surprising at first,
but makes sense once you consider that an example like this must be
rejected by the compiler:

 List<?> list = new ArrayList<Object>(); list.add(list.get(0)); 


Since annotations are only meta-data associated with a type,
the set of annotations on either argument is not taken into account when computing whether or not two 
TypeMirror objects are the same type. In particular, two TypeMirror objects can have different annotations and still be considered the same. 
Params:
  • t1 –  the first type
  • t2 –  the second type
Returns:true if and only if the two types are the same
/**
     * Tests whether two {@code TypeMirror} objects represent the same type.
     *
     * <p>Caveat: if either of the arguments to this method represents a
     * wildcard, this method will return false.  As a consequence, a wildcard
     * is not the same type as itself.  This might be surprising at first,
     * but makes sense once you consider that an example like this must be
     * rejected by the compiler:
     * <pre>
     *   {@code List<?> list = new ArrayList<Object>();}
     *   {@code list.add(list.get(0));}
     * </pre>
     *
     * <p>Since annotations are only meta-data associated with a type,
     * the set of annotations on either argument is <em>not</em> taken
     * into account when computing whether or not two {@code
     * TypeMirror} objects are the same type. In particular, two
     * {@code TypeMirror} objects can have different annotations and
     * still be considered the same.
     *
     * @param t1  the first type
     * @param t2  the second type
     * @return {@code true} if and only if the two types are the same
     */
    boolean isSameType(TypeMirror t1, TypeMirror t2);

    
Tests whether one type is a subtype of another.
Any type is considered to be a subtype of itself.

Params:
  • t1 –  the first type
  • t2 –  the second type
Throws:
Returns:true if and only if the first type is a subtype of the second
@jls4.10 Subtyping
/**
     * Tests whether one type is a subtype of another.
     * Any type is considered to be a subtype of itself.
     *
     * @param t1  the first type
     * @param t2  the second type
     * @return {@code true} if and only if the first type is a subtype
     *          of the second
     * @throws IllegalArgumentException if given a type for an executable, package, or module
     * @jls 4.10 Subtyping
     */
    boolean isSubtype(TypeMirror t1, TypeMirror t2);

    
Tests whether one type is assignable to another.

Params:
  • t1 –  the first type
  • t2 –  the second type
Throws:
Returns:true if and only if the first type is assignable to the second
@jls5.2 Assignment Conversion
/**
     * Tests whether one type is assignable to another.
     *
     * @param t1  the first type
     * @param t2  the second type
     * @return {@code true} if and only if the first type is assignable
     *          to the second
     * @throws IllegalArgumentException if given a type for an executable, package, or module
     * @jls 5.2 Assignment Conversion
     */
    boolean isAssignable(TypeMirror t1, TypeMirror t2);

    
Tests whether one type argument contains another.

Params:
  • t1 –  the first type
  • t2 –  the second type
Throws:
Returns:true if and only if the first type contains the second
@jls4.5.1.1 Type Argument Containment and Equivalence
/**
     * Tests whether one type argument <i>contains</i> another.
     *
     * @param t1  the first type
     * @param t2  the second type
     * @return {@code true} if and only if the first type contains the second
     * @throws IllegalArgumentException if given a type for an executable, package, or module
     * @jls 4.5.1.1 Type Argument Containment and Equivalence
     */
    boolean contains(TypeMirror t1, TypeMirror t2);

    
Tests whether the signature of one method is a subsignature
of another.

Params:
  • m1 –  the first method
  • m2 –  the second method
Returns:true if and only if the first signature is a subsignature of the second
@jls8.4.2 Method Signature
/**
     * Tests whether the signature of one method is a <i>subsignature</i>
     * of another.
     *
     * @param m1  the first method
     * @param m2  the second method
     * @return {@code true} if and only if the first signature is a
     *          subsignature of the second
     * @jls 8.4.2 Method Signature
     */
    boolean isSubsignature(ExecutableType m1, ExecutableType m2);

    
Returns the direct supertypes of a type. The interface types, if any, will appear last in the list. For an interface type with no direct super-interfaces, a type mirror representing java.lang.Object is returned. 
Params:
  • t –  the type being examined
Throws:
Returns:the direct supertypes, or an empty list if none
@jls4.10 Subtyping
/**
     * Returns the direct supertypes of a type. The interface types, if any,
     * will appear last in the list. For an interface type with no direct
     * super-interfaces, a type mirror representing {@code java.lang.Object}
     * is returned.
     *
     * @param t  the type being examined
     * @return the direct supertypes, or an empty list if none
     * @throws IllegalArgumentException if given a type for an executable, package, or module
     * @jls 4.10 Subtyping
     */
    List<? extends TypeMirror> directSupertypes(TypeMirror t);

    
Returns the erasure of a type.

Params:
  • t –  the type to be erased
Throws:
Returns:the erasure of the given type
@jls4.6 Type Erasure
/**
     * Returns the erasure of a type.
     *
     * @param t  the type to be erased
     * @return the erasure of the given type
     * @throws IllegalArgumentException if given a type for a package or module
     * @jls 4.6 Type Erasure
     */
    TypeMirror erasure(TypeMirror t);

    
Returns the class of a boxed value of a given primitive type.
That is, boxing conversion is applied.

Params:
  • p –  the primitive type to be converted
Returns:the class of a boxed value of type p
@jls5.1.7 Boxing Conversion
/**
     * Returns the class of a boxed value of a given primitive type.
     * That is, <i>boxing conversion</i> is applied.
     *
     * @param p  the primitive type to be converted
     * @return the class of a boxed value of type {@code p}
     * @jls 5.1.7 Boxing Conversion
     */
    TypeElement boxedClass(PrimitiveType p);

    
Returns the type (a primitive type) of unboxed values of a given type.
That is, unboxing conversion is applied.

Params:
  • t –  the type to be unboxed
Throws:
Returns:the type of an unboxed value of type t
@jls5.1.8 Unboxing Conversion
/**
     * Returns the type (a primitive type) of unboxed values of a given type.
     * That is, <i>unboxing conversion</i> is applied.
     *
     * @param t  the type to be unboxed
     * @return the type of an unboxed value of type {@code t}
     * @throws IllegalArgumentException if the given type has no
     *          unboxing conversion
     * @jls 5.1.8 Unboxing Conversion
     */
    PrimitiveType unboxedType(TypeMirror t);

    
Applies capture conversion to a type.

Params:
  • t –  the type to be converted
Throws:
Returns:the result of applying capture conversion
@jls5.1.10 Capture Conversion
/**
     * Applies capture conversion to a type.
     *
     * @param t  the type to be converted
     * @return the result of applying capture conversion
     * @throws IllegalArgumentException if given a type for an executable, package, or module
     * @jls 5.1.10 Capture Conversion
     */
    TypeMirror capture(TypeMirror t);

    
Returns a primitive type.

Params:
  • kind –  the kind of primitive type to return
Throws:
Returns:a primitive type
/**
     * Returns a primitive type.
     *
     * @param kind  the kind of primitive type to return
     * @return a primitive type
     * @throws IllegalArgumentException if {@code kind} is not a primitive kind
     */
    PrimitiveType getPrimitiveType(TypeKind kind);

    
Returns the null type. This is the type of null. 
Returns:the null type
/**
     * Returns the null type.  This is the type of {@code null}.
     *
     * @return the null type
     */
    NullType getNullType();

    
Returns a pseudo-type used where no actual type is appropriate. The kind of type to return may be either VOID or NONE. 
To get the pseudo-type corresponding to a package or module, call asType() on the element modeling the package or 
module. Names can be converted to elements for packages or modules using Elements.getPackageElement(CharSequence) or Elements.getModuleElement(CharSequence), respectively. 
Params:
  • kind –  the kind of type to return
Throws:
Returns:a pseudo-type of kind VOID or NONE
/**
     * Returns a pseudo-type used where no actual type is appropriate.
     * The kind of type to return may be either
     * {@link TypeKind#VOID VOID} or {@link TypeKind#NONE NONE}.
     *
     * <p>To get the pseudo-type corresponding to a package or module,
     * call {@code asType()} on the element modeling the {@linkplain
     * PackageElement package} or {@linkplain ModuleElement
     * module}. Names can be converted to elements for packages or
     * modules using {@link Elements#getPackageElement(CharSequence)}
     * or {@link Elements#getModuleElement(CharSequence)},
     * respectively.
     *
     * @param kind  the kind of type to return
     * @return a pseudo-type of kind {@code VOID} or {@code NONE}
     * @throws IllegalArgumentException if {@code kind} is not valid
     */
    NoType getNoType(TypeKind kind);

    
Returns an array type with the specified component type.

Params:
  • componentType –  the component type
Throws:
Returns:an array type with the specified component type.
/**
     * Returns an array type with the specified component type.
     *
     * @param componentType  the component type
     * @return an array type with the specified component type.
     * @throws IllegalArgumentException if the component type is not valid for
     *          an array
     */
    ArrayType getArrayType(TypeMirror componentType);

    
Returns a new wildcard type argument.  Either of the wildcard's
bounds may be specified, or neither, but not both.

Params:
  • extendsBound –  the extends (upper) bound, or null if none
  • superBound –  the super (lower) bound, or null if none
Throws:
Returns:a new wildcard
/**
     * Returns a new wildcard type argument.  Either of the wildcard's
     * bounds may be specified, or neither, but not both.
     *
     * @param extendsBound  the extends (upper) bound, or {@code null} if none
     * @param superBound    the super (lower) bound, or {@code null} if none
     * @return a new wildcard
     * @throws IllegalArgumentException if bounds are not valid
     */
    WildcardType getWildcardType(TypeMirror extendsBound,
                                 TypeMirror superBound);

    
Returns the type corresponding to a type element and actual type arguments. Given the type element for Set and the type mirror for String, for example, this method may be used to get the parameterized type Set<String>. 
 The number of type arguments must either equal the
number of the type element's formal type parameters, or must be
zero.  If zero, and if the type element is generic,
then the type element's raw type is returned.

 If a parameterized type is being returned, its type element must not be contained within a generic outer class. The parameterized type Outer<String>.Inner<Number>, for example, may be constructed by first using this method to get the type Outer<String>, and then invoking getDeclaredType(DeclaredType, TypeElement, TypeMirror...). 
Params:
  • typeElem –  the type element
  • typeArgs –  the actual type arguments
Throws:
  • IllegalArgumentException – if too many or too few
         type arguments are given, or if an inappropriate type
         argument or type element is provided
Returns:the type corresponding to the type element and
         actual type arguments
/**
     * Returns the type corresponding to a type element and
     * actual type arguments.
     * Given the type element for {@code Set} and the type mirror
     * for {@code String},
     * for example, this method may be used to get the
     * parameterized type {@code Set<String>}.
     *
     * <p> The number of type arguments must either equal the
     * number of the type element's formal type parameters, or must be
     * zero.  If zero, and if the type element is generic,
     * then the type element's raw type is returned.
     *
     * <p> If a parameterized type is being returned, its type element
     * must not be contained within a generic outer class.
     * The parameterized type {@code Outer<String>.Inner<Number>},
     * for example, may be constructed by first using this
     * method to get the type {@code Outer<String>}, and then invoking
     * {@link #getDeclaredType(DeclaredType, TypeElement, TypeMirror...)}.
     *
     * @param typeElem  the type element
     * @param typeArgs  the actual type arguments
     * @return the type corresponding to the type element and
     *          actual type arguments
     * @throws IllegalArgumentException if too many or too few
     *          type arguments are given, or if an inappropriate type
     *          argument or type element is provided
     */
    DeclaredType getDeclaredType(TypeElement typeElem, TypeMirror... typeArgs);

    
Returns the type corresponding to a type element and actual type arguments, given a containing type of which it is a member. The parameterized type Outer<String>.Inner<Number>, for example, may be constructed by first using getDeclaredType(TypeElement, TypeMirror...) to get the type Outer<String>, and then invoking this method. 
 If the containing type is a parameterized type, the number of type arguments must equal the number of typeElem's formal type parameters. If it is not parameterized or if it is null, this method is equivalent to getDeclaredType(typeElem, typeArgs). 
Params:
  • containing –  the containing type, or null if none
  • typeElem –    the type element
  • typeArgs –    the actual type arguments
Throws:
  • IllegalArgumentException – if too many or too few
         type arguments are given, or if an inappropriate type
         argument, type element, or containing type is provided
Returns:the type corresponding to the type element and
         actual type arguments, contained within the given type
/**
     * Returns the type corresponding to a type element
     * and actual type arguments, given a
     * {@linkplain DeclaredType#getEnclosingType() containing type}
     * of which it is a member.
     * The parameterized type {@code Outer<String>.Inner<Number>},
     * for example, may be constructed by first using
     * {@link #getDeclaredType(TypeElement, TypeMirror...)}
     * to get the type {@code Outer<String>}, and then invoking
     * this method.
     *
     * <p> If the containing type is a parameterized type,
     * the number of type arguments must equal the
     * number of {@code typeElem}'s formal type parameters.
     * If it is not parameterized or if it is {@code null}, this method is
     * equivalent to {@code getDeclaredType(typeElem, typeArgs)}.
     *
     * @param containing  the containing type, or {@code null} if none
     * @param typeElem    the type element
     * @param typeArgs    the actual type arguments
     * @return the type corresponding to the type element and
     *          actual type arguments, contained within the given type
     * @throws IllegalArgumentException if too many or too few
     *          type arguments are given, or if an inappropriate type
     *          argument, type element, or containing type is provided
     */
    DeclaredType getDeclaredType(DeclaredType containing,
                                 TypeElement typeElem, TypeMirror... typeArgs);

    
Returns the type of an element when that element is viewed as a member of, or otherwise directly contained by, a given type. For example, when viewed as a member of the parameterized type Set<String>, the Set.add method is an ExecutableType whose parameter is of type String. 
Params:
  • containing –  the containing type
  • element –     the element
Throws:
Returns:the type of the element as viewed from the containing type
/**
     * Returns the type of an element when that element is viewed as
     * a member of, or otherwise directly contained by, a given type.
     * For example,
     * when viewed as a member of the parameterized type {@code Set<String>},
     * the {@code Set.add} method is an {@code ExecutableType}
     * whose parameter is of type {@code String}.
     *
     * @param containing  the containing type
     * @param element     the element
     * @return the type of the element as viewed from the containing type
     * @throws IllegalArgumentException if the element is not a valid one
     *          for the given type
     */
    TypeMirror asMemberOf(DeclaredType containing, Element element);
}