Wed, 31 Oct 2012 13:48:15 -0700
8001664: refactor javadoc to use abstraction to handle files
Reviewed-by: darcy
1 /*
2 * Copyright (c) 1997, 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.markup;
28 import java.io.*;
30 import com.sun.tools.doclets.internal.toolkit.*;
31 import com.sun.tools.doclets.internal.toolkit.util.*;
33 /**
34 * Class for the Html format code generation.
35 * Initializes PrintWriter with FileWriter, to enable print
36 * related methods to generate the code to the named File through FileWriter.
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 * @since 1.2
44 * @author Atul M Dambalkar
45 * @author Bhavesh Patel (Modified)
46 */
47 public class HtmlWriter {
49 /**
50 * The window title of this file
51 */
52 protected String winTitle;
54 /**
55 * The configuration
56 */
57 protected Configuration configuration;
59 /**
60 * The flag to indicate whether a member details list is printed or not.
61 */
62 protected boolean memberDetailsListPrinted;
64 /**
65 * Header for tables displaying packages and description..
66 */
67 protected final String[] packageTableHeader;
69 /**
70 * Summary for use tables displaying class and package use.
71 */
72 protected final String useTableSummary;
74 /**
75 * Column header for class docs displaying Modifier and Type header.
76 */
77 protected final String modifierTypeHeader;
79 public final Content overviewLabel;
81 public final Content defaultPackageLabel;
83 public final Content packageLabel;
85 public final Content useLabel;
87 public final Content prevLabel;
89 public final Content nextLabel;
91 public final Content prevclassLabel;
93 public final Content nextclassLabel;
95 public final Content summaryLabel;
97 public final Content detailLabel;
99 public final Content framesLabel;
101 public final Content noframesLabel;
103 public final Content treeLabel;
105 public final Content classLabel;
107 public final Content deprecatedLabel;
109 public final Content deprecatedPhrase;
111 public final Content allclassesLabel;
113 public final Content indexLabel;
115 public final Content helpLabel;
117 public final Content seeLabel;
119 public final Content descriptionLabel;
121 public final Content prevpackageLabel;
123 public final Content nextpackageLabel;
125 public final Content packagesLabel;
127 public final Content methodDetailsLabel;
129 public final Content annotationTypeDetailsLabel;
131 public final Content fieldDetailsLabel;
133 public final Content constructorDetailsLabel;
135 public final Content enumConstantsDetailsLabel;
137 public final Content specifiedByLabel;
139 public final Content overridesLabel;
141 public final Content descfrmClassLabel;
143 public final Content descfrmInterfaceLabel;
145 private final Writer writer;
147 /**
148 * Constructor.
149 *
150 * @param path The directory path to be created for this file
151 * or null if none to be created.
152 * @exception IOException Exception raised by the FileWriter is passed on
153 * to next level.
154 * @exception UnsupportedEncodingException Exception raised by the
155 * OutputStreamWriter is passed on to next level.
156 */
157 public HtmlWriter(Configuration configuration, DocPath path)
158 throws IOException, UnsupportedEncodingException {
159 writer = DocFile.createFileForOutput(configuration, path).openWriter();
160 this.configuration = configuration;
161 this.memberDetailsListPrinted = false;
162 packageTableHeader = new String[] {
163 configuration.getText("doclet.Package"),
164 configuration.getText("doclet.Description")
165 };
166 useTableSummary = configuration.getText("doclet.Use_Table_Summary",
167 configuration.getText("doclet.packages"));
168 modifierTypeHeader = configuration.getText("doclet.0_and_1",
169 configuration.getText("doclet.Modifier"),
170 configuration.getText("doclet.Type"));
171 overviewLabel = getResource("doclet.Overview");
172 defaultPackageLabel = new RawHtml(
173 DocletConstants.DEFAULT_PACKAGE_NAME);
174 packageLabel = getResource("doclet.Package");
175 useLabel = getResource("doclet.navClassUse");
176 prevLabel = getResource("doclet.Prev");
177 nextLabel = getResource("doclet.Next");
178 prevclassLabel = getResource("doclet.Prev_Class");
179 nextclassLabel = getResource("doclet.Next_Class");
180 summaryLabel = getResource("doclet.Summary");
181 detailLabel = getResource("doclet.Detail");
182 framesLabel = getResource("doclet.Frames");
183 noframesLabel = getResource("doclet.No_Frames");
184 treeLabel = getResource("doclet.Tree");
185 classLabel = getResource("doclet.Class");
186 deprecatedLabel = getResource("doclet.navDeprecated");
187 deprecatedPhrase = getResource("doclet.Deprecated");
188 allclassesLabel = getResource("doclet.All_Classes");
189 indexLabel = getResource("doclet.Index");
190 helpLabel = getResource("doclet.Help");
191 seeLabel = getResource("doclet.See");
192 descriptionLabel = getResource("doclet.Description");
193 prevpackageLabel = getResource("doclet.Prev_Package");
194 nextpackageLabel = getResource("doclet.Next_Package");
195 packagesLabel = getResource("doclet.Packages");
196 methodDetailsLabel = getResource("doclet.Method_Detail");
197 annotationTypeDetailsLabel = getResource("doclet.Annotation_Type_Member_Detail");
198 fieldDetailsLabel = getResource("doclet.Field_Detail");
199 constructorDetailsLabel = getResource("doclet.Constructor_Detail");
200 enumConstantsDetailsLabel = getResource("doclet.Enum_Constant_Detail");
201 specifiedByLabel = getResource("doclet.Specified_By");
202 overridesLabel = getResource("doclet.Overrides");
203 descfrmClassLabel = getResource("doclet.Description_From_Class");
204 descfrmInterfaceLabel = getResource("doclet.Description_From_Interface");
205 }
207 public void write(Content c) throws IOException {
208 c.write(writer, true);
209 }
211 public void close() throws IOException {
212 writer.close();
213 }
215 /**
216 * Get the configuration string as a content.
217 *
218 * @param key the key to look for in the configuration file
219 * @return a content tree for the text
220 */
221 public Content getResource(String key) {
222 return new StringContent(configuration.getText(key));
223 }
225 /**
226 * Get the configuration string as a content.
227 *
228 * @param key the key to look for in the configuration file
229 * @param a1 string argument added to configuration text
230 * @return a content tree for the text
231 */
232 public Content getResource(String key, String a1) {
233 return new RawHtml(configuration.getText(key, a1));
234 }
236 /**
237 * Get the configuration string as a content.
238 *
239 * @param key the key to look for in the configuration file
240 * @param a1 string argument added to configuration text
241 * @param a2 string argument added to configuration text
242 * @return a content tree for the text
243 */
244 public Content getResource(String key, String a1, String a2) {
245 return new RawHtml(configuration.getText(key, a1, a2));
246 }
248 /**
249 * Returns an HtmlTree for the SCRIPT tag.
250 *
251 * @return an HtmlTree for the SCRIPT tag
252 */
253 protected HtmlTree getWinTitleScript(){
254 HtmlTree script = new HtmlTree(HtmlTag.SCRIPT);
255 if(winTitle != null && winTitle.length() > 0) {
256 script.addAttr(HtmlAttr.TYPE, "text/javascript");
257 String scriptCode = "<!--" + DocletConstants.NL +
258 " if (location.href.indexOf('is-external=true') == -1) {" + DocletConstants.NL +
259 " parent.document.title=\"" + winTitle + "\";" + DocletConstants.NL +
260 " }" + DocletConstants.NL +
261 "//-->" + DocletConstants.NL;
262 RawHtml scriptContent = new RawHtml(scriptCode);
263 script.addContent(scriptContent);
264 }
265 return script;
266 }
268 /**
269 * Returns a content tree for the SCRIPT tag for the main page(index.html).
270 *
271 * @return a content for the SCRIPT tag
272 */
273 protected Content getFramesetJavaScript(){
274 HtmlTree script = new HtmlTree(HtmlTag.SCRIPT);
275 script.addAttr(HtmlAttr.TYPE, "text/javascript");
276 String scriptCode = DocletConstants.NL + " targetPage = \"\" + window.location.search;" + DocletConstants.NL +
277 " if (targetPage != \"\" && targetPage != \"undefined\")" + DocletConstants.NL +
278 " targetPage = targetPage.substring(1);" + DocletConstants.NL +
279 " if (targetPage.indexOf(\":\") != -1)" + DocletConstants.NL +
280 " targetPage = \"undefined\";" + DocletConstants.NL +
281 " function loadFrames() {" + DocletConstants.NL +
282 " if (targetPage != \"\" && targetPage != \"undefined\")" + DocletConstants.NL +
283 " top.classFrame.location = top.targetPage;" + DocletConstants.NL +
284 " }" + DocletConstants.NL;
285 RawHtml scriptContent = new RawHtml(scriptCode);
286 script.addContent(scriptContent);
287 return script;
288 }
290 /**
291 * Returns an HtmlTree for the BODY tag.
292 *
293 * @param includeScript set true if printing windowtitle script
294 * @param title title for the window
295 * @return an HtmlTree for the BODY tag
296 */
297 public HtmlTree getBody(boolean includeScript, String title) {
298 HtmlTree body = new HtmlTree(HtmlTag.BODY);
299 // Set window title string which is later printed
300 this.winTitle = title;
301 // Don't print windowtitle script for overview-frame, allclasses-frame
302 // and package-frame
303 if (includeScript) {
304 body.addContent(getWinTitleScript());
305 Content noScript = HtmlTree.NOSCRIPT(
306 HtmlTree.DIV(getResource("doclet.No_Script_Message")));
307 body.addContent(noScript);
308 }
309 return body;
310 }
312 /**
313 * Returns an HtmlTree for the TITLE tag.
314 *
315 * @return an HtmlTree for the TITLE tag
316 */
317 public HtmlTree getTitle() {
318 HtmlTree title = HtmlTree.TITLE(new StringContent(winTitle));
319 return title;
320 }
322 /**
323 * Return, text passed, with Italics <i> and </i> tags, surrounding it.
324 * So if the text passed is "Hi", then string returned will be "<i>Hi</i>".
325 *
326 * @param text String to be printed in between <I> and </I> tags.
327 */
328 public String italicsText(String text) {
329 return "<i>" + text + "</i>";
330 }
332 public String codeText(String text) {
333 return "<code>" + text + "</code>";
334 }
336 /**
337 * Return "&nbsp;", non-breaking space.
338 */
339 public Content getSpace() {
340 return RawHtml.nbsp;
341 }
343 /*
344 * Returns a header for Modifier and Type column of a table.
345 */
346 public String getModifierTypeHeader() {
347 return modifierTypeHeader;
348 }
349 }