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

Initial load
http://hg.openjdk.java.net/jdk8u/jdk8u/langtools/
changeset: 2573:53ca196be1ae
tag: jdk8u25-b17

     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      * @param t the type to map to an element

    56      * @return the element corresponding to the given type

    57      */

    58     Element asElement(TypeMirror t);

    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);

    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 an executable or package type

    95      * @jls 4.10 Subtyping

    96      */

    97     boolean isSubtype(TypeMirror t1, TypeMirror t2);

    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 an executable or package type

   107      * @jls 5.2 Assignment Conversion

   108      */

   109     boolean isAssignable(TypeMirror t1, TypeMirror t2);

   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 an executable or package type

   118      * @jls 4.5.1.1 Type Argument Containment and Equivalence

   119      */

   120     boolean contains(TypeMirror t1, TypeMirror t2);

   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);

   134     /**

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

   136      * will appear last in the list.

   137      *

   138      * @param t  the type being examined

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

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

   141      */

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

   144     /**

   145      * Returns the erasure of a type.

   146      *

   147      * @param t  the type to be erased

   148      * @return the erasure of the given type

   149      * @throws IllegalArgumentException if given a package type

   150      * @jls 4.6 Type Erasure

   151      */

   152     TypeMirror erasure(TypeMirror t);

   154     /**

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

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

   157      *

   158      * @param p  the primitive type to be converted

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

   160      * @jls 5.1.7 Boxing Conversion

   161      */

   162     TypeElement boxedClass(PrimitiveType p);

   164     /**

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

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

   167      *

   168      * @param t  the type to be unboxed

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

   170      * @throws IllegalArgumentException if the given type has no

   171      *          unboxing conversion

   172      * @jls 5.1.8 Unboxing Conversion

   173      */

   174     PrimitiveType unboxedType(TypeMirror t);

   176     /**

   177      * Applies capture conversion to a type.

   178      *

   179      * @param t  the type to be converted

   180      * @return the result of applying capture conversion

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

   182      * @jls 5.1.10 Capture Conversion

   183      */

   184     TypeMirror capture(TypeMirror t);

   186     /**

   187      * Returns a primitive type.

   188      *

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

   190      * @return a primitive type

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

   192      */

   193     PrimitiveType getPrimitiveType(TypeKind kind);

   195     /**

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

   197      *

   198      * @return the null type

   199      */

   200     NullType getNullType();

   202     /**

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

   204      * The kind of type to return may be either

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

   206      * For packages, use

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

   208      * instead.

   209      *

   210      * @param kind  the kind of type to return

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

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

   213      */

   214     NoType getNoType(TypeKind kind);

   216     /**

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

   218      *

   219      * @param componentType  the component type

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

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

   222      *          an array

   223      */

   224     ArrayType getArrayType(TypeMirror componentType);

   226     /**

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

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

   229      *

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

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

   232      * @return a new wildcard

   233      * @throws IllegalArgumentException if bounds are not valid

   234      */

   235     WildcardType getWildcardType(TypeMirror extendsBound,

   236                                  TypeMirror superBound);

   238     /**

   239      * Returns the type corresponding to a type element and

   240      * actual type arguments.

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

   242      * for {@code String},

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

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

   245      *

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

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

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

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

   250      *

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

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

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

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

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

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

   257      *

   258      * @param typeElem  the type element

   259      * @param typeArgs  the actual type arguments

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

   261      *          actual type arguments

   262      * @throws IllegalArgumentException if too many or too few

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

   264      *          argument or type element is provided

   265      */

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

   268     /**

   269      * Returns the type corresponding to a type element

   270      * and actual type arguments, given a

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

   272      * of which it is a member.

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

   274      * for example, may be constructed by first using

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

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

   277      * this method.

   278      *

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

   280      * the number of type arguments must equal the

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

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

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

   284      *

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

   286      * @param typeElem    the type element

   287      * @param typeArgs    the actual type arguments

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

   289      *          actual type arguments, contained within the given type

   290      * @throws IllegalArgumentException if too many or too few

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

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

   293      */

   294     DeclaredType getDeclaredType(DeclaredType containing,

   295                                  TypeElement typeElem, TypeMirror... typeArgs);

   297     /**

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

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

   300      * For example,

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

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

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

   304      *

   305      * @param containing  the containing type

   306      * @param element     the element

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

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

   309      *          for the given type

   310      */

   311     TypeMirror asMemberOf(DeclaredType containing, Element element);

   312 }

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

src/share/classes/javax/lang/model/util/Types.java@959103a6100f

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