Wed, 31 Oct 2012 13:48:15 -0700
8001664: refactor javadoc to use abstraction to handle files
Reviewed-by: darcy
1 /*
2 * Copyright (c) 2001, 2012, 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 */
26 package com.sun.tools.doclets.formats.html;
28 import java.io.*;
30 import javax.tools.FileObject;
32 import com.sun.javadoc.*;
33 import com.sun.tools.doclets.formats.html.markup.*;
34 import com.sun.tools.doclets.internal.toolkit.*;
35 import com.sun.tools.doclets.internal.toolkit.util.*;
37 /**
38 * Converts Java Source Code to HTML.
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 * @since 1.4
48 */
49 public class SourceToHTMLConverter {
51 /**
52 * The number of trailing blank lines at the end of the page.
53 * This is inserted so that anchors at the bottom of small pages
54 * can be reached.
55 */
56 private static final int NUM_BLANK_LINES = 60;
58 /**
59 * New line to be added to the documentation.
60 */
61 private static final Content NEW_LINE = new RawHtml(DocletConstants.NL);
63 /**
64 * Relative path from the documentation root to the file that is being
65 * generated.
66 */
67 private static DocPath relativePath = DocPath.empty;
69 /**
70 * Source is converted to HTML using static methods below.
71 */
72 private SourceToHTMLConverter() {}
74 /**
75 * Convert the Classes in the given RootDoc to an HTML.
76 *
77 * @param configuration the configuration.
78 * @param rd the RootDoc to convert.
79 * @param outputdir the name of the directory to output to.
80 */
81 public static void convertRoot(ConfigurationImpl configuration, RootDoc rd,
82 DocPath outputdir) {
83 if (rd == null || outputdir == null) {
84 return;
85 }
86 PackageDoc[] pds = rd.specifiedPackages();
87 for (int i = 0; i < pds.length; i++) {
88 // If -nodeprecated option is set and the package is marked as deprecated,
89 // do not convert the package files to HTML.
90 if (!(configuration.nodeprecated && Util.isDeprecated(pds[i])))
91 convertPackage(configuration, pds[i], outputdir);
92 }
93 ClassDoc[] cds = rd.specifiedClasses();
94 for (int i = 0; i < cds.length; i++) {
95 // If -nodeprecated option is set and the class is marked as deprecated
96 // or the containing package is deprecated, do not convert the
97 // package files to HTML.
98 if (!(configuration.nodeprecated &&
99 (Util.isDeprecated(cds[i]) || Util.isDeprecated(cds[i].containingPackage()))))
100 convertClass(configuration, cds[i], outputdir);
101 }
102 }
104 /**
105 * Convert the Classes in the given Package to an HTML.
106 *
107 * @param configuration the configuration.
108 * @param pd the Package to convert.
109 * @param outputdir the name of the directory to output to.
110 */
111 public static void convertPackage(ConfigurationImpl configuration, PackageDoc pd,
112 DocPath outputdir) {
113 if (pd == null) {
114 return;
115 }
116 ClassDoc[] cds = pd.allClasses();
117 for (int i = 0; i < cds.length; i++) {
118 // If -nodeprecated option is set and the class is marked as deprecated,
119 // do not convert the package files to HTML. We do not check for
120 // containing package deprecation since it is already check in
121 // the calling method above.
122 if (!(configuration.nodeprecated && Util.isDeprecated(cds[i])))
123 convertClass(configuration, cds[i], outputdir);
124 }
125 }
127 /**
128 * Convert the given Class to an HTML.
129 *
130 * @param configuration the configuration.
131 * @param cd the class to convert.
132 * @param outputdir the name of the directory to output to.
133 */
134 public static void convertClass(ConfigurationImpl configuration, ClassDoc cd,
135 DocPath outputdir) {
136 if (cd == null) {
137 return;
138 }
139 try {
140 SourcePosition sp = cd.position();
141 if (sp == null)
142 return;
143 Reader r;
144 // temp hack until we can update SourcePosition API.
145 if (sp instanceof com.sun.tools.javadoc.SourcePositionImpl) {
146 FileObject fo = ((com.sun.tools.javadoc.SourcePositionImpl) sp).fileObject();
147 if (fo == null)
148 return;
149 r = fo.openReader(true);
150 } else {
151 File file = sp.file();
152 if (file == null)
153 return;
154 r = new FileReader(file);
155 }
156 LineNumberReader reader = new LineNumberReader(r);
157 int lineno = 1;
158 String line;
159 relativePath = DocPaths.SOURCE_OUTPUT
160 .resolve(DocPath.forPackage(cd))
161 .invert();
162 Content body = getHeader();
163 Content pre = new HtmlTree(HtmlTag.PRE);
164 try {
165 while ((line = reader.readLine()) != null) {
166 addLineNo(pre, lineno);
167 addLine(pre, line, configuration.sourcetab, lineno);
168 lineno++;
169 }
170 } finally {
171 reader.close();
172 }
173 addBlankLines(pre);
174 Content div = HtmlTree.DIV(HtmlStyle.sourceContainer, pre);
175 body.addContent(div);
176 writeToFile(body, outputdir.resolve(DocPath.forClass(cd)), configuration);
177 } catch (IOException e) {
178 e.printStackTrace();
179 }
180 }
182 /**
183 * Write the output to the file.
184 *
185 * @param body the documentation content to be written to the file.
186 * @param path the path for the file.
187 * @param configuration the Doclet configuration to pass notices to.
188 */
189 private static void writeToFile(Content body, DocPath path,
190 ConfigurationImpl configuration) throws IOException {
191 Content htmlDocType = DocType.Transitional();
192 Content head = new HtmlTree(HtmlTag.HEAD);
193 head.addContent(HtmlTree.TITLE(new StringContent(
194 configuration.getText("doclet.Window_Source_title"))));
195 head.addContent(getStyleSheetProperties(configuration));
196 Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(),
197 head, body);
198 Content htmlDocument = new HtmlDocument(htmlDocType, htmlTree);
199 configuration.message.notice("doclet.Generating_0", path.getPath());
200 DocFile df = DocFile.createFileForOutput(configuration, path);
201 Writer w = df.openWriter();
202 try {
203 htmlDocument.write(w, true);
204 } finally {
205 w.close();
206 }
208 }
210 /**
211 * Returns a link to the stylesheet file.
212 *
213 * @param configuration the doclet configuration for the current run of javadoc
214 * @return an HtmlTree for the lINK tag which provides the stylesheet location
215 */
216 public static HtmlTree getStyleSheetProperties(ConfigurationImpl configuration) {
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 }
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 }
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 }
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 tabLength the number of spaces for each tab.
264 * @param currentLineNo the current number.
265 */
266 private static void addLine(Content pre, String line, int tabLength,
267 int currentLineNo) {
268 if (line != null) {
269 StringBuilder lineBuffer = new StringBuilder(Util.escapeHtmlChars(line));
270 Util.replaceTabs(tabLength, lineBuffer);
271 pre.addContent(new RawHtml(lineBuffer.toString()));
272 Content anchor = HtmlTree.A_NAME("line." + Integer.toString(currentLineNo));
273 pre.addContent(anchor);
274 pre.addContent(NEW_LINE);
275 }
276 }
278 /**
279 * Add trailing blank lines at the end of the page.
280 *
281 * @param pre the content tree to which the blank lines will be added.
282 */
283 private static void addBlankLines(Content pre) {
284 for (int i = 0; i < NUM_BLANK_LINES; i++) {
285 pre.addContent(NEW_LINE);
286 }
287 }
289 /**
290 * Given a <code>Doc</code>, return an anchor name for it.
291 *
292 * @param d the <code>Doc</code> to check.
293 * @return the name of the anchor.
294 */
295 public static String getAnchorName(Doc d) {
296 return "line." + d.position().line();
297 }
298 }