ClassDoc


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