Tue, 03 Dec 2013 14:21:45 -0800
8025416: doclet not substituting {@docRoot} in some cases
Reviewed-by: jjg
1 /*
2 * Copyright (c) 2001, 2013, 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 String NEW_LINE = DocletConstants.NL;
63 private final ConfigurationImpl configuration;
65 private final RootDoc rootDoc;
67 private DocPath outputdir;
69 /**
70 * Relative path from the documentation root to the file that is being
71 * generated.
72 */
73 private DocPath relativePath = DocPath.empty;
75 private SourceToHTMLConverter(ConfigurationImpl configuration, RootDoc rd,
76 DocPath outputdir) {
77 this.configuration = configuration;
78 this.rootDoc = rd;
79 this.outputdir = outputdir;
80 }
82 /**
83 * Convert the Classes in the given RootDoc to an HTML.
84 *
85 * @param configuration the configuration.
86 * @param rd the RootDoc to convert.
87 * @param outputdir the name of the directory to output to.
88 */
89 public static void convertRoot(ConfigurationImpl configuration, RootDoc rd,
90 DocPath outputdir) {
91 new SourceToHTMLConverter(configuration, rd, outputdir).generate();
92 }
94 void generate() {
95 if (rootDoc == null || outputdir == null) {
96 return;
97 }
98 PackageDoc[] pds = rootDoc.specifiedPackages();
99 for (int i = 0; i < pds.length; i++) {
100 // If -nodeprecated option is set and the package is marked as deprecated,
101 // do not convert the package files to HTML.
102 if (!(configuration.nodeprecated && Util.isDeprecated(pds[i])))
103 convertPackage(pds[i], outputdir);
104 }
105 ClassDoc[] cds = rootDoc.specifiedClasses();
106 for (int i = 0; i < cds.length; i++) {
107 // If -nodeprecated option is set and the class is marked as deprecated
108 // or the containing package is deprecated, do not convert the
109 // package files to HTML.
110 if (!(configuration.nodeprecated &&
111 (Util.isDeprecated(cds[i]) || Util.isDeprecated(cds[i].containingPackage()))))
112 convertClass(cds[i], outputdir);
113 }
114 }
116 /**
117 * Convert the Classes in the given Package to an HTML.
118 *
119 * @param pd the Package to convert.
120 * @param outputdir the name of the directory to output to.
121 */
122 public void convertPackage(PackageDoc pd, DocPath outputdir) {
123 if (pd == null) {
124 return;
125 }
126 ClassDoc[] cds = pd.allClasses();
127 for (int i = 0; i < cds.length; i++) {
128 // If -nodeprecated option is set and the class is marked as deprecated,
129 // do not convert the package files to HTML. We do not check for
130 // containing package deprecation since it is already check in
131 // the calling method above.
132 if (!(configuration.nodeprecated && Util.isDeprecated(cds[i])))
133 convertClass(cds[i], outputdir);
134 }
135 }
137 /**
138 * Convert the given Class to an HTML.
139 *
140 * @param cd the class to convert.
141 * @param outputdir the name of the directory to output to.
142 */
143 public void convertClass(ClassDoc cd, DocPath outputdir) {
144 if (cd == null) {
145 return;
146 }
147 try {
148 SourcePosition sp = cd.position();
149 if (sp == null)
150 return;
151 Reader r;
152 // temp hack until we can update SourcePosition API.
153 if (sp instanceof com.sun.tools.javadoc.SourcePositionImpl) {
154 FileObject fo = ((com.sun.tools.javadoc.SourcePositionImpl) sp).fileObject();
155 if (fo == null)
156 return;
157 r = fo.openReader(true);
158 } else {
159 File file = sp.file();
160 if (file == null)
161 return;
162 r = new FileReader(file);
163 }
164 LineNumberReader reader = new LineNumberReader(r);
165 int lineno = 1;
166 String line;
167 relativePath = DocPaths.SOURCE_OUTPUT
168 .resolve(DocPath.forPackage(cd))
169 .invert();
170 Content body = getHeader();
171 Content pre = new HtmlTree(HtmlTag.PRE);
172 try {
173 while ((line = reader.readLine()) != null) {
174 addLineNo(pre, lineno);
175 addLine(pre, line, lineno);
176 lineno++;
177 }
178 } finally {
179 reader.close();
180 }
181 addBlankLines(pre);
182 Content div = HtmlTree.DIV(HtmlStyle.sourceContainer, pre);
183 body.addContent(div);
184 writeToFile(body, outputdir.resolve(DocPath.forClass(cd)));
185 } catch (IOException e) {
186 e.printStackTrace();
187 }
188 }
190 /**
191 * Write the output to the file.
192 *
193 * @param body the documentation content to be written to the file.
194 * @param path the path for the file.
195 */
196 private void writeToFile(Content body, DocPath path) throws IOException {
197 Content htmlDocType = DocType.TRANSITIONAL;
198 Content head = new HtmlTree(HtmlTag.HEAD);
199 head.addContent(HtmlTree.TITLE(new StringContent(
200 configuration.getText("doclet.Window_Source_title"))));
201 head.addContent(getStyleSheetProperties());
202 Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(),
203 head, body);
204 Content htmlDocument = new HtmlDocument(htmlDocType, htmlTree);
205 configuration.message.notice("doclet.Generating_0", path.getPath());
206 DocFile df = DocFile.createFileForOutput(configuration, path);
207 Writer w = df.openWriter();
208 try {
209 htmlDocument.write(w, true);
210 } finally {
211 w.close();
212 }
214 }
216 /**
217 * Returns a link to the stylesheet file.
218 *
219 * @return an HtmlTree for the lINK tag which provides the stylesheet location
220 */
221 public HtmlTree getStyleSheetProperties() {
222 String filename = configuration.stylesheetfile;
223 DocPath stylesheet;
224 if (filename.length() > 0) {
225 DocFile file = DocFile.createFileForInput(configuration, filename);
226 stylesheet = DocPath.create(file.getName());
227 } else {
228 stylesheet = DocPaths.STYLESHEET;
229 }
230 DocPath p = relativePath.resolve(stylesheet);
231 HtmlTree link = HtmlTree.LINK("stylesheet", "text/css", p.getPath(), "Style");
232 return link;
233 }
235 /**
236 * Get the header.
237 *
238 * @return the header content for the HTML file
239 */
240 private static Content getHeader() {
241 return new HtmlTree(HtmlTag.BODY);
242 }
244 /**
245 * Add the line numbers for the source code.
246 *
247 * @param pre the content tree to which the line number will be added
248 * @param lineno The line number
249 */
250 private static void addLineNo(Content pre, int lineno) {
251 HtmlTree span = new HtmlTree(HtmlTag.SPAN);
252 span.addStyle(HtmlStyle.sourceLineNo);
253 if (lineno < 10) {
254 span.addContent("00" + Integer.toString(lineno));
255 } else if (lineno < 100) {
256 span.addContent("0" + Integer.toString(lineno));
257 } else {
258 span.addContent(Integer.toString(lineno));
259 }
260 pre.addContent(span);
261 }
263 /**
264 * Add a line from source to the HTML file that is generated.
265 *
266 * @param pre the content tree to which the line will be added.
267 * @param line the string to format.
268 * @param currentLineNo the current number.
269 */
270 private void addLine(Content pre, String line, int currentLineNo) {
271 if (line != null) {
272 pre.addContent(Util.replaceTabs(configuration, line));
273 Content anchor = HtmlTree.A_NAME("line." + Integer.toString(currentLineNo));
274 pre.addContent(anchor);
275 pre.addContent(NEW_LINE);
276 }
277 }
279 /**
280 * Add trailing blank lines at the end of the page.
281 *
282 * @param pre the content tree to which the blank lines will be added.
283 */
284 private static void addBlankLines(Content pre) {
285 for (int i = 0; i < NUM_BLANK_LINES; i++) {
286 pre.addContent(NEW_LINE);
287 }
288 }
290 /**
291 * Given a <code>Doc</code>, return an anchor name for it.
292 *
293 * @param d the <code>Doc</code> to check.
294 * @return the name of the anchor.
295 */
296 public static String getAnchorName(Doc d) {
297 return "line." + d.position().line();
298 }
299 }