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