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

8008425: Remove interim new javax.lang.model API for type-annotations
Reviewed-by: darcy

     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>Caveat: if either of the arguments to this method represents a

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

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

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

    66      * rejected by the compiler:

    67      * <pre>

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

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

    70      * </pre>

    71      *

    72      * @param t1  the first type

    73      * @param t2  the second type

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

    75      */

    76     boolean isSameType(TypeMirror t1, TypeMirror t2);

    78     /**

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

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

    81      *

    82      * @param t1  the first type

    83      * @param t2  the second type

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

    85      *          of the second

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

    87      * @jls 4.10 Subtyping

    88      */

    89     boolean isSubtype(TypeMirror t1, TypeMirror t2);

    91     /**

    92      * Tests whether one type is assignable to another.

    93      *

    94      * @param t1  the first type

    95      * @param t2  the second type

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

    97      *          to the second

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

    99      * @jls 5.2 Assignment Conversion

   100      */

   101     boolean isAssignable(TypeMirror t1, TypeMirror t2);

   103     /**

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

   105      *

   106      * @param t1  the first type

   107      * @param t2  the second type

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

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

   110      * @jls 4.5.1.1 Type Argument Containment and Equivalence

   111      */

   112     boolean contains(TypeMirror t1, TypeMirror t2);

   114     /**

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

   116      * of another.

   117      *

   118      * @param m1  the first method

   119      * @param m2  the second method

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

   121      *          subsignature of the second

   122      * @jls 8.4.2 Method Signature

   123      */

   124     boolean isSubsignature(ExecutableType m1, ExecutableType m2);

   126     /**

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

   128      * will appear last in the list.

   129      *

   130      * @param t  the type being examined

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

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

   133      */

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

   136     /**

   137      * Returns the erasure of a type.

   138      *

   139      * @param t  the type to be erased

   140      * @return the erasure of the given type

   141      * @throws IllegalArgumentException if given a package type

   142      * @jls 4.6 Type Erasure

   143      */

   144     TypeMirror erasure(TypeMirror t);

   146     /**

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

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

   149      *

   150      * @param p  the primitive type to be converted

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

   152      * @jls 5.1.7 Boxing Conversion

   153      */

   154     TypeElement boxedClass(PrimitiveType p);

   156     /**

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

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

   159      *

   160      * @param t  the type to be unboxed

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

   162      * @throws IllegalArgumentException if the given type has no

   163      *          unboxing conversion

   164      * @jls 5.1.8 Unboxing Conversion

   165      */

   166     PrimitiveType unboxedType(TypeMirror t);

   168     /**

   169      * Applies capture conversion to a type.

   170      *

   171      * @param t  the type to be converted

   172      * @return the result of applying capture conversion

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

   174      * @jls 5.1.10 Capture Conversion

   175      */

   176     TypeMirror capture(TypeMirror t);

   178     /**

   179      * Returns a primitive type.

   180      *

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

   182      * @return a primitive type

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

   184      */

   185     PrimitiveType getPrimitiveType(TypeKind kind);

   187     /**

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

   189      *

   190      * @return the null type

   191      */

   192     NullType getNullType();

   194     /**

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

   196      * The kind of type to return may be either

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

   198      * For packages, use

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

   200      * instead.

   201      *

   202      * @param kind  the kind of type to return

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

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

   205      */

   206     NoType getNoType(TypeKind kind);

   208     /**

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

   210      *

   211      * @param componentType  the component type

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

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

   214      *          an array

   215      */

   216     ArrayType getArrayType(TypeMirror componentType);

   218     /**

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

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

   221      *

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

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

   224      * @return a new wildcard

   225      * @throws IllegalArgumentException if bounds are not valid

   226      */

   227     WildcardType getWildcardType(TypeMirror extendsBound,

   228                                  TypeMirror superBound);

   230     /**

   231      * Returns the type corresponding to a type element and

   232      * actual type arguments.

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

   234      * for {@code String},

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

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

   237      *

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

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

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

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

   242      *

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

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

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

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

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

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

   249      *

   250      * @param typeElem  the type element

   251      * @param typeArgs  the actual type arguments

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

   253      *          actual type arguments

   254      * @throws IllegalArgumentException if too many or too few

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

   256      *          argument or type element is provided

   257      */

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

   260     /**

   261      * Returns the type corresponding to a type element

   262      * and actual type arguments, given a

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

   264      * of which it is a member.

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

   266      * for example, may be constructed by first using

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

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

   269      * this method.

   270      *

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

   272      * the number of type arguments must equal the

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

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

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

   276      *

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

   278      * @param typeElem    the type element

   279      * @param typeArgs    the actual type arguments

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

   281      *          actual type arguments, contained within the given type

   282      * @throws IllegalArgumentException if too many or too few

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

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

   285      */

   286     DeclaredType getDeclaredType(DeclaredType containing,

   287                                  TypeElement typeElem, TypeMirror... typeArgs);

   289     /**

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

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

   292      * For example,

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

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

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

   296      *

   297      * @param containing  the containing type

   298      * @param element     the element

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

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

   301      *          for the given type

   302      */

   303     TypeMirror asMemberOf(DeclaredType containing, Element element);

   304 }

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

src/share/classes/javax/lang/model/util/Types.java@40adaf938847

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