Tue, 14 May 2013 10:14:54 -0700
8012175: Convert TagletOutputImpl to use ContentBuilder instead of StringBuilder
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;
28 import java.io.*;
29 import java.util.*;
31 import com.sun.javadoc.*;
32 import com.sun.tools.doclets.formats.html.markup.*;
33 import com.sun.tools.doclets.internal.toolkit.*;
34 import com.sun.tools.doclets.internal.toolkit.util.*;
36 /**
37 * This abstract class exists to provide functionality needed in the
38 * the formatting of member information. Since AbstractSubWriter and its
39 * subclasses control this, they would be the logical place to put this.
40 * However, because each member type has its own subclass, subclassing
41 * can not be used effectively to change formatting. The concrete
42 * class subclass of this class can be subclassed to change formatting.
43 *
44 * <p><b>This is NOT part of any supported API.
45 * If you write code that depends on this, you do so at your own risk.
46 * This code and its internal interfaces are subject to change or
47 * deletion without notice.</b>
48 *
49 * @see AbstractMemberWriter
50 * @see ClassWriterImpl
51 *
52 * @author Robert Field
53 * @author Atul M Dambalkar
54 * @author Bhavesh Patel (Modified)
55 */
56 public abstract class SubWriterHolderWriter extends HtmlDocletWriter {
58 public SubWriterHolderWriter(ConfigurationImpl configuration, DocPath filename)
59 throws IOException {
60 super(configuration, filename);
61 }
63 /**
64 * Add the summary header.
65 *
66 * @param mw the writer for the member being documented
67 * @param cd the classdoc to be documented
68 * @param memberTree the content tree to which the summary header will be added
69 */
70 public void addSummaryHeader(AbstractMemberWriter mw, ClassDoc cd,
71 Content memberTree) {
72 mw.addSummaryAnchor(cd, memberTree);
73 mw.addSummaryLabel(memberTree);
74 }
76 /**
77 * Get the summary table.
78 *
79 * @param mw the writer for the member being documented
80 * @param cd the classdoc to be documented
81 * @param tableContents list of summary table contents
82 * @param showTabs true if the table needs to show tabs
83 * @return the content tree for the summary table
84 */
85 public Content getSummaryTableTree(AbstractMemberWriter mw, ClassDoc cd,
86 List<Content> tableContents, boolean showTabs) {
87 Content caption;
88 if (showTabs) {
89 caption = getTableCaption(mw.methodTypes);
90 generateMethodTypesScript(mw.typeMap, mw.methodTypes);
91 }
92 else {
93 caption = getTableCaption(mw.getCaption());
94 }
95 Content table = HtmlTree.TABLE(HtmlStyle.overviewSummary, 0, 3, 0,
96 mw.getTableSummary(), caption);
97 table.addContent(getSummaryTableHeader(mw.getSummaryTableHeader(cd), "col"));
98 for (int i = 0; i < tableContents.size(); i++) {
99 table.addContent(tableContents.get(i));
100 }
101 return table;
102 }
104 /**
105 * Get the summary table caption.
106 *
107 * @param methodTypes set comprising of method types to show as table caption
108 * @return the caption for the summary table
109 */
110 public Content getTableCaption(Set<MethodTypes> methodTypes) {
111 Content tabbedCaption = new HtmlTree(HtmlTag.CAPTION);
112 for (MethodTypes type : methodTypes) {
113 Content captionSpan;
114 Content span;
115 if (type.isDefaultTab()) {
116 captionSpan = HtmlTree.SPAN(new StringContent(type.text()));
117 span = HtmlTree.SPAN(type.tabId(),
118 HtmlStyle.activeTableTab, captionSpan);
119 } else {
120 captionSpan = HtmlTree.SPAN(getMethodTypeLinks(type));
121 span = HtmlTree.SPAN(type.tabId(),
122 HtmlStyle.tableTab, captionSpan);
123 }
124 Content tabSpan = HtmlTree.SPAN(HtmlStyle.tabEnd, getSpace());
125 span.addContent(tabSpan);
126 tabbedCaption.addContent(span);
127 }
128 return tabbedCaption;
129 }
131 /**
132 * Get the method type links for the table caption.
133 *
134 * @param methodType the method type to be displayed as link
135 * @return the content tree for the method type link
136 */
137 public Content getMethodTypeLinks(MethodTypes methodType) {
138 StringBuilder jsShow = new StringBuilder("javascript:show(");
139 jsShow.append(methodType.value()).append(");");
140 HtmlTree link = HtmlTree.A(jsShow.toString(),
141 new StringContent(methodType.text()));
142 return link;
143 }
145 /**
146 * Add the inherited summary header.
147 *
148 * @param mw the writer for the member being documented
149 * @param cd the classdoc to be documented
150 * @param inheritedTree the content tree to which the inherited summary header will be added
151 */
152 public void addInheritedSummaryHeader(AbstractMemberWriter mw, ClassDoc cd,
153 Content inheritedTree) {
154 mw.addInheritedSummaryAnchor(cd, inheritedTree);
155 mw.addInheritedSummaryLabel(cd, inheritedTree);
156 }
158 /**
159 * Add the index comment.
160 *
161 * @param member the member being documented
162 * @param contentTree the content tree to which the comment will be added
163 */
164 protected void addIndexComment(Doc member, Content contentTree) {
165 addIndexComment(member, member.firstSentenceTags(), contentTree);
166 }
168 /**
169 * Add the index comment.
170 *
171 * @param member the member being documented
172 * @param firstSentenceTags the first sentence tags for the member to be documented
173 * @param tdSummary the content tree to which the comment will be added
174 */
175 protected void addIndexComment(Doc member, Tag[] firstSentenceTags,
176 Content tdSummary) {
177 Tag[] deprs = member.tags("deprecated");
178 Content div;
179 if (Util.isDeprecated((ProgramElementDoc) member)) {
180 Content strong = HtmlTree.STRONG(deprecatedPhrase);
181 div = HtmlTree.DIV(HtmlStyle.block, strong);
182 div.addContent(getSpace());
183 if (deprs.length > 0) {
184 addInlineDeprecatedComment(member, deprs[0], div);
185 }
186 tdSummary.addContent(div);
187 return;
188 } else {
189 ClassDoc cd = ((ProgramElementDoc)member).containingClass();
190 if (cd != null && Util.isDeprecated(cd)) {
191 Content strong = HtmlTree.STRONG(deprecatedPhrase);
192 div = HtmlTree.DIV(HtmlStyle.block, strong);
193 div.addContent(getSpace());
194 tdSummary.addContent(div);
195 }
196 }
197 addSummaryComment(member, firstSentenceTags, tdSummary);
198 }
200 /**
201 * Add the summary type for the member.
202 *
203 * @param mw the writer for the member being documented
204 * @param member the member to be documented
205 * @param tdSummaryType the content tree to which the type will be added
206 */
207 public void addSummaryType(AbstractMemberWriter mw, ProgramElementDoc member,
208 Content tdSummaryType) {
209 mw.addSummaryType(member, tdSummaryType);
210 }
212 /**
213 * Add the summary link for the member.
214 *
215 * @param mw the writer for the member being documented
216 * @param member the member to be documented
217 * @param contentTree the content tree to which the link will be added
218 */
219 public void addSummaryLinkComment(AbstractMemberWriter mw,
220 ProgramElementDoc member, Content contentTree) {
221 addSummaryLinkComment(mw, member, member.firstSentenceTags(), contentTree);
222 }
224 /**
225 * Add the summary link comment.
226 *
227 * @param mw the writer for the member being documented
228 * @param member the member being documented
229 * @param firstSentenceTags the first sentence tags for the member to be documented
230 * @param tdSummary the content tree to which the comment will be added
231 */
232 public void addSummaryLinkComment(AbstractMemberWriter mw,
233 ProgramElementDoc member, Tag[] firstSentenceTags, Content tdSummary) {
234 addIndexComment(member, firstSentenceTags, tdSummary);
235 }
237 /**
238 * Add the inherited member summary.
239 *
240 * @param mw the writer for the member being documented
241 * @param cd the class being documented
242 * @param member the member being documented
243 * @param isFirst true if its the first link being documented
244 * @param linksTree the content tree to which the summary will be added
245 */
246 public void addInheritedMemberSummary(AbstractMemberWriter mw, ClassDoc cd,
247 ProgramElementDoc member, boolean isFirst, Content linksTree) {
248 if (! isFirst) {
249 linksTree.addContent(", ");
250 }
251 mw.addInheritedSummaryLink(cd, member, linksTree);
252 }
254 /**
255 * Get the document content header tree
256 *
257 * @return a content tree the document content header
258 */
259 public Content getContentHeader() {
260 HtmlTree div = new HtmlTree(HtmlTag.DIV);
261 div.addStyle(HtmlStyle.contentContainer);
262 return div;
263 }
265 /**
266 * Get the member header tree
267 *
268 * @return a content tree the member header
269 */
270 public Content getMemberTreeHeader() {
271 HtmlTree li = new HtmlTree(HtmlTag.LI);
272 li.addStyle(HtmlStyle.blockList);
273 return li;
274 }
276 /**
277 * Get the member tree
278 *
279 * @param contentTree the tree used to generate the complete member tree
280 * @return a content tree for the member
281 */
282 public Content getMemberTree(Content contentTree) {
283 Content ul = HtmlTree.UL(HtmlStyle.blockList, contentTree);
284 return ul;
285 }
287 /**
288 * Get the member summary tree
289 *
290 * @param contentTree the tree used to generate the member summary tree
291 * @return a content tree for the member summary
292 */
293 public Content getMemberSummaryTree(Content contentTree) {
294 return getMemberTree(HtmlStyle.summary, contentTree);
295 }
297 /**
298 * Get the member details tree
299 *
300 * @param contentTree the tree used to generate the member details tree
301 * @return a content tree for the member details
302 */
303 public Content getMemberDetailsTree(Content contentTree) {
304 return getMemberTree(HtmlStyle.details, contentTree);
305 }
307 /**
308 * Get the member tree
309 *
310 * @param style the style class to be added to the content tree
311 * @param contentTree the tree used to generate the complete member tree
312 */
313 public Content getMemberTree(HtmlStyle style, Content contentTree) {
314 Content div = HtmlTree.DIV(style, getMemberTree(contentTree));
315 return div;
316 }
317 }