ClassBuilder.java revision 3233:b5d08bc0d224
1/* 2 * Copyright (c) 2003, 2016, 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 jdk.javadoc.internal.doclets.toolkit.builders; 27 28import java.io.*; 29 30import javax.lang.model.element.PackageElement; 31import javax.lang.model.element.TypeElement; 32 33import jdk.javadoc.internal.doclets.toolkit.ClassWriter; 34import jdk.javadoc.internal.doclets.toolkit.Content; 35import jdk.javadoc.internal.doclets.toolkit.util.Utils; 36 37/** 38 * Builds the summary for a given class. 39 * 40 * <p><b>This is NOT part of any supported API. 41 * If you write code that depends on this, you do so at your own risk. 42 * This code and its internal interfaces are subject to change or 43 * deletion without notice.</b> 44 * 45 * @author Jamie Ho 46 * @author Bhavesh Patel (Modified) 47 */ 48public class ClassBuilder extends AbstractBuilder { 49 50 /** 51 * The root element of the class XML is {@value}. 52 */ 53 public static final String ROOT = "ClassDoc"; 54 55 /** 56 * The class being documented. 57 */ 58 private final TypeElement typeElement; 59 60 /** 61 * The doclet specific writer. 62 */ 63 private final ClassWriter writer; 64 65 /** 66 * Keep track of whether or not this typeElement is an interface. 67 */ 68 private final boolean isInterface; 69 70 /** 71 * Keep track of whether or not this typeElement is an enum. 72 */ 73 private final boolean isEnum; 74 75 /** 76 * The content tree for the class documentation. 77 */ 78 private Content contentTree; 79 80 private final Utils utils; 81 82 /** 83 * Construct a new ClassBuilder. 84 * 85 * @param context the build context 86 * @param typeElement the class being documented. 87 * @param writer the doclet specific writer. 88 */ 89 private ClassBuilder(Context context, TypeElement typeElement, ClassWriter writer) { 90 super(context); 91 this.typeElement = typeElement; 92 this.writer = writer; 93 this.utils = configuration.utils; 94 if (utils.isInterface(typeElement)) { 95 isInterface = true; 96 isEnum = false; 97 } else if (utils.isEnum(typeElement)) { 98 isInterface = false; 99 isEnum = true; 100 utils.setEnumDocumentation(typeElement); 101 } else { 102 isInterface = false; 103 isEnum = false; 104 } 105 } 106 107 /** 108 * Construct a new ClassBuilder. 109 * 110 * @param context the build context 111 * @param typeElement the class being documented. 112 * @param writer the doclet specific writer. 113 */ 114 public static ClassBuilder getInstance(Context context, 115 TypeElement typeElement, ClassWriter writer) { 116 return new ClassBuilder(context, typeElement, writer); 117 } 118 119 /** 120 * {@inheritDoc} 121 */ 122 public void build() throws IOException { 123 build(layoutParser.parseXML(ROOT), contentTree); 124 } 125 126 /** 127 * {@inheritDoc} 128 */ 129 public String getName() { 130 return ROOT; 131 } 132 133 /** 134 * Handles the {@literal <TypeElement>} tag. 135 * 136 * @param node the XML element that specifies which components to document 137 * @param contentTree the content tree to which the documentation will be added 138 */ 139 public void buildClassDoc(XMLNode node, Content contentTree) throws Exception { 140 String key; 141 if (isInterface) { 142 key = "doclet.Interface"; 143 } else if (isEnum) { 144 key = "doclet.Enum"; 145 } else { 146 key = "doclet.Class"; 147 } 148 contentTree = writer.getHeader(configuration.getText(key) + " " + 149 utils.getSimpleName(typeElement)); 150 Content classContentTree = writer.getClassContentHeader(); 151 buildChildren(node, classContentTree); 152 writer.addClassContentTree(contentTree, classContentTree); 153 writer.addFooter(contentTree); 154 writer.printDocument(contentTree); 155 writer.close(); 156 copyDocFiles(); 157 } 158 159 /** 160 * Build the class tree documentation. 161 * 162 * @param node the XML element that specifies which components to document 163 * @param classContentTree the content tree to which the documentation will be added 164 */ 165 public void buildClassTree(XMLNode node, Content classContentTree) { 166 writer.addClassTree(classContentTree); 167 } 168 169 /** 170 * Build the class information tree documentation. 171 * 172 * @param node the XML element that specifies which components to document 173 * @param classContentTree the content tree to which the documentation will be added 174 */ 175 public void buildClassInfo(XMLNode node, Content classContentTree) { 176 Content classInfoTree = writer.getClassInfoTreeHeader(); 177 buildChildren(node, classInfoTree); 178 classContentTree.addContent(writer.getClassInfo(classInfoTree)); 179 } 180 181 /** 182 * Build the typeparameters of this class. 183 * 184 * @param node the XML element that specifies which components to document 185 * @param classInfoTree the content tree to which the documentation will be added 186 */ 187 public void buildTypeParamInfo(XMLNode node, Content classInfoTree) { 188 writer.addTypeParamInfo(classInfoTree); 189 } 190 191 /** 192 * If this is an interface, list all super interfaces. 193 * 194 * @param node the XML element that specifies which components to document 195 * @param classInfoTree the content tree to which the documentation will be added 196 */ 197 public void buildSuperInterfacesInfo(XMLNode node, Content classInfoTree) { 198 writer.addSuperInterfacesInfo(classInfoTree); 199 } 200 201 /** 202 * If this is a class, list all interfaces implemented by this class. 203 * 204 * @param node the XML element that specifies which components to document 205 * @param classInfoTree the content tree to which the documentation will be added 206 */ 207 public void buildImplementedInterfacesInfo(XMLNode node, Content classInfoTree) { 208 writer.addImplementedInterfacesInfo(classInfoTree); 209 } 210 211 /** 212 * List all the classes extend this one. 213 * 214 * @param node the XML element that specifies which components to document 215 * @param classInfoTree the content tree to which the documentation will be added 216 */ 217 public void buildSubClassInfo(XMLNode node, Content classInfoTree) { 218 writer.addSubClassInfo(classInfoTree); 219 } 220 221 /** 222 * List all the interfaces that extend this one. 223 * 224 * @param node the XML element that specifies which components to document 225 * @param classInfoTree the content tree to which the documentation will be added 226 */ 227 public void buildSubInterfacesInfo(XMLNode node, Content classInfoTree) { 228 writer.addSubInterfacesInfo(classInfoTree); 229 } 230 231 /** 232 * If this is an interface, list all classes that implement this interface. 233 * 234 * @param node the XML element that specifies which components to document 235 * @param classInfoTree the content tree to which the documentation will be added 236 */ 237 public void buildInterfaceUsageInfo(XMLNode node, Content classInfoTree) { 238 writer.addInterfaceUsageInfo(classInfoTree); 239 } 240 241 /** 242 * If this is an functional interface, display appropriate message. 243 * 244 * @param node the XML element that specifies which components to document 245 * @param classInfoTree the content tree to which the documentation will be added 246 */ 247 public void buildFunctionalInterfaceInfo(XMLNode node, Content classInfoTree) { 248 writer.addFunctionalInterfaceInfo(classInfoTree); 249 } 250 251 /** 252 * If this class is deprecated, build the appropriate information. 253 * 254 * @param node the XML element that specifies which components to document 255 * @param classInfoTree the content tree to which the documentation will be added 256 */ 257 public void buildDeprecationInfo (XMLNode node, Content classInfoTree) { 258 writer.addClassDeprecationInfo(classInfoTree); 259 } 260 261 /** 262 * If this is an inner class or interface, list the enclosing class or interface. 263 * 264 * @param node the XML element that specifies which components to document 265 * @param classInfoTree the content tree to which the documentation will be added 266 */ 267 public void buildNestedClassInfo (XMLNode node, Content classInfoTree) { 268 writer.addNestedClassInfo(classInfoTree); 269 } 270 271 /** 272 * Copy the doc files. 273 */ 274 private void copyDocFiles() { 275 PackageElement containingPackage = utils.containingPackage(typeElement); 276 if((configuration.packages == null || 277 !configuration.packages.contains(containingPackage)) && 278 !containingPackagesSeen.contains(containingPackage)) { 279 //Only copy doc files dir if the containing package is not 280 //documented AND if we have not documented a class from the same 281 //package already. Otherwise, we are making duplicate copies. 282 utils.copyDocFiles(containingPackage); 283 containingPackagesSeen.add(containingPackage); 284 } 285 } 286 287 /** 288 * Build the signature of the current class. 289 * 290 * @param node the XML element that specifies which components to document 291 * @param classInfoTree the content tree to which the documentation will be added 292 */ 293 public void buildClassSignature(XMLNode node, Content classInfoTree) { 294 writer.addClassSignature(utils.modifiersToString(typeElement, true), classInfoTree); 295 } 296 297 /** 298 * Build the class description. 299 * 300 * @param node the XML element that specifies which components to document 301 * @param classInfoTree the content tree to which the documentation will be added 302 */ 303 public void buildClassDescription(XMLNode node, Content classInfoTree) { 304 writer.addClassDescription(classInfoTree); 305 } 306 307 /** 308 * Build the tag information for the current class. 309 * 310 * @param node the XML element that specifies which components to document 311 * @param classInfoTree the content tree to which the documentation will be added 312 */ 313 public void buildClassTagInfo(XMLNode node, Content classInfoTree) { 314 writer.addClassTagInfo(classInfoTree); 315 } 316 317 /** 318 * Build the member summary contents of the page. 319 * 320 * @param node the XML element that specifies which components to document 321 * @param classContentTree the content tree to which the documentation will be added 322 */ 323 public void buildMemberSummary(XMLNode node, Content classContentTree) throws Exception { 324 Content memberSummaryTree = writer.getMemberTreeHeader(); 325 configuration.getBuilderFactory(). 326 getMemberSummaryBuilder(writer).buildChildren(node, memberSummaryTree); 327 classContentTree.addContent(writer.getMemberSummaryTree(memberSummaryTree)); 328 } 329 330 /** 331 * Build the member details contents of the page. 332 * 333 * @param node the XML element that specifies which components to document 334 * @param classContentTree the content tree to which the documentation will be added 335 */ 336 public void buildMemberDetails(XMLNode node, Content classContentTree) { 337 Content memberDetailsTree = writer.getMemberTreeHeader(); 338 buildChildren(node, memberDetailsTree); 339 classContentTree.addContent(writer.getMemberDetailsTree(memberDetailsTree)); 340 } 341 342 /** 343 * Build the enum constants documentation. 344 * 345 * @param node the XML element that specifies which components to document 346 * @param memberDetailsTree the content tree to which the documentation will be added 347 */ 348 public void buildEnumConstantsDetails(XMLNode node, 349 Content memberDetailsTree) throws Exception { 350 configuration.getBuilderFactory(). 351 getEnumConstantsBuilder(writer).buildChildren(node, memberDetailsTree); 352 } 353 354 /** 355 * Build the field documentation. 356 * 357 * @param node the XML element that specifies which components to document 358 * @param memberDetailsTree the content tree to which the documentation will be added 359 */ 360 public void buildFieldDetails(XMLNode node, 361 Content memberDetailsTree) throws Exception { 362 configuration.getBuilderFactory(). 363 getFieldBuilder(writer).buildChildren(node, memberDetailsTree); 364 } 365 366 /** 367 * Build the property documentation. 368 * 369 * @param elements the XML elements that specify how a field is documented. 370 */ 371 public void buildPropertyDetails(XMLNode node, 372 Content memberDetailsTree) throws Exception { 373 configuration.getBuilderFactory(). 374 getPropertyBuilder(writer).buildChildren(node, memberDetailsTree); 375 } 376 377 /** 378 * Build the constructor documentation. 379 * 380 * @param node the XML element that specifies which components to document 381 * @param memberDetailsTree the content tree to which the documentation will be added 382 */ 383 public void buildConstructorDetails(XMLNode node, 384 Content memberDetailsTree) throws Exception { 385 configuration.getBuilderFactory(). 386 getConstructorBuilder(writer).buildChildren(node, memberDetailsTree); 387 } 388 389 /** 390 * Build the method documentation. 391 * 392 * @param node the XML element that specifies which components to document 393 * @param memberDetailsTree the content tree to which the documentation will be added 394 */ 395 public void buildMethodDetails(XMLNode node, 396 Content memberDetailsTree) throws Exception { 397 configuration.getBuilderFactory(). 398 getMethodBuilder(writer).buildChildren(node, memberDetailsTree); 399 } 400} 401