Thu, 13 Jan 2011 21:28:38 -0800
7010528: javadoc performance regression
Reviewed-by: jjg
1 /*
2 * Copyright (c) 1998, 2010, 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 java.util.*;
30 import com.sun.javadoc.*;
31 import com.sun.tools.doclets.formats.html.markup.*;
32 import com.sun.tools.doclets.internal.toolkit.*;
34 /**
35 * Abstract class to generate the overview files in
36 * Frame and Non-Frame format. This will be sub-classed by to
37 * generate overview-frame.html as well as overview-summary.html.
38 *
39 * @author Atul M Dambalkar
40 * @author Bhavesh Patel (Modified)
41 */
42 public abstract class AbstractPackageIndexWriter extends HtmlDocletWriter {
44 /**
45 * Array of Packages to be documented.
46 */
47 protected PackageDoc[] packages;
49 /**
50 * Constructor. Also initialises the packages variable.
51 *
52 * @param filename Name of the package index file to be generated.
53 */
54 public AbstractPackageIndexWriter(ConfigurationImpl configuration,
55 String filename) throws IOException {
56 super(configuration, filename);
57 this.relativepathNoSlash = ".";
58 packages = configuration.packages;
59 }
61 /**
62 * Adds the navigation bar header to the documentation tree.
63 *
64 * @param body the document tree to which the navigation bar header will be added
65 */
66 protected abstract void addNavigationBarHeader(Content body);
68 /**
69 * Adds the navigation bar footer to the documentation tree.
70 *
71 * @param body the document tree to which the navigation bar footer will be added
72 */
73 protected abstract void addNavigationBarFooter(Content body);
75 /**
76 * Adds the overview header to the documentation tree.
77 *
78 * @param body the document tree to which the overview header will be added
79 */
80 protected abstract void addOverviewHeader(Content body);
82 /**
83 * Adds the packages list to the documentation tree.
84 *
85 * @param packages an array of packagedoc objects
86 * @param text caption for the table
87 * @param tableSummary summary for the table
88 * @param body the document tree to which the packages list will be added
89 */
90 protected abstract void addPackagesList(PackageDoc[] packages, String text,
91 String tableSummary, Content body);
93 /**
94 * Generate and prints the contents in the package index file. Call appropriate
95 * methods from the sub-class in order to generate Frame or Non
96 * Frame format.
97 *
98 * @param title the title of the window.
99 * @param includeScript boolean set true if windowtitle script is to be included
100 */
101 protected void buildPackageIndexFile(String title, boolean includeScript) throws IOException {
102 String windowOverview = configuration.getText(title);
103 Content body = getBody(includeScript, getWindowTitle(windowOverview));
104 addNavigationBarHeader(body);
105 addOverviewHeader(body);
106 addIndex(body);
107 addOverview(body);
108 addNavigationBarFooter(body);
109 printHtmlDocument(configuration.metakeywords.getOverviewMetaKeywords(title,
110 configuration.doctitle), includeScript, body);
111 }
113 /**
114 * Default to no overview, override to add overview.
115 *
116 * @param body the document tree to which the overview will be added
117 */
118 protected void addOverview(Content body) throws IOException {
119 }
121 /**
122 * Adds the frame or non-frame package index to the documentation tree.
123 *
124 * @param body the document tree to which the index will be added
125 */
126 protected void addIndex(Content body) {
127 addIndexContents(packages, "doclet.Package_Summary",
128 configuration.getText("doclet.Member_Table_Summary",
129 configuration.getText("doclet.Package_Summary"),
130 configuration.getText("doclet.packages")), body);
131 }
133 /**
134 * Adds package index contents. Call appropriate methods from
135 * the sub-classes. Adds it to the body HtmlTree
136 *
137 * @param packages array of packages to be documented
138 * @param text string which will be used as the heading
139 * @param tableSummary summary for the table
140 * @param body the document tree to which the index contents will be added
141 */
142 protected void addIndexContents(PackageDoc[] packages, String text,
143 String tableSummary, Content body) {
144 if (packages.length > 0) {
145 Arrays.sort(packages);
146 addAllClassesLink(body);
147 addPackagesList(packages, text, tableSummary, body);
148 }
149 }
151 /**
152 * Adds the doctitle to the documentation tree, if it is specified on the command line.
153 *
154 * @param body the document tree to which the title will be added
155 */
156 protected void addConfigurationTitle(Content body) {
157 if (configuration.doctitle.length() > 0) {
158 Content title = new RawHtml(configuration.doctitle);
159 Content heading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING,
160 HtmlStyle.title, title);
161 Content div = HtmlTree.DIV(HtmlStyle.header, heading);
162 body.addContent(div);
163 }
164 }
166 /**
167 * Returns highlighted "Overview", in the navigation bar as this is the
168 * overview page.
169 *
170 * @return a Content object to be added to the documentation tree
171 */
172 protected Content getNavLinkContents() {
173 Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, overviewLabel);
174 return li;
175 }
177 /**
178 * Do nothing. This will be overridden in PackageIndexFrameWriter.
179 *
180 * @param body the document tree to which the all classes link will be added
181 */
182 protected void addAllClassesLink(Content body) {
183 }
184 }