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