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