Types


1   /*
2    * @(#)Types.java   1.7 06/07/11
3    *
4    * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.lang.model.util;
9   
10  import java.util.List  ;
11  import javax.lang.model.element.*;
12  import javax.lang.model.type.*;
13  
14  /**
15   * Utility methods for operating on types.
16   *
17   * <p><b>Compatibility Note:</b> Methods may be added to this interface
18   * in future releases of the platform.
19   *
20   * @author Joseph D. Darcy
21   * @author Scott Seligman
22   * @author Peter von der Ah&eacute;
23   * @version 1.7 06/07/11
24   * @see javax.annotation.processing.ProcessingEnvironment#getTypeUtils
25   * @since 1.6
26   */
27  public interface Types {
28  
29      /**
30       * Returns the element corresponding to a type.
31       * The type may be a {@code DeclaredType} or {@code TypeVariable}.
32       * Returns {@code null} if the type is not one with a
33       * corresponding element.
34       *
35       * @return the element corresponding to the given type
36       */
37      Element asElement(TypeMirror t);
38      
39      /**
40       * Tests whether two {@code TypeMirror} objects represent the same type.
41       *
42       * <p>Caveat: if either of the arguments to this method represents a
43       * wildcard, this method will return false.  As a consequence, a wildcard
44       * is not the same type as itself.  This might be surprising at first,
45       * but makes sense once you consider that an example like this must be
46       * rejected by the compiler:
47       * <pre> 
48       *   {@code List<?> list = new ArrayList<Object>();}
49       *   {@code list.add(list.get(0));}
50       * </pre>
51       *
52       * @param t1  the first type
53       * @param t2  the second type
54       * @return {@code true} if and only if the two types are the same
55       */
56      boolean isSameType(TypeMirror t1, TypeMirror t2);
57  
58      /**
59       * Tests whether one type is a subtype of another.
60       * Any type is considered to be a subtype of itself.
61       *
62       * @param t1  the first type
63       * @param t2  the second type
64       * @return {@code true} if and only if the first type is a subtype
65       *      of the second
66       * @throws IllegalArgumentException if given an executable or package type
67       * @jls3 4.10 Subtyping
68       */
69      boolean isSubtype(TypeMirror t1, TypeMirror t2);
70  
71      /**
72       * Tests whether one type is assignable to another.
73       *
74       * @param t1  the first type
75       * @param t2  the second type
76       * @return {@code true} if and only if the first type is assignable
77       *      to the second
78       * @throws IllegalArgumentException if given an executable or package type
79       * @jls3 5.2 Assignment Conversion
80       */
81      boolean isAssignable(TypeMirror t1, TypeMirror t2);
82  
83      /**
84       * Tests whether one type argument <i>contains</i> another.
85       *
86       * @param t1  the first type
87       * @param t2  the second type
88       * @return {@code true} if and only if the first type contains the second
89       * @throws IllegalArgumentException if given an executable or package type
90       * @jls3 4.5.1.1 Type Argument Containment and Equivalence
91       */
92      boolean contains(TypeMirror t1, TypeMirror t2);
93  
94      /**
95       * Tests whether the signature of one method is a <i>subsignature</i>
96       * of another.
97       *
98       * @param m1  the first method
99       * @param m2  the second method
100      * @return {@code true} if and only if the first signature is a
101      *      subsignature of the second
102      * @jls3 8.4.2 Method Signature
103      */
104     boolean isSubsignature(ExecutableType m1, ExecutableType m2);
105 
106     /**
107      * Returns the direct supertypes of a type.  The interface types, if any,
108      * will appear last in the list.
109      *
110      * @param t  the type being examined
111      * @return the direct supertypes, or an empty list if none
112      * @throws IllegalArgumentException if given an executable or package type
113      */
114     List  <? extends TypeMirror> directSupertypes(TypeMirror t);
115 
116     /**
117      * Returns the erasure of a type.
118      *
119      * @param t  the type to be erased
120      * @return the erasure of the given type
121      * @throws IllegalArgumentException if given a package type
122      * @jls3 4.6 Type Erasure
123      */
124     TypeMirror erasure(TypeMirror t);
125 
126     /**
127      * Returns the class of a boxed value of a given primitive type.
128      * That is, <i>boxing conversion</i> is applied.
129      *
130      * @param p  the primitive type to be converted
131      * @return the class of a boxed value of type {@code p}
132      * @jls3 5.1.7 Boxing Conversion
133      */
134     TypeElement boxedClass(PrimitiveType p);
135 
136     /**
137      * Returns the type (a primitive type) of unboxed values of a given type.
138      * That is, <i>unboxing conversion</i> is applied.
139      *
140      * @param t  the type to be unboxed
141      * @return the type of an unboxed value of type {@code t}
142      * @throws IllegalArgumentException if the given type has no
143      *      unboxing conversion
144      * @jls3 5.1.8 Unboxing Conversion
145      */
146     PrimitiveType unboxedType(TypeMirror t);
147 
148     /**
149      * Applies capture conversion to a type.
150      *
151      * @param t  the type to be converted
152      * @return the result of applying capture conversion
153      * @throws IllegalArgumentException if given an executable or package type
154      * @jls3 5.1.10 Capture Conversion
155      */
156     TypeMirror capture(TypeMirror t);
157 
158     /**
159      * Returns a primitive type.
160      *
161      * @param kind  the kind of primitive type to return
162      * @return a primitive type
163      * @throws IllegalArgumentException if {@code kind} is not a primitive kind
164      */
165     PrimitiveType getPrimitiveType(TypeKind kind);
166 
167     /**
168      * Returns the null type.  This is the type of {@code null}.
169      *
170      * @return the null type
171      */
172     NullType getNullType();
173 
174     /**
175      * Returns a pseudo-type used where no actual type is appropriate.
176      * The kind of type to return may be either
177      * {@link TypeKind#VOID VOID} or {@link TypeKind#NONE NONE}.
178      * For packages, use
179      * {@link Elements#getPackageElement(CharSequence)}{@code .asType()}
180      * instead.
181      *
182      * @param kind  the kind of type to return
183      * @return a pseudo-type of kind {@code VOID} or {@code NONE}
184      * @throws IllegalArgumentException if {@code kind} is not valid
185      */
186     NoType getNoType(TypeKind kind);
187 
188     /**
189      * Returns an array type with the specified component type.
190      *
191      * @param componentType  the component type
192      * @return an array type with the specified component type.
193      * @throws IllegalArgumentException if the component type is not valid for
194      *      an array
195      */
196     ArrayType getArrayType(TypeMirror componentType);
197 
198     /**
199      * Returns a new wildcard type argument.  Either of the wildcard's
200      * bounds may be specified, or neither, but not both.
201      *
202      * @param extendsBound  the extends (upper) bound, or {@code null} if none
203      * @param superBound    the super (lower) bound, or {@code null} if none
204      * @return a new wildcard
205      * @throws IllegalArgumentException if bounds are not valid
206      */
207     WildcardType getWildcardType(TypeMirror extendsBound,
208                  TypeMirror superBound);
209 
210     /**
211      * Returns the type corresponding to a type element and
212      * actual type arguments.
213      * Given the type element for {@code Set} and the type mirror
214      * for {@code String},
215      * for example, this method may be used to get the
216      * parameterized type {@code Set<String>}.
217      *
218      * <p> The number of type arguments must either equal the
219      * number of the type element's formal type parameters, or must be
220      * zero.  If zero, and if the type element is generic,
221      * then the type element's raw type is returned.
222      *
223      * <p> If a parameterized type is being returned, its type element
224      * must not be contained within a generic outer class.
225      * The parameterized type {@code Outer<String>.Inner<Number>},
226      * for example, may be constructed by first using this
227      * method to get the type {@code Outer<String>}, and then invoking
228      * {@link #getDeclaredType(DeclaredType, TypeElement, TypeMirror...)}.
229      *
230      * @param typeElem  the type element
231      * @param typeArgs  the actual type arguments
232      * @return the type corresponding to the type element and
233      *      actual type arguments
234      * @throws IllegalArgumentException if too many or too few
235      *      type arguments are given, or if an inappropriate type
236      *      argument or type element is provided
237      */
238     DeclaredType getDeclaredType(TypeElement typeElem, TypeMirror... typeArgs);
239 
240     /**
241      * Returns the type corresponding to a type element
242      * and actual type arguments, given a
243      * {@linkplain DeclaredType#getEnclosingType() containing type}
244      * of which it is a member.
245      * The parameterized type {@code Outer<String>.Inner<Number>},
246      * for example, may be constructed by first using
247      * {@link #getDeclaredType(TypeElement, TypeMirror...)}
248      * to get the type {@code Outer<String>}, and then invoking
249      * this method.
250      *
251      * <p> If the containing type is a parameterized type,
252      * the number of type arguments must equal the
253      * number of {@code typeElem}'s formal type parameters.
254      * If it is not parameterized or if it is {@code null}, this method is
255      * equivalent to {@code getDeclaredType(typeElem, typeArgs)}.
256      *
257      * @param containing  the containing type, or {@code null} if none
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, contained within the given type
262      * @throws IllegalArgumentException if too many or too few
263      *      type arguments are given, or if an inappropriate type
264      *      argument, type element, or containing type is provided
265      */
266     DeclaredType getDeclaredType(DeclaredType containing,
267                  TypeElement typeElem, TypeMirror... typeArgs);
268 
269     /**
270      * Returns the type of an element when that element is viewed as
271      * a member of, or otherwise directly contained by, a given type.
272      * For example,
273      * when viewed as a member of the parameterized type {@code Set<String>},
274      * the {@code Set.add} method is an {@code ExecutableType}
275      * whose parameter is of type {@code String}.
276      *
277      * @param containing  the containing type
278      * @param element     the element
279      * @return the type of the element as viewed from the containing type
280      * @throws IllegalArgumentException if the element is not a valid one
281      *      for the given type
282      */
283     TypeMirror asMemberOf(DeclaredType containing, Element element);
284 }
285
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags