Thu, 04 Feb 2010 10:14:28 -0800
6923080: TreeScanner.visitNewClass should scan tree.typeargs
Reviewed-by: darcy
1 /*
2 * Copyright 1998-2006 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 */
26 package com.sun.javadoc;
29 /**
30 * Represents a java class or interface and provides access to
31 * information about the class, the class's comment and tags, and the
32 * members of the class. A ClassDoc only exists if it was
33 * processed in this run of javadoc. References to classes
34 * which may or may not have been processed in this run are
35 * referred to using Type (which can be converted to ClassDoc,
36 * if possible).
37 *
38 * @see Type
39 *
40 * @since 1.2
41 * @author Kaiyang Liu (original)
42 * @author Robert Field (rewrite)
43 */
44 public interface ClassDoc extends ProgramElementDoc, Type {
46 /**
47 * Return true if this class is abstract. Return true
48 * for all interfaces.
49 */
50 boolean isAbstract();
52 /**
53 * Return true if this class implements or interface extends
54 * <code>java.io.Serializable</code>.
55 *
56 * Since <code>java.io.Externalizable</code> extends
57 * <code>java.io.Serializable</code>,
58 * Externalizable objects are also Serializable.
59 */
60 boolean isSerializable();
62 /**
63 * Return true if this class implements or interface extends
64 * <code>java.io.Externalizable</code>.
65 */
66 boolean isExternalizable();
68 /**
69 * Return the serialization methods for this class or
70 * interface.
71 *
72 * @return an array of MethodDoc objects that represents
73 * the serialization methods for this class or interface.
74 */
75 MethodDoc[] serializationMethods();
77 /**
78 * Return the Serializable fields of this class or interface.
79 * <p>
80 * Return either a list of default fields documented by
81 * <code>serial</code> tag<br>
82 * or return a single <code>FieldDoc</code> for
83 * <code>serialPersistentField</code> member.
84 * There should be a <code>serialField</code> tag for
85 * each Serializable field defined by an <code>ObjectStreamField</code>
86 * array component of <code>serialPersistentField</code>.
87 *
88 * @return an array of <code>FieldDoc</code> objects for the Serializable
89 * fields of this class or interface.
90 *
91 * @see #definesSerializableFields()
92 * @see SerialFieldTag
93 */
94 FieldDoc[] serializableFields();
96 /**
97 * Return true if Serializable fields are explicitly defined with
98 * the special class member <code>serialPersistentFields</code>.
99 *
100 * @see #serializableFields()
101 * @see SerialFieldTag
102 */
103 boolean definesSerializableFields();
105 /**
106 * Return the superclass of this class. Return null if this is an
107 * interface.
108 *
109 * <p> <i>This method cannot accommodate certain generic type constructs.
110 * The <code>superclassType</code> method should be used instead.</i>
111 *
112 * @return the ClassDoc for the superclass of this class, null if
113 * there is no superclass.
114 * @see #superclassType
115 */
116 ClassDoc superclass();
118 /**
119 * Return the superclass of this class. Return null if this is an
120 * interface. A superclass is represented by either a
121 * <code>ClassDoc</code> or a <code>ParametrizedType</code>.
122 *
123 * @return the superclass of this class, or null if there is no superclass.
124 * @since 1.5
125 */
126 Type superclassType();
128 /**
129 * Test whether this class is a subclass of the specified class.
130 * If this is an interface, return false for all classes except
131 * <code>java.lang.Object</code> (we must keep this unexpected
132 * behavior for compatibility reasons).
133 *
134 * @param cd the candidate superclass.
135 * @return true if cd is a superclass of this class.
136 */
137 boolean subclassOf(ClassDoc cd);
139 /**
140 * Return interfaces implemented by this class or interfaces extended
141 * by this interface. Includes only directly-declared interfaces, not
142 * inherited interfaces.
143 * Return an empty array if there are no interfaces.
144 *
145 * <p> <i>This method cannot accommodate certain generic type constructs.
146 * The <code>interfaceTypes</code> method should be used instead.</i>
147 *
148 * @return an array of ClassDoc objects representing the interfaces.
149 * @see #interfaceTypes
150 */
151 ClassDoc[] interfaces();
153 /**
154 * Return interfaces implemented by this class or interfaces extended
155 * by this interface. Includes only directly-declared interfaces, not
156 * inherited interfaces.
157 * Return an empty array if there are no interfaces.
158 *
159 * @return an array of interfaces, each represented by a
160 * <code>ClassDoc</code> or a <code>ParametrizedType</code>.
161 * @since 1.5
162 */
163 Type[] interfaceTypes();
165 /**
166 * Return the formal type parameters of this class or interface.
167 * Return an empty array if there are none.
168 *
169 * @return the formal type parameters of this class or interface.
170 * @since 1.5
171 */
172 TypeVariable[] typeParameters();
174 /**
175 * Return the type parameter tags of this class or interface.
176 * Return an empty array if there are none.
177 *
178 * @return the type parameter tags of this class or interface.
179 * @since 1.5
180 */
181 ParamTag[] typeParamTags();
183 /**
184 * Return
185 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a>
186 * fields in this class or interface.
187 * Excludes enum constants if this is an enum type.
188 *
189 * @return an array of FieldDoc objects representing the included
190 * fields in this class or interface.
191 */
192 FieldDoc[] fields();
194 /**
195 * Return fields in this class or interface, filtered to the specified
196 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">access
197 * modifier option</a>.
198 * Excludes enum constants if this is an enum type.
199 *
200 * @param filter Specify true to filter according to the specified access
201 * modifier option.
202 * Specify false to include all fields regardless of
203 * access modifier option.
204 * @return an array of FieldDoc objects representing the included
205 * fields in this class or interface.
206 */
207 FieldDoc[] fields(boolean filter);
209 /**
210 * Return the enum constants if this is an enum type.
211 * Return an empty array if there are no enum constants, or if
212 * this is not an enum type.
213 *
214 * @return the enum constants if this is an enum type.
215 */
216 FieldDoc[] enumConstants();
218 /**
219 * Return
220 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a>
221 * methods in this class or interface.
222 * Same as <code>methods(true)</code>.
223 *
224 * @return an array of MethodDoc objects representing the included
225 * methods in this class or interface. Does not include
226 * constructors or annotation type elements.
227 */
228 MethodDoc[] methods();
230 /**
231 * Return methods in this class or interface, filtered to the specified
232 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">access
233 * modifier option</a>. Does not include constructors or annotation
234 * type elements.
235 *
236 * @param filter Specify true to filter according to the specified access
237 * modifier option.
238 * Specify false to include all methods regardless of
239 * access modifier option.
240 * @return an array of MethodDoc objects representing the included
241 * methods in this class or interface.
242 */
243 MethodDoc[] methods(boolean filter);
245 /**
246 * Return
247 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a>
248 * constructors in this class. An array containing the default
249 * no-arg constructor is returned if no other constructors exist.
250 * Return empty array if this is an interface.
251 *
252 * @return an array of ConstructorDoc objects representing the included
253 * constructors in this class.
254 */
255 ConstructorDoc[] constructors();
257 /**
258 * Return constructors in this class, filtered to the specified
259 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">access
260 * modifier option</a>. Return an array containing the default
261 * no-arg constructor if no other constructors exist.
262 *
263 * @param filter Specify true to filter according to the specified access
264 * modifier option.
265 * Specify false to include all constructors regardless of
266 * access modifier option.
267 * @return an array of ConstructorDoc objects representing the included
268 * constructors in this class.
269 */
270 ConstructorDoc[] constructors(boolean filter);
273 /**
274 * Return
275 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a>
276 * nested classes and interfaces within this class or interface.
277 * This includes both static and non-static nested classes.
278 * (This method should have been named <code>nestedClasses()</code>,
279 * as inner classes are technically non-static.) Anonymous and local classes
280 * or interfaces are not included.
281 *
282 * @return an array of ClassDoc objects representing the included classes
283 * and interfaces defined in this class or interface.
284 */
285 ClassDoc[] innerClasses();
287 /**
288 * Return nested classes and interfaces within this class or interface
289 * filtered to the specified
290 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">access
291 * modifier option</a>.
292 * This includes both static and non-static nested classes.
293 * Anonymous and local classes are not included.
294 *
295 * @param filter Specify true to filter according to the specified access
296 * modifier option.
297 * Specify false to include all nested classes regardless of
298 * access modifier option.
299 * @return a filtered array of ClassDoc objects representing the included
300 * classes and interfaces defined in this class or interface.
301 */
302 ClassDoc[] innerClasses(boolean filter);
304 /**
305 * Find the specified class or interface within the context of this class doc.
306 * Search order: 1) qualified name, 2) nested in this class or interface,
307 * 3) in this package, 4) in the class imports, 5) in the package imports.
308 * Return the ClassDoc if found, null if not found.
309 */
310 ClassDoc findClass(String className);
312 /**
313 * Get the list of classes and interfaces declared as imported.
314 * These are called "single-type-import declarations" in the
315 * Java Language Specification.
316 *
317 * @return an array of ClassDoc representing the imported classes.
318 *
319 * @deprecated Import declarations are implementation details that
320 * should not be exposed here. In addition, not all imported
321 * classes are imported through single-type-import declarations.
322 */
323 @Deprecated
324 ClassDoc[] importedClasses();
326 /**
327 * Get the list of packages declared as imported.
328 * These are called "type-import-on-demand declarations" in the
329 * Java Language Specification.
330 *
331 * @return an array of PackageDoc representing the imported packages.
332 *
333 * @deprecated Import declarations are implementation details that
334 * should not be exposed here. In addition, this method's
335 * return type does not allow for all type-import-on-demand
336 * declarations to be returned.
337 */
338 @Deprecated
339 PackageDoc[] importedPackages();
340 }