001: /*
002: * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package javax.lang.model.util;
027:
028: import java.util.List;
029: import javax.lang.model.element.*;
030: import javax.lang.model.type.*;
031:
032: /**
033: * Utility methods for operating on types.
034: *
035: * <p><b>Compatibility Note:</b> Methods may be added to this interface
036: * in future releases of the platform.
037: *
038: * @author Joseph D. Darcy
039: * @author Scott Seligman
040: * @author Peter von der Ahé
041: * @version 1.13 07/05/05
042: * @see javax.annotation.processing.ProcessingEnvironment#getTypeUtils
043: * @since 1.6
044: */
045: public interface Types {
046:
047: /**
048: * Returns the element corresponding to a type.
049: * The type may be a {@code DeclaredType} or {@code TypeVariable}.
050: * Returns {@code null} if the type is not one with a
051: * corresponding element.
052: *
053: * @return the element corresponding to the given type
054: */
055: Element asElement(TypeMirror t);
056:
057: /**
058: * Tests whether two {@code TypeMirror} objects represent the same type.
059: *
060: * <p>Caveat: if either of the arguments to this method represents a
061: * wildcard, this method will return false. As a consequence, a wildcard
062: * is not the same type as itself. This might be surprising at first,
063: * but makes sense once you consider that an example like this must be
064: * rejected by the compiler:
065: * <pre>
066: * {@code List<?> list = new ArrayList<Object>();}
067: * {@code list.add(list.get(0));}
068: * </pre>
069: *
070: * @param t1 the first type
071: * @param t2 the second type
072: * @return {@code true} if and only if the two types are the same
073: */
074: boolean isSameType(TypeMirror t1, TypeMirror t2);
075:
076: /**
077: * Tests whether one type is a subtype of another.
078: * Any type is considered to be a subtype of itself.
079: *
080: * @param t1 the first type
081: * @param t2 the second type
082: * @return {@code true} if and only if the first type is a subtype
083: * of the second
084: * @throws IllegalArgumentException if given an executable or package type
085: * @jls3 4.10 Subtyping
086: */
087: boolean isSubtype(TypeMirror t1, TypeMirror t2);
088:
089: /**
090: * Tests whether one type is assignable to another.
091: *
092: * @param t1 the first type
093: * @param t2 the second type
094: * @return {@code true} if and only if the first type is assignable
095: * to the second
096: * @throws IllegalArgumentException if given an executable or package type
097: * @jls3 5.2 Assignment Conversion
098: */
099: boolean isAssignable(TypeMirror t1, TypeMirror t2);
100:
101: /**
102: * Tests whether one type argument <i>contains</i> another.
103: *
104: * @param t1 the first type
105: * @param t2 the second type
106: * @return {@code true} if and only if the first type contains the second
107: * @throws IllegalArgumentException if given an executable or package type
108: * @jls3 4.5.1.1 Type Argument Containment and Equivalence
109: */
110: boolean contains(TypeMirror t1, TypeMirror t2);
111:
112: /**
113: * Tests whether the signature of one method is a <i>subsignature</i>
114: * of another.
115: *
116: * @param m1 the first method
117: * @param m2 the second method
118: * @return {@code true} if and only if the first signature is a
119: * subsignature of the second
120: * @jls3 8.4.2 Method Signature
121: */
122: boolean isSubsignature(ExecutableType m1, ExecutableType m2);
123:
124: /**
125: * Returns the direct supertypes of a type. The interface types, if any,
126: * will appear last in the list.
127: *
128: * @param t the type being examined
129: * @return the direct supertypes, or an empty list if none
130: * @throws IllegalArgumentException if given an executable or package type
131: */
132: List<? extends TypeMirror> directSupertypes(TypeMirror t);
133:
134: /**
135: * Returns the erasure of a type.
136: *
137: * @param t the type to be erased
138: * @return the erasure of the given type
139: * @throws IllegalArgumentException if given a package type
140: * @jls3 4.6 Type Erasure
141: */
142: TypeMirror erasure(TypeMirror t);
143:
144: /**
145: * Returns the class of a boxed value of a given primitive type.
146: * That is, <i>boxing conversion</i> is applied.
147: *
148: * @param p the primitive type to be converted
149: * @return the class of a boxed value of type {@code p}
150: * @jls3 5.1.7 Boxing Conversion
151: */
152: TypeElement boxedClass(PrimitiveType p);
153:
154: /**
155: * Returns the type (a primitive type) of unboxed values of a given type.
156: * That is, <i>unboxing conversion</i> is applied.
157: *
158: * @param t the type to be unboxed
159: * @return the type of an unboxed value of type {@code t}
160: * @throws IllegalArgumentException if the given type has no
161: * unboxing conversion
162: * @jls3 5.1.8 Unboxing Conversion
163: */
164: PrimitiveType unboxedType(TypeMirror t);
165:
166: /**
167: * Applies capture conversion to a type.
168: *
169: * @param t the type to be converted
170: * @return the result of applying capture conversion
171: * @throws IllegalArgumentException if given an executable or package type
172: * @jls3 5.1.10 Capture Conversion
173: */
174: TypeMirror capture(TypeMirror t);
175:
176: /**
177: * Returns a primitive type.
178: *
179: * @param kind the kind of primitive type to return
180: * @return a primitive type
181: * @throws IllegalArgumentException if {@code kind} is not a primitive kind
182: */
183: PrimitiveType getPrimitiveType(TypeKind kind);
184:
185: /**
186: * Returns the null type. This is the type of {@code null}.
187: *
188: * @return the null type
189: */
190: NullType getNullType();
191:
192: /**
193: * Returns a pseudo-type used where no actual type is appropriate.
194: * The kind of type to return may be either
195: * {@link TypeKind#VOID VOID} or {@link TypeKind#NONE NONE}.
196: * For packages, use
197: * {@link Elements#getPackageElement(CharSequence)}{@code .asType()}
198: * instead.
199: *
200: * @param kind the kind of type to return
201: * @return a pseudo-type of kind {@code VOID} or {@code NONE}
202: * @throws IllegalArgumentException if {@code kind} is not valid
203: */
204: NoType getNoType(TypeKind kind);
205:
206: /**
207: * Returns an array type with the specified component type.
208: *
209: * @param componentType the component type
210: * @return an array type with the specified component type.
211: * @throws IllegalArgumentException if the component type is not valid for
212: * an array
213: */
214: ArrayType getArrayType(TypeMirror componentType);
215:
216: /**
217: * Returns a new wildcard type argument. Either of the wildcard's
218: * bounds may be specified, or neither, but not both.
219: *
220: * @param extendsBound the extends (upper) bound, or {@code null} if none
221: * @param superBound the super (lower) bound, or {@code null} if none
222: * @return a new wildcard
223: * @throws IllegalArgumentException if bounds are not valid
224: */
225: WildcardType getWildcardType(TypeMirror extendsBound,
226: TypeMirror super Bound);
227:
228: /**
229: * Returns the type corresponding to a type element and
230: * actual type arguments.
231: * Given the type element for {@code Set} and the type mirror
232: * for {@code String},
233: * for example, this method may be used to get the
234: * parameterized type {@code Set<String>}.
235: *
236: * <p> The number of type arguments must either equal the
237: * number of the type element's formal type parameters, or must be
238: * zero. If zero, and if the type element is generic,
239: * then the type element's raw type is returned.
240: *
241: * <p> If a parameterized type is being returned, its type element
242: * must not be contained within a generic outer class.
243: * The parameterized type {@code Outer<String>.Inner<Number>},
244: * for example, may be constructed by first using this
245: * method to get the type {@code Outer<String>}, and then invoking
246: * {@link #getDeclaredType(DeclaredType, TypeElement, TypeMirror...)}.
247: *
248: * @param typeElem the type element
249: * @param typeArgs the actual type arguments
250: * @return the type corresponding to the type element and
251: * actual type arguments
252: * @throws IllegalArgumentException if too many or too few
253: * type arguments are given, or if an inappropriate type
254: * argument or type element is provided
255: */
256: DeclaredType getDeclaredType(TypeElement typeElem,
257: TypeMirror... typeArgs);
258:
259: /**
260: * Returns the type corresponding to a type element
261: * and actual type arguments, given a
262: * {@linkplain DeclaredType#getEnclosingType() containing type}
263: * of which it is a member.
264: * The parameterized type {@code Outer<String>.Inner<Number>},
265: * for example, may be constructed by first using
266: * {@link #getDeclaredType(TypeElement, TypeMirror...)}
267: * to get the type {@code Outer<String>}, and then invoking
268: * this method.
269: *
270: * <p> If the containing type is a parameterized type,
271: * the number of type arguments must equal the
272: * number of {@code typeElem}'s formal type parameters.
273: * If it is not parameterized or if it is {@code null}, this method is
274: * equivalent to {@code getDeclaredType(typeElem, typeArgs)}.
275: *
276: * @param containing the containing type, or {@code null} if none
277: * @param typeElem the type element
278: * @param typeArgs the actual type arguments
279: * @return the type corresponding to the type element and
280: * actual type arguments, contained within the given type
281: * @throws IllegalArgumentException if too many or too few
282: * type arguments are given, or if an inappropriate type
283: * argument, type element, or containing type is provided
284: */
285: DeclaredType getDeclaredType(DeclaredType containing,
286: TypeElement typeElem, TypeMirror... typeArgs);
287:
288: /**
289: * Returns the type of an element when that element is viewed as
290: * a member of, or otherwise directly contained by, a given type.
291: * For example,
292: * when viewed as a member of the parameterized type {@code Set<String>},
293: * the {@code Set.add} method is an {@code ExecutableType}
294: * whose parameter is of type {@code String}.
295: *
296: * @param containing the containing type
297: * @param element the element
298: * @return the type of the element as viewed from the containing type
299: * @throws IllegalArgumentException if the element is not a valid one
300: * for the given type
301: */
302: TypeMirror asMemberOf(DeclaredType containing, Element element);
303: }
|