SourceToHTMLConverter.java revision 3233:b5d08bc0d224
1/* 2 * Copyright (c) 2001, 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.formats.html; 27 28import java.io.*; 29 30import javax.lang.model.element.Element; 31import javax.lang.model.element.PackageElement; 32import javax.lang.model.element.TypeElement; 33import javax.tools.FileObject; 34 35import jdk.javadoc.doclet.DocletEnvironment; 36import jdk.javadoc.internal.doclets.formats.html.markup.DocType; 37import jdk.javadoc.internal.doclets.formats.html.markup.HtmlDocument; 38import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; 39import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag; 40import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; 41import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; 42import jdk.javadoc.internal.doclets.toolkit.Content; 43import jdk.javadoc.internal.doclets.toolkit.util.DocFile; 44import jdk.javadoc.internal.doclets.toolkit.util.DocPath; 45import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; 46import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; 47import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants; 48import jdk.javadoc.internal.doclets.toolkit.util.Utils; 49 50/** 51 * Converts Java Source Code to HTML. 52 * 53 * <p><b>This is NOT part of any supported API. 54 * If you write code that depends on this, you do so at your own risk. 55 * This code and its internal interfaces are subject to change or 56 * deletion without notice.</b> 57 * 58 * @author Jamie Ho 59 * @author Bhavesh Patel (Modified) 60 */ 61public class SourceToHTMLConverter { 62 63 /** 64 * The number of trailing blank lines at the end of the page. 65 * This is inserted so that anchors at the bottom of small pages 66 * can be reached. 67 */ 68 private static final int NUM_BLANK_LINES = 60; 69 70 /** 71 * New line to be added to the documentation. 72 */ 73 private static final String NEW_LINE = DocletConstants.NL; 74 75 private final ConfigurationImpl configuration; 76 private final Utils utils; 77 78 private final DocletEnvironment rootDoc; 79 80 private DocPath outputdir; 81 82 /** 83 * Relative path from the documentation root to the file that is being 84 * generated. 85 */ 86 private DocPath relativePath = DocPath.empty; 87 88 private SourceToHTMLConverter(ConfigurationImpl configuration, DocletEnvironment rd, 89 DocPath outputdir) { 90 this.configuration = configuration; 91 this.utils = configuration.utils; 92 this.rootDoc = rd; 93 this.outputdir = outputdir; 94 } 95 96 /** 97 * Translate the TypeElements in the given DocletEnvironment to HTML representation. 98 * 99 * @param configuration the configuration. 100 * @param root the DocletEnvironment to convert. 101 * @param outputdir the name of the directory to output to. 102 */ 103 public static void convertRoot(ConfigurationImpl configuration, DocletEnvironment root, 104 DocPath outputdir) { 105 new SourceToHTMLConverter(configuration, root, outputdir).generate(); 106 } 107 108 void generate() { 109 if (rootDoc == null || outputdir == null) { 110 return; 111 } 112 for (PackageElement pkg : utils.getSpecifiedPackages()) { 113 // If -nodeprecated option is set and the package is marked as deprecated, 114 // do not convert the package files to HTML. 115 if (!(configuration.nodeprecated && utils.isDeprecated(pkg))) 116 convertPackage(pkg, outputdir); 117 } 118 for (TypeElement te : utils.getSpecifiedClasses()) { 119 // If -nodeprecated option is set and the class is marked as deprecated 120 // or the containing package is deprecated, do not convert the 121 // package files to HTML. 122 if (!(configuration.nodeprecated && 123 (utils.isDeprecated(te) || utils.isDeprecated(utils.containingPackage(te))))) 124 convertClass(te, outputdir); 125 } 126 } 127 128 /** 129 * Convert the Classes in the given Package to an HTML. 130 * 131 * @param pkg the Package to convert. 132 * @param outputdir the name of the directory to output to. 133 */ 134 public void convertPackage(PackageElement pkg, DocPath outputdir) { 135 if (pkg == null) { 136 return; 137 } 138 for (Element te : utils.getAllClasses(pkg)) { 139 // If -nodeprecated option is set and the class is marked as deprecated, 140 // do not convert the package files to HTML. We do not check for 141 // containing package deprecation since it is already check in 142 // the calling method above. 143 if (!(configuration.nodeprecated && utils.isDeprecated(te))) 144 convertClass((TypeElement)te, outputdir); 145 } 146 } 147 148 /** 149 * Convert the given Class to an HTML. 150 * 151 * @param te the class to convert. 152 * @param outputdir the name of the directory to output to. 153 */ 154 public void convertClass(TypeElement te, DocPath outputdir) { 155 if (te == null) { 156 return; 157 } 158 try { 159 FileObject fo = utils.getFileObject(te); 160 if (fo == null) 161 return; 162 Reader r = fo.openReader(true); 163 int lineno = 1; 164 String line; 165 relativePath = DocPaths.SOURCE_OUTPUT 166 .resolve(DocPath.forPackage(utils, te)) 167 .invert(); 168 Content body = getHeader(); 169 Content pre = new HtmlTree(HtmlTag.PRE); 170 try (LineNumberReader reader = new LineNumberReader(r)) { 171 while ((line = reader.readLine()) != null) { 172 addLineNo(pre, lineno); 173 addLine(pre, line, lineno); 174 lineno++; 175 } 176 } 177 addBlankLines(pre); 178 Content div = HtmlTree.DIV(HtmlStyle.sourceContainer, pre); 179 body.addContent((configuration.allowTag(HtmlTag.MAIN)) ? HtmlTree.MAIN(div) : div); 180 writeToFile(body, outputdir.resolve(DocPath.forClass(utils, te))); 181 } catch (IOException e) { 182 throw new DocletAbortException(e); 183 } 184 } 185 186 /** 187 * Write the output to the file. 188 * 189 * @param body the documentation content to be written to the file. 190 * @param path the path for the file. 191 */ 192 private void writeToFile(Content body, DocPath path) throws IOException { 193 Content htmlDocType = configuration.isOutputHtml5() 194 ? DocType.HTML5 195 : DocType.TRANSITIONAL; 196 Content head = new HtmlTree(HtmlTag.HEAD); 197 head.addContent(HtmlTree.TITLE(new StringContent( 198 configuration.getText("doclet.Window_Source_title")))); 199 head.addContent(getStyleSheetProperties()); 200 Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(), 201 head, body); 202 Content htmlDocument = new HtmlDocument(htmlDocType, htmlTree); 203 configuration.message.notice("doclet.Generating_0", path.getPath()); 204 DocFile df = DocFile.createFileForOutput(configuration, path); 205 try (Writer w = df.openWriter()) { 206 htmlDocument.write(w, true); 207 } 208 209 } 210 211 /** 212 * Returns a link to the stylesheet file. 213 * 214 * @return an HtmlTree for the lINK tag which provides the stylesheet location 215 */ 216 public HtmlTree getStyleSheetProperties() { 217 String filename = configuration.stylesheetfile; 218 DocPath stylesheet; 219 if (filename.length() > 0) { 220 DocFile file = DocFile.createFileForInput(configuration, filename); 221 stylesheet = DocPath.create(file.getName()); 222 } else { 223 stylesheet = DocPaths.STYLESHEET; 224 } 225 DocPath p = relativePath.resolve(stylesheet); 226 HtmlTree link = HtmlTree.LINK("stylesheet", "text/css", p.getPath(), "Style"); 227 return link; 228 } 229 230 /** 231 * Get the header. 232 * 233 * @return the header content for the HTML file 234 */ 235 private static Content getHeader() { 236 return new HtmlTree(HtmlTag.BODY); 237 } 238 239 /** 240 * Add the line numbers for the source code. 241 * 242 * @param pre the content tree to which the line number will be added 243 * @param lineno The line number 244 */ 245 private static void addLineNo(Content pre, int lineno) { 246 HtmlTree span = new HtmlTree(HtmlTag.SPAN); 247 span.addStyle(HtmlStyle.sourceLineNo); 248 if (lineno < 10) { 249 span.addContent("00" + Integer.toString(lineno)); 250 } else if (lineno < 100) { 251 span.addContent("0" + Integer.toString(lineno)); 252 } else { 253 span.addContent(Integer.toString(lineno)); 254 } 255 pre.addContent(span); 256 } 257 258 /** 259 * Add a line from source to the HTML file that is generated. 260 * 261 * @param pre the content tree to which the line will be added. 262 * @param line the string to format. 263 * @param currentLineNo the current number. 264 */ 265 private void addLine(Content pre, String line, int currentLineNo) { 266 if (line != null) { 267 Content anchor = HtmlTree.A(configuration.htmlVersion, 268 "line." + Integer.toString(currentLineNo), 269 new StringContent(utils.replaceTabs(line))); 270 pre.addContent(anchor); 271 pre.addContent(NEW_LINE); 272 } 273 } 274 275 /** 276 * Add trailing blank lines at the end of the page. 277 * 278 * @param pre the content tree to which the blank lines will be added. 279 */ 280 private static void addBlankLines(Content pre) { 281 for (int i = 0; i < NUM_BLANK_LINES; i++) { 282 pre.addContent(NEW_LINE); 283 } 284 } 285 286 /** 287 * Given a <code>Doc</code>, return an anchor name for it. 288 * 289 * @param d the <code>Doc</code> to check. 290 * @return the name of the anchor. 291 */ 292 public static String getAnchorName(Utils utils, Element e) { 293 return "line." + utils.getLineNumber(e); 294 } 295} 296