Tue, 23 Oct 2012 13:20:37 -0700
8000741: refactor javadoc to use abstraction to handle relative paths
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.*;
29 import javax.tools.FileObject;
30 import com.sun.javadoc.*;
31 import com.sun.tools.doclets.internal.toolkit.*;
32 import com.sun.tools.doclets.internal.toolkit.util.*;
33 import com.sun.tools.doclets.formats.html.markup.*;
35 /**
36 * Converts Java Source Code to HTML.
37 *
38 * <p><b>This is NOT part of any supported API.
39 * If you write code that depends on this, you do so at your own risk.
40 * This code and its internal interfaces are subject to change or
41 * deletion without notice.</b>
42 *
43 * @author Jamie Ho
44 * @author Bhavesh Patel (Modified)
45 * @since 1.4
46 */
47 public class SourceToHTMLConverter {
49 /**
50 * The number of trailing blank lines at the end of the page.
51 * This is inserted so that anchors at the bottom of small pages
52 * can be reached.
53 */
54 private static final int NUM_BLANK_LINES = 60;
56 /**
57 * New line to be added to the documentation.
58 */
59 private static final Content NEW_LINE = new RawHtml(DocletConstants.NL);
61 /**
62 * Relative path from the documentation root to the file that is being
63 * generated.
64 */
65 private static DocPath relativePath = DocPath.empty;
67 /**
68 * Source is converted to HTML using static methods below.
69 */
70 private SourceToHTMLConverter() {}
72 /**
73 * Convert the Classes in the given RootDoc to an HTML.
74 *
75 * @param configuration the configuration.
76 * @param rd the RootDoc to convert.
77 * @param outputdir the name of the directory to output to.
78 */
79 public static void convertRoot(ConfigurationImpl configuration, RootDoc rd,
80 DocPath outputdir) {
81 if (rd == null || outputdir == null) {
82 return;
83 }
84 PackageDoc[] pds = rd.specifiedPackages();
85 for (int i = 0; i < pds.length; i++) {
86 // If -nodeprecated option is set and the package is marked as deprecated,
87 // do not convert the package files to HTML.
88 if (!(configuration.nodeprecated && Util.isDeprecated(pds[i])))
89 convertPackage(configuration, pds[i], outputdir);
90 }
91 ClassDoc[] cds = rd.specifiedClasses();
92 for (int i = 0; i < cds.length; i++) {
93 // If -nodeprecated option is set and the class is marked as deprecated
94 // or the containing package is deprecated, do not convert the
95 // package files to HTML.
96 if (!(configuration.nodeprecated &&
97 (Util.isDeprecated(cds[i]) || Util.isDeprecated(cds[i].containingPackage()))))
98 convertClass(configuration, cds[i],
99 getPackageOutputDir(outputdir, cds[i].containingPackage()));
100 }
101 }
103 /**
104 * Convert the Classes in the given Package to an HTML.
105 *
106 * @param configuration the configuration.
107 * @param pd the Package to convert.
108 * @param outputdir the name of the directory to output to.
109 */
110 public static void convertPackage(ConfigurationImpl configuration, PackageDoc pd,
111 DocPath outputdir) {
112 if (pd == null || outputdir == null) {
113 return;
114 }
115 DocPath classOutputdir = getPackageOutputDir(outputdir, pd);
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], classOutputdir);
124 }
125 }
127 /**
128 * Return the directory write output to for the given package.
129 *
130 * @param outputDir the directory to output to.
131 * @param pd the Package to generate output for.
132 * @return the package output directory as a String.
133 */
134 private static DocPath getPackageOutputDir(DocPath outputDir, PackageDoc pd) {
135 return outputDir.resolve(DocPath.forPackage(pd));
136 }
138 /**
139 * Convert the given Class to an HTML.
140 *
141 * @param configuration the configuration.
142 * @param cd the class to convert.
143 * @param outputdir the name of the directory to output to.
144 */
145 public static void convertClass(ConfigurationImpl configuration, ClassDoc cd,
146 DocPath outputdir) {
147 if (cd == null || outputdir == null) {
148 return;
149 }
150 try {
151 SourcePosition sp = cd.position();
152 if (sp == null)
153 return;
154 Reader r;
155 // temp hack until we can update SourcePosition API.
156 if (sp instanceof com.sun.tools.javadoc.SourcePositionImpl) {
157 FileObject fo = ((com.sun.tools.javadoc.SourcePositionImpl) sp).fileObject();
158 if (fo == null)
159 return;
160 r = fo.openReader(true);
161 } else {
162 File file = sp.file();
163 if (file == null)
164 return;
165 r = new FileReader(file);
166 }
167 LineNumberReader reader = new LineNumberReader(r);
168 int lineno = 1;
169 String line;
170 relativePath = DocPaths.SOURCE_OUTPUT
171 .resolve(DocPath.forPackage(cd))
172 .invert();
173 Content body = getHeader();
174 Content pre = new HtmlTree(HtmlTag.PRE);
175 try {
176 while ((line = reader.readLine()) != null) {
177 addLineNo(pre, lineno);
178 addLine(pre, line, configuration.sourcetab, lineno);
179 lineno++;
180 }
181 } finally {
182 reader.close();
183 }
184 addBlankLines(pre);
185 Content div = HtmlTree.DIV(HtmlStyle.sourceContainer, pre);
186 body.addContent(div);
187 writeToFile(body, outputdir, cd.name(), configuration);
188 } catch (Exception e){
189 e.printStackTrace();
190 }
191 }
193 /**
194 * Write the output to the file.
195 *
196 * @param body the documentation content to be written to the file.
197 * @param outputDir the directory to output to.
198 * @param className the name of the class that I am converting to HTML.
199 * @param configuration the Doclet configuration to pass notices to.
200 */
201 private static void writeToFile(Content body, DocPath outputDir,
202 String className, ConfigurationImpl configuration) throws IOException {
203 Content htmlDocType = DocType.Transitional();
204 Content head = new HtmlTree(HtmlTag.HEAD);
205 head.addContent(HtmlTree.TITLE(new StringContent(
206 configuration.getText("doclet.Window_Source_title"))));
207 head.addContent(getStyleSheetProperties(configuration));
208 Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(),
209 head, body);
210 Content htmlDocument = new HtmlDocument(htmlDocType, htmlTree);
211 File dir = outputDir.resolveAgainst(configuration.destDirName);
212 dir.mkdirs();
213 File newFile = new File(dir, className + ".html");
214 configuration.message.notice("doclet.Generating_0", newFile.getPath());
215 FileOutputStream fout = new FileOutputStream(newFile);
216 BufferedWriter bw = new BufferedWriter(new OutputStreamWriter(fout));
217 bw.write(htmlDocument.toString());
218 bw.close();
219 fout.close();
220 }
222 /**
223 * Returns a link to the stylesheet file.
224 *
225 * @param configuration the doclet configuration for the current run of javadoc
226 * @return an HtmlTree for the lINK tag which provides the stylesheet location
227 */
228 public static HtmlTree getStyleSheetProperties(ConfigurationImpl configuration) {
229 String filename = configuration.stylesheetfile;
230 DocPath stylesheet;
231 if (filename.length() > 0) {
232 stylesheet = DocPath.create(new File(filename).getName());
233 } else {
234 stylesheet = DocPaths.STYLESHEET;
235 }
236 DocPath p = relativePath.resolve(stylesheet);
237 HtmlTree link = HtmlTree.LINK("stylesheet", "text/css", p.getPath(), "Style");
238 return link;
239 }
241 /**
242 * Get the header.
243 *
244 * @return the header content for the HTML file
245 */
246 private static Content getHeader() {
247 return new HtmlTree(HtmlTag.BODY);
248 }
250 /**
251 * Add the line numbers for the source code.
252 *
253 * @param pre the content tree to which the line number will be added
254 * @param lineno The line number
255 */
256 private static void addLineNo(Content pre, int lineno) {
257 HtmlTree span = new HtmlTree(HtmlTag.SPAN);
258 span.addStyle(HtmlStyle.sourceLineNo);
259 if (lineno < 10) {
260 span.addContent("00" + Integer.toString(lineno));
261 } else if (lineno < 100) {
262 span.addContent("0" + Integer.toString(lineno));
263 } else {
264 span.addContent(Integer.toString(lineno));
265 }
266 pre.addContent(span);
267 }
269 /**
270 * Add a line from source to the HTML file that is generated.
271 *
272 * @param pre the content tree to which the line will be added.
273 * @param line the string to format.
274 * @param tabLength the number of spaces for each tab.
275 * @param currentLineNo the current number.
276 */
277 private static void addLine(Content pre, String line, int tabLength,
278 int currentLineNo) {
279 if (line != null) {
280 StringBuilder lineBuffer = new StringBuilder(Util.escapeHtmlChars(line));
281 Util.replaceTabs(tabLength, lineBuffer);
282 pre.addContent(new RawHtml(lineBuffer.toString()));
283 Content anchor = HtmlTree.A_NAME("line." + Integer.toString(currentLineNo));
284 pre.addContent(anchor);
285 pre.addContent(NEW_LINE);
286 }
287 }
289 /**
290 * Add trailing blank lines at the end of the page.
291 *
292 * @param pre the content tree to which the blank lines will be added.
293 */
294 private static void addBlankLines(Content pre) {
295 for (int i = 0; i < NUM_BLANK_LINES; i++) {
296 pre.addContent(NEW_LINE);
297 }
298 }
300 /**
301 * Given a <code>Doc</code>, return an anchor name for it.
302 *
303 * @param d the <code>Doc</code> to check.
304 * @return the name of the anchor.
305 */
306 public static String getAnchorName(Doc d) {
307 return "line." + d.position().line();
308 }
309 }