1 /*
   2  * Copyright 2004 Sun Microsystems, Inc.  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.  Sun designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
  22  * CA 95054 USA or visit www.sun.com if you need additional information or
  23  * have any questions.
  24  */
  25 
  26 package com.sun.mirror.util;
  27 
  28 
  29 import java.util.Collection;
  30 
  31 import com.sun.mirror.declaration.*;
  32 import com.sun.mirror.type.*;
  33 
  34 
  35 /**
  36  * Utility methods for operating on types.
  37  *
  38  * @author Joseph D. Darcy
  39  * @author Scott Seligman
  40  * @since 1.5
  41  */
  42 
  43 public interface Types {
  44 
  45     /**
  46      * Tests whether one type is a subtype of the another.
  47      * Any type is considered to be a subtype of itself.
  48      *
  49      * @param t1  the first type
  50      * @param t2  the second type
  51      * @return <tt>true</tt> if and only if the first type is a subtype
  52      *          of the second
  53      */
  54     boolean isSubtype(TypeMirror t1, TypeMirror t2);
  55 
  56     /**
  57      * Tests whether one type is assignable to another.
  58      *
  59      * @param t1  the first type
  60      * @param t2  the second type
  61      * @return <tt>true</tt> if and only if the first type is assignable
  62      *          to the second
  63      */
  64     boolean isAssignable(TypeMirror t1, TypeMirror t2);
  65 
  66     /**
  67      * Returns the erasure of a type.
  68      *
  69      * @param t  the type to be erased
  70      * @return the erasure of the given type
  71      */
  72     TypeMirror getErasure(TypeMirror t);
  73 
  74     /**
  75      * Returns a primitive type.
  76      *
  77      * @param kind  the kind of primitive type to return
  78      * @return a primitive type
  79      */
  80     PrimitiveType getPrimitiveType(PrimitiveType.Kind kind);
  81 
  82     /**
  83      * Returns the pseudo-type representing the type of <tt>void</tt>.
  84      *
  85      * @return the pseudo-type representing the type of <tt>void</tt>
  86      */
  87     VoidType getVoidType();
  88 
  89     /**
  90      * Returns an array type with the specified component type.
  91      *
  92      * @param componentType  the component type
  93      * @return an array type with the specified component type.
  94      * @throws IllegalArgumentException if the component type is not valid for
  95      *          an array
  96      */
  97     ArrayType getArrayType(TypeMirror componentType);
  98 
  99     /**
 100      * Returns the type variable declared by a type parameter.
 101      *
 102      * @param tparam  the type parameter
 103      * @return the type variable declared by the type parameter
 104      */
 105     TypeVariable getTypeVariable(TypeParameterDeclaration tparam);
 106 
 107     /**
 108      * Returns a new wildcard.
 109      * Either the wildcards's upper bounds or lower bounds may be
 110      * specified, or neither, but not both.
 111      *
 112      * @param upperBounds  the upper bounds of this wildcard,
 113      *          or an empty collection if none
 114      * @param lowerBounds  the lower bounds of this wildcard,
 115      *          or an empty collection if none
 116      * @return a new wildcard
 117      * @throws IllegalArgumentException if bounds are not valid
 118      */
 119     WildcardType getWildcardType(Collection<ReferenceType> upperBounds,
 120                                  Collection<ReferenceType> lowerBounds);
 121 
 122     /**
 123      * Returns the type corresponding to a type declaration and
 124      * actual type arguments.
 125      * Given the declaration for <tt>String</tt>, for example, this
 126      * method may be used to get the <tt>String</tt> type.  It may
 127      * then be invoked a second time, with the declaration for <tt>Set</tt>,
 128      * to make the parameterized type {@code Set<String>}.
 129      *
 130      * <p> The number of type arguments must either equal the
 131      * number of the declaration's formal type parameters, or must be
 132      * zero.  If zero, and if the declaration is generic,
 133      * then the declaration's raw type is returned.
 134      *
 135      * <p> If a parameterized type is being returned, its declaration
 136      * must not be contained within a generic outer class.
 137      * The parameterized type {@code Outer<String>.Inner<Number>},
 138      * for example, may be constructed by first using this
 139      * method to get the type {@code Outer<String>}, and then invoking
 140      * {@link #getDeclaredType(DeclaredType, TypeDeclaration, TypeMirror...)}.
 141      *
 142      * @param decl      the type declaration
 143      * @param typeArgs  the actual type arguments
 144      * @return the type corresponding to the type declaration and
 145      *          actual type arguments
 146      * @throws IllegalArgumentException if too many or too few
 147      *          type arguments are given, or if an inappropriate type
 148      *          argument or declaration is provided
 149      */
 150     DeclaredType getDeclaredType(TypeDeclaration decl,
 151                                  TypeMirror... typeArgs);
 152 
 153     /**
 154      * Returns the type corresponding to a type declaration
 155      * and actual arguments, given a
 156      * {@linkplain DeclaredType#getContainingType() containing type}
 157      * of which it is a member.
 158      * The parameterized type {@code Outer<String>.Inner<Number>},
 159      * for example, may be constructed by first using
 160      * {@link #getDeclaredType(TypeDeclaration, TypeMirror...)}
 161      * to get the type {@code Outer<String>}, and then invoking
 162      * this method.
 163      *
 164      * <p> If the containing type is a parameterized type,
 165      * the number of type arguments must equal the
 166      * number of the declaration's formal type parameters.
 167      * If it is not parameterized or if it is <tt>null</tt>, this method is
 168      * equivalent to <tt>getDeclaredType(decl, typeArgs)</tt>.
 169      *
 170      * @param containing  the containing type, or <tt>null</tt> if none
 171      * @param decl        the type declaration
 172      * @param typeArgs    the actual type arguments
 173      * @return the type corresponding to the type declaration and
 174      *          actual type arguments,
 175      *          contained within the given type
 176      * @throws IllegalArgumentException if too many or too few
 177      *          type arguments are given, or if an inappropriate type
 178      *          argument, declaration, or containing type is provided
 179      */
 180     DeclaredType getDeclaredType(DeclaredType containing,
 181                                  TypeDeclaration decl,
 182                                  TypeMirror... typeArgs);
 183 }