jdk8-mips64-public/langtools: src/share/classes/javax/lang/model/util/Types.java@97f6839673d6

     1 /*

     2  * Copyright (c) 2005, 2013, 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  */

    26 package javax.lang.model.util;

    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.*;

    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 {

    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      * @return the element corresponding to the given type

    56      */

    57     Element asElement(TypeMirror t);

    59     /**

    60      * Tests whether two {@code TypeMirror} objects represent the same type.

    61      *

    62      * <p>Since annotations are only meta-data associated with a type,

    63      * the set of annotations on either argument is <em>not</em> taken

    64      * into account when computing whether or not two {@code

    65      * TypeMirror} objects are the same type. In particular, two

    66      * {@code TypeMirror} objects can have different annotations and

    67      * still be considered the same.

    68      *

    69      * <p>Caveat: if either of the arguments to this method represents a

    70      * wildcard, this method will return false.  As a consequence, a wildcard

    71      * is not the same type as itself.  This might be surprising at first,

    72      * but makes sense once you consider that an example like this must be

    73      * rejected by the compiler:

    74      * <pre>

    75      *   {@code List<?> list = new ArrayList<Object>();}

    76      *   {@code list.add(list.get(0));}

    77      * </pre>

    78      *

    79      * @param t1  the first type

    80      * @param t2  the second type

    81      * @return {@code true} if and only if the two types are the same

    82      */

    83     boolean isSameType(TypeMirror t1, TypeMirror t2);

    85     /**

    86      * Tests whether one type is a subtype of another.

    87      * Any type is considered to be a subtype of itself.

    88      *

    89      * @param t1  the first type

    90      * @param t2  the second type

    91      * @return {@code true} if and only if the first type is a subtype

    92      *          of the second

    93      * @throws IllegalArgumentException if given an executable or package type

    94      * @jls 4.10 Subtyping

    95      */

    96     boolean isSubtype(TypeMirror t1, TypeMirror t2);

    98     /**

    99      * Tests whether one type is assignable to another.

   100      *

   101      * @param t1  the first type

   102      * @param t2  the second type

   103      * @return {@code true} if and only if the first type is assignable

   104      *          to the second

   105      * @throws IllegalArgumentException if given an executable or package type

   106      * @jls 5.2 Assignment Conversion

   107      */

   108     boolean isAssignable(TypeMirror t1, TypeMirror t2);

   110     /**

   111      * Tests whether one type argument <i>contains</i> another.

   112      *

   113      * @param t1  the first type

   114      * @param t2  the second type

   115      * @return {@code true} if and only if the first type contains the second

   116      * @throws IllegalArgumentException if given an executable or package type

   117      * @jls 4.5.1.1 Type Argument Containment and Equivalence

   118      */

   119     boolean contains(TypeMirror t1, TypeMirror t2);

   121     /**

   122      * Tests whether the signature of one method is a <i>subsignature</i>

   123      * of another.

   124      *

   125      * @param m1  the first method

   126      * @param m2  the second method

   127      * @return {@code true} if and only if the first signature is a

   128      *          subsignature of the second

   129      * @jls 8.4.2 Method Signature

   130      */

   131     boolean isSubsignature(ExecutableType m1, ExecutableType m2);

   133     /**

   134      * Returns the direct supertypes of a type.  The interface types, if any,

   135      * will appear last in the list.

   136      *

   137      * @param t  the type being examined

   138      * @return the direct supertypes, or an empty list if none

   139      * @throws IllegalArgumentException if given an executable or package type

   140      */

   141     List<? extends TypeMirror> directSupertypes(TypeMirror t);

   143     /**

   144      * Returns the erasure of a type.

   145      *

   146      * @param t  the type to be erased

   147      * @return the erasure of the given type

   148      * @throws IllegalArgumentException if given a package type

   149      * @jls 4.6 Type Erasure

   150      */

   151     TypeMirror erasure(TypeMirror t);

   153     /**

   154      * Returns the class of a boxed value of a given primitive type.

   155      * That is, <i>boxing conversion</i> is applied.

   156      *

   157      * @param p  the primitive type to be converted

   158      * @return the class of a boxed value of type {@code p}

   159      * @jls 5.1.7 Boxing Conversion

   160      */

   161     TypeElement boxedClass(PrimitiveType p);

   163     /**

   164      * Returns the type (a primitive type) of unboxed values of a given type.

   165      * That is, <i>unboxing conversion</i> is applied.

   166      *

   167      * @param t  the type to be unboxed

   168      * @return the type of an unboxed value of type {@code t}

   169      * @throws IllegalArgumentException if the given type has no

   170      *          unboxing conversion

   171      * @jls 5.1.8 Unboxing Conversion

   172      */

   173     PrimitiveType unboxedType(TypeMirror t);

   175     /**

   176      * Applies capture conversion to a type.

   177      *

   178      * @param t  the type to be converted

   179      * @return the result of applying capture conversion

   180      * @throws IllegalArgumentException if given an executable or package type

   181      * @jls 5.1.10 Capture Conversion

   182      */

   183     TypeMirror capture(TypeMirror t);

   185     /**

   186      * Returns a primitive type.

   187      *

   188      * @param kind  the kind of primitive type to return

   189      * @return a primitive type

   190      * @throws IllegalArgumentException if {@code kind} is not a primitive kind

   191      */

   192     PrimitiveType getPrimitiveType(TypeKind kind);

   194     /**

   195      * Returns the null type.  This is the type of {@code null}.

   196      *

   197      * @return the null type

   198      */

   199     NullType getNullType();

   201     /**

   202      * Returns a pseudo-type used where no actual type is appropriate.

   203      * The kind of type to return may be either

   204      * {@link TypeKind#VOID VOID} or {@link TypeKind#NONE NONE}.

   205      * For packages, use

   206      * {@link Elements#getPackageElement(CharSequence)}{@code .asType()}

   207      * instead.

   208      *

   209      * @param kind  the kind of type to return

   210      * @return a pseudo-type of kind {@code VOID} or {@code NONE}

   211      * @throws IllegalArgumentException if {@code kind} is not valid

   212      */

   213     NoType getNoType(TypeKind kind);

   215     /**

   216      * Returns an array type with the specified component type.

   217      *

   218      * @param componentType  the component type

   219      * @return an array type with the specified component type.

   220      * @throws IllegalArgumentException if the component type is not valid for

   221      *          an array

   222      */

   223     ArrayType getArrayType(TypeMirror componentType);

   225     /**

   226      * Returns a new wildcard type argument.  Either of the wildcard's

   227      * bounds may be specified, or neither, but not both.

   228      *

   229      * @param extendsBound  the extends (upper) bound, or {@code null} if none

   230      * @param superBound    the super (lower) bound, or {@code null} if none

   231      * @return a new wildcard

   232      * @throws IllegalArgumentException if bounds are not valid

   233      */

   234     WildcardType getWildcardType(TypeMirror extendsBound,

   235                                  TypeMirror superBound);

   237     /**

   238      * Returns the type corresponding to a type element and

   239      * actual type arguments.

   240      * Given the type element for {@code Set} and the type mirror

   241      * for {@code String},

   242      * for example, this method may be used to get the

   243      * parameterized type {@code Set<String>}.

   244      *

   245      * <p> The number of type arguments must either equal the

   246      * number of the type element's formal type parameters, or must be

   247      * zero.  If zero, and if the type element is generic,

   248      * then the type element's raw type is returned.

   249      *

   250      * <p> If a parameterized type is being returned, its type element

   251      * must not be contained within a generic outer class.

   252      * The parameterized type {@code Outer<String>.Inner<Number>},

   253      * for example, may be constructed by first using this

   254      * method to get the type {@code Outer<String>}, and then invoking

   255      * {@link #getDeclaredType(DeclaredType, TypeElement, TypeMirror...)}.

   256      *

   257      * @param typeElem  the type element

   258      * @param typeArgs  the actual type arguments

   259      * @return the type corresponding to the type element and

   260      *          actual type arguments

   261      * @throws IllegalArgumentException if too many or too few

   262      *          type arguments are given, or if an inappropriate type

   263      *          argument or type element is provided

   264      */

   265     DeclaredType getDeclaredType(TypeElement typeElem, TypeMirror... typeArgs);

   267     /**

   268      * Returns the type corresponding to a type element

   269      * and actual type arguments, given a

   270      * {@linkplain DeclaredType#getEnclosingType() containing type}

   271      * of which it is a member.

   272      * The parameterized type {@code Outer<String>.Inner<Number>},

   273      * for example, may be constructed by first using

   274      * {@link #getDeclaredType(TypeElement, TypeMirror...)}

   275      * to get the type {@code Outer<String>}, and then invoking

   276      * this method.

   277      *

   278      * <p> If the containing type is a parameterized type,

   279      * the number of type arguments must equal the

   280      * number of {@code typeElem}'s formal type parameters.

   281      * If it is not parameterized or if it is {@code null}, this method is

   282      * equivalent to {@code getDeclaredType(typeElem, typeArgs)}.

   283      *

   284      * @param containing  the containing type, or {@code null} if none

   285      * @param typeElem    the type element

   286      * @param typeArgs    the actual type arguments

   287      * @return the type corresponding to the type element and

   288      *          actual type arguments, contained within the given type

   289      * @throws IllegalArgumentException if too many or too few

   290      *          type arguments are given, or if an inappropriate type

   291      *          argument, type element, or containing type is provided

   292      */

   293     DeclaredType getDeclaredType(DeclaredType containing,

   294                                  TypeElement typeElem, TypeMirror... typeArgs);

   296     /**

   297      * Returns the type of an element when that element is viewed as

   298      * a member of, or otherwise directly contained by, a given type.

   299      * For example,

   300      * when viewed as a member of the parameterized type {@code Set<String>},

   301      * the {@code Set.add} method is an {@code ExecutableType}

   302      * whose parameter is of type {@code String}.

   303      *

   304      * @param containing  the containing type

   305      * @param element     the element

   306      * @return the type of the element as viewed from the containing type

   307      * @throws IllegalArgumentException if the element is not a valid one

   308      *          for the given type

   309      */

   310     TypeMirror asMemberOf(DeclaredType containing, Element element);

   311 }

Mercurial > jdk8-mips64-public > langtools / file revision

src/share/classes/javax/lang/model/util/Types.java@97f6839673d6

src/share/classes/javax/lang/model/util/Types.java