View Javadoc
1   /*
2    * Copyright (c) 1998, 2013, Oracle and/or its affiliates. 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.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package com.sun.javadoc;
27  
28  
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 {
45  
46      /**
47       * Return true if this class is abstract.  Return true
48       * for all interfaces.
49       */
50      boolean isAbstract();
51  
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();
61  
62      /**
63       * Return true if this class implements or interface extends
64       * <code>java.io.Externalizable</code>.
65       */
66      boolean isExternalizable();
67  
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();
76  
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();
95  
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();
104 
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();
117 
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();
127 
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);
138 
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();
152 
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();
164 
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();
173 
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();
182 
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();
193 
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);
208 
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();
217 
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();
229 
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);
244 
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();
256 
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);
271 
272 
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();
286 
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);
303 
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);
311 
312     /**
313      * Get the list of classes and interfaces declared as imported.
314      * These are called "single-type-import declarations" in
315      * <cite>The Java&trade; Language Specification</cite>.
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();
325 
326     /**
327      * Get the list of packages declared as imported.
328      * These are called "type-import-on-demand declarations" in
329      * <cite>The Java&trade; Language Specification</cite>.
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 }