Source code: javax/ide/model/java/declaration/TypeD.java
1 /*
2 * @(#)TypeD.java
3 */
4
5 package javax.ide.model.java.declaration;
6
7 import java.util.Collection;
8
9 /**
10 * Mirrors a type.
11 *
12 * <h3> Members </h3>
13 *
14 * A member should be listed in its respective member collection if it
15 * is either declared or inherited. Members that are not inherited
16 * should not be listed. Private members are never inherited.
17 * Package-private members are not inherited outside of the declaring
18 * package. Public members are always inherited. Note that
19 * constructors are never inherited. <p/>
20 *
21 * The order of the member listing should be determined by the type
22 * hierarchy. If type B occurs before type A in the type hierarchy,
23 * then all of B's declared members should occur before any of A's
24 * declared members in the member collection. Consider the following
25 * two classes. <p/>
26 *
27 * <pre>
28 * class A
29 * {
30 * int a;
31 * }
32 * class B extends A
33 * {
34 * int b;
35 * }
36 * </pre>
37 *
38 * The iterator for the collection returned for the member fields of B
39 * should always return <code>B.b</code> before <code>A.a</code>.
40 * Order within the same declaring type is not defined. <p/>
41 *
42 * TODO: If a client wanted to write a compiler and base it on the
43 * declaration interfaces (which should conceivably be possible), how does
44 * the client find out about not-inherited fields in order to display
45 * a meaningful error message? Should we address that here? <p/>
46 *
47 * @author Andy Yu
48 */
49 public interface TypeD
50 extends Declaration, HasTypeD
51 {
52 // ----------------------------------------------------------------------
53
54 public static final TypeD[] EMPTY_ARRAY = new TypeD[ 0 ];
55
56
57 // ----------------------------------------------------------------------
58
59 /**
60 * Gets itself as its type.
61 *
62 * @return The type of a type declaration is trivially itself.
63 */
64 public TypeD getType();
65
66
67 // ----------------------------------------------------------------------
68
69 /**
70 * Gets the type erasure of this type.
71 *
72 * @return The type declaration representing the type erasure of this type.
73 */
74 public ClassD getTypeErasure();
75
76
77 // ----------------------------------------------------------------------
78
79 /**
80 * True if this is a primitive type, including the special
81 * <code>void</code> type. <p/>
82 *
83 * @return True if this type is a primitive type.
84 */
85 public boolean isPrimitive();
86
87 /**
88 * True if this is an array type. <p/>
89 *
90 * @return True if this type is an array type.
91 */
92 public boolean isArray();
93
94
95 // ----------------------------------------------------------------------
96
97 /**
98 * True if this is an enum type. <p/>
99 *
100 * @return True if this an enumeration type. False otherwise.
101 */
102 public boolean isEnum();
103
104 /**
105 * True if this is an annotation type. <p/>
106 *
107 * @return True if this is an annotation type. False otherwise.
108 */
109 public boolean isAnnotation();
110
111 /**
112 * True if this is an interface. This includes "interface" types and
113 * "annotation" types. <p/>
114 *
115 * @return True if this is an interface type.
116 */
117 public boolean isInterface();
118
119
120 // ----------------------------------------------------------------------
121
122 /**
123 * Gets the fully qualified name of this type in source format.
124 * Here, "source format" means the format of a type reference in a
125 * source compilation unit. A type's source name uniquely identifies
126 * a type in a specific scope but not in the general scope. <p/>
127 *
128 * An array type returns the fully qualified name of its component
129 * type suffixed by the appropriate number of brackets. Parametrized
130 * types return the fully qualified name of its raw type suffixed
131 * with the type parameters. A local inner class returns only its
132 * simple name because that is how it is referred to in a source
133 * compilation unit. <p/>
134 *
135 * Note: Anonymous inner classes return the empty string because
136 * they may not be referred to in a source compilation unit. <p/>
137 *
138 * TODO: What should be returned by an anonymous class? Technically,
139 * getSourceName() is irrelevant because anonymous classes may not
140 * be referred to in a source compilation unit. <p/>
141 *
142 * @return The fully qualified source name for this type, empty for
143 * anonymous classes. Examples: <code>java.lang.Object</code>,
144 * <code>java.util.Map<String,String></code>,
145 * <code>java.lang.String[][]</code>
146 */
147 public String getSourceName();
148
149 /**
150 * Gets the descriptor for this type, as defined by the JVMS2. <p/>
151 *
152 * For jdk < 1.5, the "FieldDescriptor" is returned (JVMS2). For
153 * jdk >= 1.5, a type signature of the type erasure is returned. <p/>
154 *
155 * Note: The descriptor is equivalent to the type signature of this
156 * type's erasure. <p/>
157 *
158 * @return The descriptor as defined in the JVMS2. Always non-null.
159 * e.g. "I", "Ljava/lang/Object;"
160 */
161 public String getDescriptor();
162
163 /**
164 * Gets the type signature for this type, as defined by the
165 * JVMS3. <p/>
166 *
167 * A ClassD returns its "ClassTypeSignature" (JVMS3). A ClassD is
168 * uniquely identified by its type signature. Example value:
169 * <code>Ljava/util/List<Ljava/lang/Object;>;</code> <p/>
170 *
171 * A TypeVariableD returns its "TypeVariableSignature" (JVMS3). A
172 * TypeVariableD is uniquely identified by its owning declaration
173 * and its type signature. Example value: <code>TE;</code>. <p/>
174 *
175 * A WildcardTypeD returns its "TypeArgument" value (JVMS3). A
176 * WildcardTypeD is uniquely identified by its type signature.
177 * Example values: <code>*</code> <code>+Ljava/lang/Object;</code>
178 * <p/>
179 *
180 * @return The type signature as defined in the JVMS3. Always
181 * non-null.
182 */
183 public String getTypeSignature();
184
185
186 // ----------------------------------------------------------------------
187
188 /**
189 * Gets this type's superclass. The name "getSuperclass" was chosen
190 * to be consistent with java/lang/Class.
191 *
192 * @return The type declaration for this type's superclass. Behavior
193 * should "declaration" reflection. <p/>
194 *
195 * If this is a ClassD: Null is returned for java/lang/Object and
196 * primitive types, non-null otherwise. Where no base class was
197 * declared, java/lang/Object is returned, even for interfaces. <p/>
198 *
199 * If this is a TypeVariableD: Null if no superclass was declared
200 * AND an interface as declared. <p/>
201 *
202 * If this is a WildcardTypeD: Always non-null. If no superclass was
203 * declared, then a TypeD for the "null" primitive type is returned.
204 * <p/>
205 *
206 * Note: Wildcard types may have a type variable as an upper bound,
207 * therefore, this must return a TypeD instead of a ClassD. <p/>
208 */
209 public TypeD getSuperclass();
210
211 /**
212 * Gets this type's super-interfaces. The name "getInterfaces" was
213 * chosen to be consistent with java/lang/Class.
214 *
215 * @return The collection of type declarations for this type's
216 * super-interfaces. May be zero-length. Will include all implicit
217 * base interfaces, e.g. all array types implement
218 * java/lang/Cloneable. <p/>
219 *
220 * Collection of TypeDs.
221 */
222 public Collection getInterfaces();
223
224 /**
225 * Recursively gets all superclasses and super-interfaces. Order is
226 * depth-first, classes before interfaces, left-to-right, no
227 * duplicates. <p/>
228 *
229 * @return The collection of type declarations for ALL base classes and
230 * base interfaces (including java.lang.Object). <p/>
231 *
232 * Collection of TypeDs.
233 */
234 public Collection getHierarchy();
235
236 /**
237 * True if this type is assignable from the subject type. Behavior
238 * should declaration reflection. Consider the following expression where
239 * S (subject) represents another type and T (this) represents this
240 * type. <p/>
241 *
242 * <pre>
243 * void method( S subject )
244 * {
245 * T variable = subject;
246 * }
247 * </pre>
248 *
249 * Notice that because the parameter subject is not a
250 * constant-value, the assignment conversion will not perform the
251 * implicit narrowing conversion. <p/>
252 *
253 * TODO: Should isAssignableFrom perform auto-boxing? What does
254 * reflection do? <p/>
255 *
256 * @return True if the above assignment is allowed. False if the
257 * answer is not known or if the answer is no.
258 */
259 public boolean isAssignableFrom( TypeD subject );
260
261
262 // ----------------------------------------------------------------------
263
264 /**
265 * Gets all declared fields. Includes synthetic fields and enum
266 * constants. <p/>
267 *
268 * @return The collection of field declarations for declared fields,
269 * synthetic or not, including enum constants. <p/>
270 *
271 * Collection of FieldDs.
272 */
273 public Collection getDeclaredFields();
274
275 /**
276 * Gets the first matching declared field, null if none. <p/>
277 *
278 * @param name The name to match. Require non-null.
279 *
280 * @return The field declaration for the first matching declared field,
281 * null if none.
282 */
283 public FieldD getDeclaredField( String name );
284
285 /**
286 * Gets all declared constructors. Includes synthetic
287 * constructors. <p/>
288 *
289 * Note: Constructors are not inherited, so the collection of
290 * declared constructors is the same as the collection of
291 * constructors. <p/>
292 *
293 * @return The collection of constructor declarations for declared
294 * constructors, synthetic or not. <p/>
295 *
296 * Collection of ConstructorDs.
297 */
298 public Collection getDeclaredConstructors();
299
300 /**
301 * Gets the matching declared constructor, null if none. <p/>
302 *
303 * @param parameters The exact parameter types to match. Null
304 * indicates an empty parameter list.
305 *
306 * @return The constructor declaration for the first matching
307 * constructor, null if none.
308 */
309 public MethodD getDeclaredConstructor( TypeD[] parameters );
310
311 /**
312 * Gets all declared methods. Does not include the hidden
313 * <code>clinit</code> method.
314 *
315 * @return The collection of method declarations for declared methods,
316 * excluding the <code>clinit</code> method. <p/>
317 *
318 * Collection of MethodDs.
319 */
320 public Collection getDeclaredMethods();
321
322 /**
323 * Gets all matching declared methods.
324 *
325 * @param name The method name to match. Require non-null.
326 *
327 * @return The collection of method declarations for matching declared
328 * methods. <p/>
329 *
330 * Collection of MethodDs.
331 */
332 public Collection getDeclaredMethods( String name );
333
334 /**
335 * Gets the matching declared method, null if none. <p/>
336 *
337 * @param name The method name to match. Require non-null.
338 *
339 * @param parameters The exact parameter types to match. Null
340 * indicates an empty parameter list.
341 *
342 * @return The method declaration for the first matching method, null if none.
343 */
344 public MethodD getDeclaredMethod( String name, TypeD[] parameters );
345
346 /**
347 * Gets all declared member classes. Does not include local and
348 * anonymous inner classes. <p/>
349 *
350 * TODO: Should this return local and anonymous inner classes? I
351 * don't remember what reflection does. <p/>
352 *
353 * @return The collection of class declarations for declared member
354 * classes. Only returns member classes that are directly enclosing
355 * in this type. Hence, a member class of a member class would not
356 * be listed here. <p/>
357 *
358 * Collection of ClassDs.
359 */
360 public Collection getDeclaredClasses();
361
362 /**
363 * Gets the matching member class, null if none.
364 *
365 * @return The class declaration for the matching declared member class.
366 */
367 public ClassD getDeclaredClass( String name );
368
369
370 // ----------------------------------------------------------------------
371
372 /**
373 * Gets all member fields, declared and inherited. The type
374 * hierarchy dictates order. <p/>
375 *
376 * For more detal on members, please see the Members discussion at
377 * {@link TypeD}. <p/>
378 *
379 * Note: The implicit "length" field for array types should be
380 * suppressed because according to the JLS, it is technically not a
381 * member variable. <p/>
382 *
383 * TODO: Should this list shadowed (hidden) fields? Technically,
384 * though they aren't visible, they are inherited. <p/>
385 *
386 * @return A collection of field declarations for all member fields,
387 * declared and inherited. <p/>
388 *
389 * Collection of FieldDs.
390 */
391 public Collection getFields();
392
393 /**
394 * Gets the matching member field, null if none.
395 *
396 * @param name The field name to match. Require non-null.
397 *
398 * @return The field declaration for the first matching member field,
399 * null if none.
400 */
401 public FieldD getField( String name );
402
403 /**
404 * Gets all member methods, declared and inherited. The type
405 * hierarchy dictates order. <p/>
406 *
407 * For more detal on members, please see the Members discussion at
408 * {@link TypeD}. <p/>
409 *
410 * TODO: Should overridden methods be listed? They are neither
411 * visible to the type's client nor are they inherited. <p/>
412 *
413 * TODO: If a client wanted to write a compiler and base it on the
414 * declaration interfaces (which should conceivably be possible), how
415 * does the client find out about not-inherited methods in order to
416 * display a meaningful error message? Should we address that here?
417 * <p/>
418 *
419 * @return A collection of method declarations for all member methods,
420 * declared and inherited. <p/>
421 *
422 * Collection of MethodDs.
423 */
424 public Collection getMethods();
425
426 /**
427 * Gets all matching methods.
428 *
429 * @param name The method name to match. Require non-null.
430 *
431 * @return A collection of method declarations for all matching member
432 * methods. <p/>
433 *
434 * Collection of MethodDs.
435 */
436 public Collection getMethods( String name );
437
438 /**
439 * Gets the first matching method, null if none.
440 *
441 * @param name The method name to match. Require non-null.
442 * @param parameters The exact parameter types to match. Null
443 * indicates an empty parameter list.
444 *
445 * @return The method declaration for the first matching method, null if
446 * none.
447 */
448 public MethodD getMethod( String name, TypeD[] parameters );
449
450 /**
451 * Gets all member classes, declared and inherited. The type
452 * hierarchy dictates order. <p/>
453 *
454 * For more detal on members, please see the Members discussion at
455 * {@link TypeD}. <p/>
456 *
457 * TODO: Should this list shadowed (hidden) member classes?
458 * Technically, though they aren't visible, they are inherited. <p/>
459 *
460 * @return A collection of class declarations for all member classes,
461 * declared and inherited. <p/>
462 *
463 * Collection of ClassDs.
464 */
465 public Collection getClasses();
466
467 /**
468 * Gets the first matching member class, null if none.
469 *
470 * @param name The simple class name to match. Require non-null.
471 *
472 * @return The class declaration for the first matching member class,
473 * null if none.
474 */
475 public ClassD getClass( String name );
476
477
478 // ----------------------------------------------------------------------
479
480 /**
481 * True if the other object is also a TypeM and declarations the same
482 * type. <p/>
483 *
484 * ClassDs and WildcardTypeDs are uniquely identified by their type
485 * signatures. TypeVariableDs are uniquely identified by both their
486 * owning declaration and type signature. <p/>
487 *
488 * @return True if o is a TypeD and declarations the same type.
489 */
490 public boolean equals( Object o );
491
492
493 // ----------------------------------------------------------------------
494 }