ModuleSummaryBuilder.java revision 3294:9adfb22ff08f
1/* 2 * Copyright (c) 2013, 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.IOException; 29import java.util.Set; 30 31import javax.lang.model.element.ModuleElement; 32import javax.lang.model.element.PackageElement; 33import javax.tools.StandardLocation; 34 35import jdk.javadoc.internal.doclets.toolkit.Content; 36import jdk.javadoc.internal.doclets.toolkit.ModuleSummaryWriter; 37import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; 38 39 40/** 41 * Builds the summary for a given module. 42 * 43 * <p><b>This is NOT part of any supported API. 44 * If you write code that depends on this, you do so at your own risk. 45 * This code and its internal interfaces are subject to change or 46 * deletion without notice.</b> 47 * 48 * @author Bhavesh Patel 49 */ 50public class ModuleSummaryBuilder extends AbstractBuilder { 51 /** 52 * The root element of the module summary XML is {@value}. 53 */ 54 public static final String ROOT = "ModuleDoc"; 55 56 /** 57 * The module being documented. 58 */ 59 private final ModuleElement mdle; 60 61 /** 62 * The doclet specific writer that will output the result. 63 */ 64 private final ModuleSummaryWriter moduleWriter; 65 66 /** 67 * The content that will be added to the module summary documentation tree. 68 */ 69 private Content contentTree; 70 71 /** 72 * The module package being documented. 73 */ 74 private PackageElement pkg; 75 76 /** 77 * Construct a new ModuleSummaryBuilder. 78 * 79 * @param context the build context. 80 * @param mdle the module being documented. 81 * @param moduleWriter the doclet specific writer that will output the 82 * result. 83 */ 84 private ModuleSummaryBuilder(Context context, 85 ModuleElement mdle, ModuleSummaryWriter moduleWriter) { 86 super(context); 87 this.mdle = mdle; 88 this.moduleWriter = moduleWriter; 89 } 90 91 /** 92 * Construct a new ModuleSummaryBuilder. 93 * 94 * @param context the build context. 95 * @param mdle the module being documented. 96 * @param moduleWriter the doclet specific writer that will output the 97 * result. 98 * 99 * @return an instance of a ModuleSummaryBuilder. 100 */ 101 public static ModuleSummaryBuilder getInstance(Context context, 102 ModuleElement mdle, ModuleSummaryWriter moduleWriter) { 103 return new ModuleSummaryBuilder(context, mdle, moduleWriter); 104 } 105 106 /** 107 * Build the module summary. 108 */ 109 public void build() throws IOException { 110 if (moduleWriter == null) { 111 //Doclet does not support this output. 112 return; 113 } 114 build(layoutParser.parseXML(ROOT), contentTree); 115 } 116 117 /** 118 * {@inheritDoc} 119 */ 120 public String getName() { 121 return ROOT; 122 } 123 124 /** 125 * Build the module documentation. 126 * 127 * @param node the XML element that specifies which components to document 128 * @param contentTree the content tree to which the documentation will be added 129 */ 130 public void buildModuleDoc(XMLNode node, Content contentTree) throws Exception { 131 contentTree = moduleWriter.getModuleHeader(mdle.getSimpleName().toString()); 132 buildChildren(node, contentTree); 133 moduleWriter.addModuleFooter(contentTree); 134 moduleWriter.printDocument(contentTree); 135 moduleWriter.close(); 136 // TEMPORARY: 137 // The use of SOURCE_PATH on the next line is temporary. As we transition into the 138 // modules world, this should migrate into using a location for the appropriate module 139 // on the MODULE_SOURCE_PATH, or (in the old doclet) simply deleted. 140 utils.copyDocFiles(configuration, StandardLocation.SOURCE_PATH, DocPaths.moduleSummary(mdle)); 141 } 142 143 /** 144 * Build the content for the module doc. 145 * 146 * @param node the XML element that specifies which components to document 147 * @param contentTree the content tree to which the module contents 148 * will be added 149 */ 150 public void buildContent(XMLNode node, Content contentTree) { 151 Content moduleContentTree = moduleWriter.getContentHeader(); 152 buildChildren(node, moduleContentTree); 153 moduleWriter.addModuleContent(contentTree, moduleContentTree); 154 } 155 156 /** 157 * Build the module summary. 158 * 159 * @param node the XML element that specifies which components to document 160 * @param moduleContentTree the module content tree to which the summaries will 161 * be added 162 */ 163 public void buildSummary(XMLNode node, Content moduleContentTree) { 164 Content summaryContentTree = moduleWriter.getSummaryHeader(); 165 buildChildren(node, summaryContentTree); 166 moduleContentTree.addContent(moduleWriter.getSummaryTree(summaryContentTree)); 167 } 168 169 /** 170 * Build the module package summary. 171 * 172 * @param node the XML element that specifies which components to document 173 * @param summaryContentTree the content tree to which the summaries will 174 * be added 175 */ 176 public void buildPackageSummary(XMLNode node, Content summaryContentTree) { 177 Set<PackageElement> packages = configuration.modulePackages.get(mdle); 178 if (!packages.isEmpty()) { 179 String packageTableSummary 180 = configuration.getText("doclet.Member_Table_Summary", 181 configuration.getText("doclet.Package_Summary"), 182 configuration.getText("doclet.packages")); 183 moduleWriter.addPackagesSummary( 184 packages, configuration.getText("doclet.Package_Summary"), 185 packageTableSummary, summaryContentTree); 186 } 187 } 188} 189