Mon, 15 Oct 2012 17:07:55 -0700
8000666: javadoc should write directly to Writer instead of composing strings
Reviewed-by: bpatel
1 /*
2 * Copyright (c) 2003, 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.IOException;
30 import com.sun.javadoc.*;
31 import com.sun.tools.doclets.formats.html.markup.*;
32 import com.sun.tools.doclets.internal.toolkit.*;
33 import com.sun.tools.doclets.internal.toolkit.builders.*;
34 import com.sun.tools.doclets.internal.toolkit.util.*;
36 /**
37 * Generate the Class Information Page.
38 *
39 * <p><b>This is NOT part of any supported API.
40 * If you write code that depends on this, you do so at your own risk.
41 * This code and its internal interfaces are subject to change or
42 * deletion without notice.</b>
43 *
44 * @see com.sun.javadoc.ClassDoc
45 * @see java.util.Collections
46 * @see java.util.List
47 * @see java.util.ArrayList
48 * @see java.util.HashMap
49 *
50 * @author Atul M Dambalkar
51 * @author Robert Field
52 * @author Bhavesh Patel (Modified)
53 */
54 public class AnnotationTypeWriterImpl extends SubWriterHolderWriter
55 implements AnnotationTypeWriter {
57 protected AnnotationTypeDoc annotationType;
59 protected Type prev;
61 protected Type next;
63 /**
64 * @param annotationType the annotation type being documented.
65 * @param prevType the previous class that was documented.
66 * @param nextType the next class being documented.
67 */
68 public AnnotationTypeWriterImpl (AnnotationTypeDoc annotationType,
69 Type prevType, Type nextType)
70 throws Exception {
71 super(ConfigurationImpl.getInstance(),
72 DirectoryManager.getDirectoryPath(annotationType.containingPackage()),
73 annotationType.name() + ".html",
74 DirectoryManager.getRelativePath(annotationType.containingPackage().name()));
75 this.annotationType = annotationType;
76 configuration.currentcd = annotationType.asClassDoc();
77 this.prev = prevType;
78 this.next = nextType;
79 }
81 /**
82 * Get this package link.
83 *
84 * @return a content tree for the package link
85 */
86 protected Content getNavLinkPackage() {
87 Content linkContent = getHyperLink("package-summary.html", "",
88 packageLabel);
89 Content li = HtmlTree.LI(linkContent);
90 return li;
91 }
93 /**
94 * Get the class link.
95 *
96 * @return a content tree for the class link
97 */
98 protected Content getNavLinkClass() {
99 Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, classLabel);
100 return li;
101 }
103 /**
104 * Get the class use link.
105 *
106 * @return a content tree for the class use link
107 */
108 protected Content getNavLinkClassUse() {
109 Content linkContent = getHyperLink("class-use/" + filename, "", useLabel);
110 Content li = HtmlTree.LI(linkContent);
111 return li;
112 }
114 /**
115 * Get link to previous class.
116 *
117 * @return a content tree for the previous class link
118 */
119 public Content getNavLinkPrevious() {
120 Content li;
121 if (prev != null) {
122 Content prevLink = new RawHtml(getLink(new LinkInfoImpl(
123 LinkInfoImpl.CONTEXT_CLASS, prev.asClassDoc(), "",
124 configuration.getText("doclet.Prev_Class"), true)));
125 li = HtmlTree.LI(prevLink);
126 }
127 else
128 li = HtmlTree.LI(prevclassLabel);
129 return li;
130 }
132 /**
133 * Get link to next class.
134 *
135 * @return a content tree for the next class link
136 */
137 public Content getNavLinkNext() {
138 Content li;
139 if (next != null) {
140 Content nextLink = new RawHtml(getLink(new LinkInfoImpl(
141 LinkInfoImpl.CONTEXT_CLASS, next.asClassDoc(), "",
142 configuration.getText("doclet.Next_Class"), true)));
143 li = HtmlTree.LI(nextLink);
144 }
145 else
146 li = HtmlTree.LI(nextclassLabel);
147 return li;
148 }
150 /**
151 * {@inheritDoc}
152 */
153 public Content getHeader(String header) {
154 String pkgname = (annotationType.containingPackage() != null)?
155 annotationType.containingPackage().name(): "";
156 String clname = annotationType.name();
157 Content bodyTree = getBody(true, getWindowTitle(clname));
158 addTop(bodyTree);
159 addNavLinks(true, bodyTree);
160 bodyTree.addContent(HtmlConstants.START_OF_CLASS_DATA);
161 HtmlTree div = new HtmlTree(HtmlTag.DIV);
162 div.addStyle(HtmlStyle.header);
163 if (pkgname.length() > 0) {
164 Content pkgNameContent = new StringContent(pkgname);
165 Content pkgNameDiv = HtmlTree.DIV(HtmlStyle.subTitle, pkgNameContent);
166 div.addContent(pkgNameDiv);
167 }
168 LinkInfoImpl linkInfo = new LinkInfoImpl(
169 LinkInfoImpl.CONTEXT_CLASS_HEADER, annotationType, false);
170 Content headerContent = new StringContent(header);
171 Content heading = HtmlTree.HEADING(HtmlConstants.CLASS_PAGE_HEADING, true,
172 HtmlStyle.title, headerContent);
173 heading.addContent(new RawHtml(getTypeParameterLinks(linkInfo)));
174 div.addContent(heading);
175 bodyTree.addContent(div);
176 return bodyTree;
177 }
179 /**
180 * {@inheritDoc}
181 */
182 public Content getAnnotationContentHeader() {
183 return getContentHeader();
184 }
186 /**
187 * {@inheritDoc}
188 */
189 public void addFooter(Content contentTree) {
190 contentTree.addContent(HtmlConstants.END_OF_CLASS_DATA);
191 addNavLinks(false, contentTree);
192 addBottom(contentTree);
193 }
195 /**
196 * {@inheritDoc}
197 */
198 public void printDocument(Content contentTree) throws IOException {
199 printHtmlDocument(configuration.metakeywords.getMetaKeywords(annotationType),
200 true, contentTree);
201 }
203 /**
204 * {@inheritDoc}
205 */
206 public Content getAnnotationInfoTreeHeader() {
207 return getMemberTreeHeader();
208 }
210 /**
211 * {@inheritDoc}
212 */
213 public Content getAnnotationInfo(Content annotationInfoTree) {
214 return getMemberTree(HtmlStyle.description, annotationInfoTree);
215 }
217 /**
218 * {@inheritDoc}
219 */
220 public void addAnnotationTypeSignature(String modifiers, Content annotationInfoTree) {
221 annotationInfoTree.addContent(new HtmlTree(HtmlTag.BR));
222 Content pre = new HtmlTree(HtmlTag.PRE);
223 addAnnotationInfo(annotationType, pre);
224 pre.addContent(modifiers);
225 LinkInfoImpl linkInfo = new LinkInfoImpl(
226 LinkInfoImpl.CONTEXT_CLASS_SIGNATURE, annotationType, false);
227 Content annotationName = new StringContent(annotationType.name());
228 Content parameterLinks = new RawHtml(getTypeParameterLinks(linkInfo));
229 if (configuration().linksource) {
230 addSrcLink(annotationType, annotationName, pre);
231 pre.addContent(parameterLinks);
232 } else {
233 Content span = HtmlTree.SPAN(HtmlStyle.strong, annotationName);
234 span.addContent(parameterLinks);
235 pre.addContent(span);
236 }
237 annotationInfoTree.addContent(pre);
238 }
240 /**
241 * {@inheritDoc}
242 */
243 public void addAnnotationTypeDescription(Content annotationInfoTree) {
244 if(!configuration.nocomment) {
245 if (annotationType.inlineTags().length > 0) {
246 addInlineComment(annotationType, annotationInfoTree);
247 }
248 }
249 }
251 /**
252 * {@inheritDoc}
253 */
254 public void addAnnotationTypeTagInfo(Content annotationInfoTree) {
255 if(!configuration.nocomment) {
256 addTagsInfo(annotationType, annotationInfoTree);
257 }
258 }
260 /**
261 * {@inheritDoc}
262 */
263 public void addAnnotationTypeDeprecationInfo(Content annotationInfoTree) {
264 Content hr = new HtmlTree(HtmlTag.HR);
265 annotationInfoTree.addContent(hr);
266 Tag[] deprs = annotationType.tags("deprecated");
267 if (Util.isDeprecated(annotationType)) {
268 Content strong = HtmlTree.STRONG(deprecatedPhrase);
269 Content div = HtmlTree.DIV(HtmlStyle.block, strong);
270 if (deprs.length > 0) {
271 Tag[] commentTags = deprs[0].inlineTags();
272 if (commentTags.length > 0) {
273 div.addContent(getSpace());
274 addInlineDeprecatedComment(annotationType, deprs[0], div);
275 }
276 }
277 annotationInfoTree.addContent(div);
278 }
279 }
281 /**
282 * {@inheritDoc}
283 */
284 public void addAnnotationDetailsMarker(Content memberDetails) {
285 memberDetails.addContent(HtmlConstants.START_OF_ANNOTATION_TYPE_DETAILS);
286 }
288 /**
289 * {@inheritDoc}
290 */
291 protected Content getNavLinkTree() {
292 Content treeLinkContent = getHyperLink("package-tree.html",
293 "", treeLabel, "", "");
294 Content li = HtmlTree.LI(treeLinkContent);
295 return li;
296 }
298 /**
299 * Add summary details to the navigation bar.
300 *
301 * @param subDiv the content tree to which the summary detail links will be added
302 */
303 protected void addSummaryDetailLinks(Content subDiv) {
304 try {
305 Content div = HtmlTree.DIV(getNavSummaryLinks());
306 div.addContent(getNavDetailLinks());
307 subDiv.addContent(div);
308 } catch (Exception e) {
309 e.printStackTrace();
310 throw new DocletAbortException();
311 }
312 }
314 /**
315 * Get summary links for navigation bar.
316 *
317 * @return the content tree for the navigation summary links
318 */
319 protected Content getNavSummaryLinks() throws Exception {
320 Content li = HtmlTree.LI(summaryLabel);
321 li.addContent(getSpace());
322 Content ulNav = HtmlTree.UL(HtmlStyle.subNavList, li);
323 MemberSummaryBuilder memberSummaryBuilder = (MemberSummaryBuilder)
324 configuration.getBuilderFactory().getMemberSummaryBuilder(this);
325 Content liNavReq = new HtmlTree(HtmlTag.LI);
326 addNavSummaryLink(memberSummaryBuilder,
327 "doclet.navAnnotationTypeRequiredMember",
328 VisibleMemberMap.ANNOTATION_TYPE_MEMBER_REQUIRED, liNavReq);
329 addNavGap(liNavReq);
330 ulNav.addContent(liNavReq);
331 Content liNavOpt = new HtmlTree(HtmlTag.LI);
332 addNavSummaryLink(memberSummaryBuilder,
333 "doclet.navAnnotationTypeOptionalMember",
334 VisibleMemberMap.ANNOTATION_TYPE_MEMBER_OPTIONAL, liNavOpt);
335 ulNav.addContent(liNavOpt);
336 return ulNav;
337 }
339 /**
340 * Add the navigation summary link.
341 *
342 * @param builder builder for the member to be documented
343 * @param label the label for the navigation
344 * @param type type to be documented
345 * @param liNav the content tree to which the navigation summary link will be added
346 */
347 protected void addNavSummaryLink(MemberSummaryBuilder builder,
348 String label, int type, Content liNav) {
349 AbstractMemberWriter writer = ((AbstractMemberWriter) builder.
350 getMemberSummaryWriter(type));
351 if (writer == null) {
352 liNav.addContent(getResource(label));
353 } else {
354 liNav.addContent(writer.getNavSummaryLink(null,
355 ! builder.getVisibleMemberMap(type).noVisibleMembers()));
356 }
357 }
359 /**
360 * Get detail links for the navigation bar.
361 *
362 * @return the content tree for the detail links
363 */
364 protected Content getNavDetailLinks() throws Exception {
365 Content li = HtmlTree.LI(detailLabel);
366 li.addContent(getSpace());
367 Content ulNav = HtmlTree.UL(HtmlStyle.subNavList, li);
368 MemberSummaryBuilder memberSummaryBuilder = (MemberSummaryBuilder)
369 configuration.getBuilderFactory().getMemberSummaryBuilder(this);
370 AbstractMemberWriter writerOptional =
371 ((AbstractMemberWriter) memberSummaryBuilder.
372 getMemberSummaryWriter(VisibleMemberMap.ANNOTATION_TYPE_MEMBER_OPTIONAL));
373 AbstractMemberWriter writerRequired =
374 ((AbstractMemberWriter) memberSummaryBuilder.
375 getMemberSummaryWriter(VisibleMemberMap.ANNOTATION_TYPE_MEMBER_REQUIRED));
376 if (writerOptional != null){
377 Content liNavOpt = new HtmlTree(HtmlTag.LI);
378 writerOptional.addNavDetailLink(annotationType.elements().length > 0, liNavOpt);
379 ulNav.addContent(liNavOpt);
380 } else if (writerRequired != null){
381 Content liNavReq = new HtmlTree(HtmlTag.LI);
382 writerRequired.addNavDetailLink(annotationType.elements().length > 0, liNavReq);
383 ulNav.addContent(liNavReq);
384 } else {
385 Content liNav = HtmlTree.LI(getResource("doclet.navAnnotationTypeMember"));
386 ulNav.addContent(liNav);
387 }
388 return ulNav;
389 }
391 /**
392 * Add gap between navigation bar elements.
393 *
394 * @param liNav the content tree to which the gap will be added
395 */
396 protected void addNavGap(Content liNav) {
397 liNav.addContent(getSpace());
398 liNav.addContent("|");
399 liNav.addContent(getSpace());
400 }
402 /**
403 * {@inheritDoc}
404 */
405 public AnnotationTypeDoc getAnnotationTypeDoc() {
406 return annotationType;
407 }
408 }