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) 1998, 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.text.SimpleDateFormat;
30 import java.util.*;
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.taglets.*;
36 import com.sun.tools.doclets.internal.toolkit.util.*;
38 /**
39 * Class for the Html Format Code Generation specific to JavaDoc.
40 * This Class contains methods related to the Html Code Generation which
41 * are used extensively while generating the entire documentation.
42 *
43 * <p><b>This is NOT part of any supported API.
44 * If you write code that depends on this, you do so at your own risk.
45 * This code and its internal interfaces are subject to change or
46 * deletion without notice.</b>
47 *
48 * @since 1.2
49 * @author Atul M Dambalkar
50 * @author Robert Field
51 * @author Bhavesh Patel (Modified)
52 */
53 public class HtmlDocletWriter extends HtmlDocWriter {
55 /**
56 * Relative path from the file getting generated to the destination
57 * directory. For example, if the file getting generated is
58 * "java/lang/Object.html", then the relative path string is "../../".
59 * This string can be empty if the file getting generated is in
60 * the destination directory.
61 */
62 public String relativePath = "";
64 /**
65 * Same as relativepath, but normalized to never be empty or
66 * end with a slash.
67 */
68 public String relativepathNoSlash = "";
70 /**
71 * Platform-dependent directory path from the current or the
72 * destination directory to the file getting generated.
73 * Used when creating the file.
74 * For example, if the file getting generated is
75 * "java/lang/Object.html", then the path string is "java/lang".
76 */
77 public String path = "";
79 /**
80 * Name of the file getting generated. If the file getting generated is
81 * "java/lang/Object.html", then the filename is "Object.html".
82 */
83 public String filename = "";
85 /**
86 * The display length used for indentation while generating the class page.
87 */
88 public int displayLength = 0;
90 /**
91 * The global configuration information for this run.
92 */
93 public ConfigurationImpl configuration;
95 /**
96 * To check whether annotation heading is printed or not.
97 */
98 protected boolean printedAnnotationHeading = false;
100 /**
101 * Constructor to construct the HtmlStandardWriter object.
102 *
103 * @param filename File to be generated.
104 */
105 public HtmlDocletWriter(ConfigurationImpl configuration,
106 String filename) throws IOException {
107 super(configuration, filename);
108 this.configuration = configuration;
109 this.filename = filename;
110 }
112 /**
113 * Constructor to construct the HtmlStandardWriter object.
114 *
115 * @param path Platform-dependent {@link #path} used when
116 * creating file.
117 * @param filename Name of file to be generated.
118 * @param relativePath Value for the variable {@link #relativePath}.
119 */
120 public HtmlDocletWriter(ConfigurationImpl configuration,
121 String path, String filename,
122 String relativePath) throws IOException {
123 super(configuration, path, filename);
124 this.configuration = configuration;
125 this.path = path;
126 this.relativePath = relativePath;
127 this.relativepathNoSlash =
128 DirectoryManager.getPathNoTrailingSlash(this.relativePath);
129 this.filename = filename;
130 }
132 /**
133 * Replace {@docRoot} tag used in options that accept HTML text, such
134 * as -header, -footer, -top and -bottom, and when converting a relative
135 * HREF where commentTagsToString inserts a {@docRoot} where one was
136 * missing. (Also see DocRootTaglet for {@docRoot} tags in doc
137 * comments.)
138 * <p>
139 * Replace {@docRoot} tag in htmlstr with the relative path to the
140 * destination directory from the directory where the file is being
141 * written, looping to handle all such tags in htmlstr.
142 * <p>
143 * For example, for "-d docs" and -header containing {@docRoot}, when
144 * the HTML page for source file p/C1.java is being generated, the
145 * {@docRoot} tag would be inserted into the header as "../",
146 * the relative path from docs/p/ to docs/ (the document root).
147 * <p>
148 * Note: This doc comment was written with '&#064;' representing '@'
149 * to prevent the inline tag from being interpreted.
150 */
151 public String replaceDocRootDir(String htmlstr) {
152 // Return if no inline tags exist
153 int index = htmlstr.indexOf("{@");
154 if (index < 0) {
155 return htmlstr;
156 }
157 String lowerHtml = htmlstr.toLowerCase();
158 // Return index of first occurrence of {@docroot}
159 // Note: {@docRoot} is not case sensitive when passed in w/command line option
160 index = lowerHtml.indexOf("{@docroot}", index);
161 if (index < 0) {
162 return htmlstr;
163 }
164 StringBuilder buf = new StringBuilder();
165 int previndex = 0;
166 while (true) {
167 if (configuration.docrootparent.length() > 0) {
168 // Search for lowercase version of {@docRoot}/..
169 index = lowerHtml.indexOf("{@docroot}/..", previndex);
170 // If next {@docRoot}/.. pattern not found, append rest of htmlstr and exit loop
171 if (index < 0) {
172 buf.append(htmlstr.substring(previndex));
173 break;
174 }
175 // If next {@docroot}/.. pattern found, append htmlstr up to start of tag
176 buf.append(htmlstr.substring(previndex, index));
177 previndex = index + 13; // length for {@docroot}/.. string
178 // Insert docrootparent absolute path where {@docRoot}/.. was located
180 buf.append(configuration.docrootparent);
181 // Append slash if next character is not a slash
182 if (previndex < htmlstr.length() && htmlstr.charAt(previndex) != '/') {
183 buf.append(DirectoryManager.URL_FILE_SEPARATOR);
184 }
185 } else {
186 // Search for lowercase version of {@docRoot}
187 index = lowerHtml.indexOf("{@docroot}", previndex);
188 // If next {@docRoot} tag not found, append rest of htmlstr and exit loop
189 if (index < 0) {
190 buf.append(htmlstr.substring(previndex));
191 break;
192 }
193 // If next {@docroot} tag found, append htmlstr up to start of tag
194 buf.append(htmlstr.substring(previndex, index));
195 previndex = index + 10; // length for {@docroot} string
196 // Insert relative path where {@docRoot} was located
197 buf.append(relativepathNoSlash);
198 // Append slash if next character is not a slash
199 if (relativepathNoSlash.length() > 0 && previndex < htmlstr.length() &&
200 htmlstr.charAt(previndex) != '/') {
201 buf.append(DirectoryManager.URL_FILE_SEPARATOR);
202 }
203 }
204 }
205 return buf.toString();
206 }
208 /**
209 * Print Html Hyper Link, with target frame. This
210 * link will only appear if page is not in a frame.
211 *
212 * @param link String name of the file.
213 * @param where Position in the file
214 * @param target Name of the target frame.
215 * @param label Tag for the link.
216 * @param strong Whether the label should be strong or not?
217 */
218 public void printNoFramesTargetHyperLink(String link, String where,
219 String target, String label,
220 boolean strong) {
221 script();
222 println(" <!--");
223 println(" if(window==top) {");
224 println(" document.writeln('"
225 + getHyperLinkString(link, where, label, strong, "", "", target) + "');");
226 println(" }");
227 println(" //-->");
228 scriptEnd();
229 noScript();
230 println(" " + getHyperLinkString(link, where, label, strong, "", "", target));
231 noScriptEnd();
232 println(DocletConstants.NL);
233 }
235 /**
236 * Get the script to show or hide the All classes link.
237 *
238 * @param id id of the element to show or hide
239 * @return a content tree for the script
240 */
241 public Content getAllClassesLinkScript(String id) {
242 HtmlTree script = new HtmlTree(HtmlTag.SCRIPT);
243 script.addAttr(HtmlAttr.TYPE, "text/javascript");
244 String scriptCode = "<!--" + DocletConstants.NL +
245 " allClassesLink = document.getElementById(\"" + id + "\");" + DocletConstants.NL +
246 " if(window==top) {" + DocletConstants.NL +
247 " allClassesLink.style.display = \"block\";" + DocletConstants.NL +
248 " }" + DocletConstants.NL +
249 " else {" + DocletConstants.NL +
250 " allClassesLink.style.display = \"none\";" + DocletConstants.NL +
251 " }" + DocletConstants.NL +
252 " //-->" + DocletConstants.NL;
253 Content scriptContent = new RawHtml(scriptCode);
254 script.addContent(scriptContent);
255 Content div = HtmlTree.DIV(script);
256 return div;
257 }
259 /**
260 * Add method information.
261 *
262 * @param method the method to be documented
263 * @param dl the content tree to which the method information will be added
264 */
265 private void addMethodInfo(MethodDoc method, Content dl) {
266 ClassDoc[] intfacs = method.containingClass().interfaces();
267 MethodDoc overriddenMethod = method.overriddenMethod();
268 // Check whether there is any implementation or overridden info to be
269 // printed. If no overridden or implementation info needs to be
270 // printed, do not print this section.
271 if ((intfacs.length > 0 &&
272 new ImplementedMethods(method, this.configuration).build().length > 0) ||
273 overriddenMethod != null) {
274 MethodWriterImpl.addImplementsInfo(this, method, dl);
275 if (overriddenMethod != null) {
276 MethodWriterImpl.addOverridden(this,
277 method.overriddenType(), overriddenMethod, dl);
278 }
279 }
280 }
282 /**
283 * Adds the tags information.
284 *
285 * @param doc the doc for which the tags will be generated
286 * @param htmltree the documentation tree to which the tags will be added
287 */
288 protected void addTagsInfo(Doc doc, Content htmltree) {
289 if (configuration.nocomment) {
290 return;
291 }
292 Content dl = new HtmlTree(HtmlTag.DL);
293 if (doc instanceof MethodDoc) {
294 addMethodInfo((MethodDoc) doc, dl);
295 }
296 TagletOutputImpl output = new TagletOutputImpl("");
297 TagletWriter.genTagOuput(configuration.tagletManager, doc,
298 configuration.tagletManager.getCustomTags(doc),
299 getTagletWriterInstance(false), output);
300 String outputString = output.toString().trim();
301 if (!outputString.isEmpty()) {
302 Content resultString = new RawHtml(outputString);
303 dl.addContent(resultString);
304 }
305 htmltree.addContent(dl);
306 }
308 /**
309 * Check whether there are any tags for Serialization Overview
310 * section to be printed.
311 *
312 * @param field the FieldDoc object to check for tags.
313 * @return true if there are tags to be printed else return false.
314 */
315 protected boolean hasSerializationOverviewTags(FieldDoc field) {
316 TagletOutputImpl output = new TagletOutputImpl("");
317 TagletWriter.genTagOuput(configuration.tagletManager, field,
318 configuration.tagletManager.getCustomTags(field),
319 getTagletWriterInstance(false), output);
320 return (!output.toString().trim().isEmpty());
321 }
323 /**
324 * Returns a TagletWriter that knows how to write HTML.
325 *
326 * @return a TagletWriter that knows how to write HTML.
327 */
328 public TagletWriter getTagletWriterInstance(boolean isFirstSentence) {
329 return new TagletWriterImpl(this, isFirstSentence);
330 }
332 protected void printTagsInfoHeader() {
333 dl();
334 }
336 protected void printTagsInfoFooter() {
337 dlEnd();
338 }
340 /**
341 * Get Package link, with target frame.
342 *
343 * @param pd The link will be to the "package-summary.html" page for this package
344 * @param target name of the target frame
345 * @param label tag for the link
346 * @return a content for the target package link
347 */
348 public Content getTargetPackageLink(PackageDoc pd, String target,
349 Content label) {
350 return getHyperLink(pathString(pd, "package-summary.html"), "", label, "", target);
351 }
353 /**
354 * Generates the HTML document tree and prints it out.
355 *
356 * @param metakeywords Array of String keywords for META tag. Each element
357 * of the array is assigned to a separate META tag.
358 * Pass in null for no array
359 * @param includeScript true if printing windowtitle script
360 * false for files that appear in the left-hand frames
361 * @param body the body htmltree to be included in the document
362 */
363 public void printHtmlDocument(String[] metakeywords, boolean includeScript,
364 Content body) throws IOException {
365 Content htmlDocType = DocType.Transitional();
366 Content htmlComment = new Comment(configuration.getText("doclet.New_Page"));
367 Content head = new HtmlTree(HtmlTag.HEAD);
368 if (!configuration.notimestamp) {
369 Content headComment = new Comment(getGeneratedByString());
370 head.addContent(headComment);
371 }
372 if (configuration.charset.length() > 0) {
373 Content meta = HtmlTree.META("Content-Type", "text/html",
374 configuration.charset);
375 head.addContent(meta);
376 }
377 head.addContent(getTitle());
378 if (!configuration.notimestamp) {
379 SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
380 Content meta = HtmlTree.META("date", dateFormat.format(new Date()));
381 head.addContent(meta);
382 }
383 if (metakeywords != null) {
384 for (int i=0; i < metakeywords.length; i++) {
385 Content meta = HtmlTree.META("keywords", metakeywords[i]);
386 head.addContent(meta);
387 }
388 }
389 head.addContent(getStyleSheetProperties());
390 Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(),
391 head, body);
392 Content htmlDocument = new HtmlDocument(htmlDocType,
393 htmlComment, htmlTree);
394 htmlDocument.write(this, true);
395 }
397 /**
398 * Get the window title.
399 *
400 * @param title the title string to construct the complete window title
401 * @return the window title string
402 */
403 public String getWindowTitle(String title) {
404 if (configuration.windowtitle.length() > 0) {
405 title += " (" + configuration.windowtitle + ")";
406 }
407 return title;
408 }
410 /**
411 * Print user specified header and the footer.
412 *
413 * @param header if true print the user provided header else print the
414 * user provided footer.
415 */
416 public void printUserHeaderFooter(boolean header) {
417 em();
418 if (header) {
419 print(replaceDocRootDir(configuration.header));
420 } else {
421 if (configuration.footer.length() != 0) {
422 print(replaceDocRootDir(configuration.footer));
423 } else {
424 print(replaceDocRootDir(configuration.header));
425 }
426 }
427 emEnd();
428 }
430 /**
431 * Get user specified header and the footer.
432 *
433 * @param header if true print the user provided header else print the
434 * user provided footer.
435 */
436 public Content getUserHeaderFooter(boolean header) {
437 String content;
438 if (header) {
439 content = replaceDocRootDir(configuration.header);
440 } else {
441 if (configuration.footer.length() != 0) {
442 content = replaceDocRootDir(configuration.footer);
443 } else {
444 content = replaceDocRootDir(configuration.header);
445 }
446 }
447 Content rawContent = new RawHtml(content);
448 Content em = HtmlTree.EM(rawContent);
449 return em;
450 }
452 /**
453 * Print the user specified top.
454 */
455 public void printTop() {
456 print(replaceDocRootDir(configuration.top));
457 hr();
458 }
460 /**
461 * Adds the user specified top.
462 *
463 * @param body the content tree to which user specified top will be added
464 */
465 public void addTop(Content body) {
466 Content top = new RawHtml(replaceDocRootDir(configuration.top));
467 body.addContent(top);
468 }
470 /**
471 * Print the user specified bottom.
472 */
473 public void printBottom() {
474 hr();
475 print(replaceDocRootDir(configuration.bottom));
476 }
478 /**
479 * Adds the user specified bottom.
480 *
481 * @param body the content tree to which user specified bottom will be added
482 */
483 public void addBottom(Content body) {
484 Content bottom = new RawHtml(replaceDocRootDir(configuration.bottom));
485 Content small = HtmlTree.SMALL(bottom);
486 Content p = HtmlTree.P(HtmlStyle.legalCopy, small);
487 body.addContent(p);
488 }
490 /**
491 * Print the navigation bar for the Html page at the top and and the bottom.
492 *
493 * @param header If true print navigation bar at the top of the page else
494 * print the nevigation bar at the bottom.
495 */
496 protected void navLinks(boolean header) {
497 println("");
498 if (!configuration.nonavbar) {
499 if (header) {
500 println(DocletConstants.NL + "<!-- ========= START OF TOP NAVBAR ======= -->");
501 anchor("navbar_top");
502 println();
503 print(getHyperLinkString("", "skip-navbar_top", "", false, "",
504 configuration.getText("doclet.Skip_navigation_links"), ""));
505 } else {
506 println(DocletConstants.NL + "<!-- ======= START OF BOTTOM NAVBAR ====== -->");
507 anchor("navbar_bottom");
508 println();
509 print(getHyperLinkString("", "skip-navbar_bottom", "", false, "",
510 configuration.getText("doclet.Skip_navigation_links"), ""));
511 }
512 table(0, "100%", 1, 0);
513 tr();
514 tdColspanBgcolorStyle(2, "#EEEEFF", "NavBarCell1");
515 println("");
516 if (header) {
517 anchor("navbar_top_firstrow");
518 } else {
519 anchor("navbar_bottom_firstrow");
520 }
521 table(0, 0, 3);
522 print(" ");
523 trAlignVAlign("center", "top");
525 if (configuration.createoverview) {
526 navLinkContents();
527 }
529 if (configuration.packages.length == 1) {
530 navLinkPackage(configuration.packages[0]);
531 } else if (configuration.packages.length > 1) {
532 navLinkPackage();
533 }
535 navLinkClass();
537 if(configuration.classuse) {
538 navLinkClassUse();
539 }
540 if(configuration.createtree) {
541 navLinkTree();
542 }
543 if(!(configuration.nodeprecated ||
544 configuration.nodeprecatedlist)) {
545 navLinkDeprecated();
546 }
547 if(configuration.createindex) {
548 navLinkIndex();
549 }
550 if (!configuration.nohelp) {
551 navLinkHelp();
552 }
553 print(" ");
554 trEnd();
555 tableEnd();
556 tdEnd();
558 tdAlignVAlignRowspan("right", "top", 3);
560 printUserHeaderFooter(header);
561 tdEnd();
562 trEnd();
563 println("");
565 tr();
566 tdBgcolorStyle("white", "NavBarCell2");
567 font("-2");
568 space();
569 navLinkPrevious();
570 space();
571 println("");
572 space();
573 navLinkNext();
574 fontEnd();
575 tdEnd();
577 tdBgcolorStyle("white", "NavBarCell2");
578 font("-2");
579 print(" ");
580 navShowLists();
581 print(" ");
582 space();
583 println("");
584 space();
585 navHideLists(filename);
586 print(" ");
587 space();
588 println("");
589 space();
590 navLinkClassIndex();
591 fontEnd();
592 tdEnd();
594 trEnd();
596 printSummaryDetailLinks();
598 tableEnd();
599 if (header) {
600 aName("skip-navbar_top");
601 aEnd();
602 println(DocletConstants.NL + "<!-- ========= END OF TOP NAVBAR ========= -->");
603 } else {
604 aName("skip-navbar_bottom");
605 aEnd();
606 println(DocletConstants.NL + "<!-- ======== END OF BOTTOM NAVBAR ======= -->");
607 }
608 println("");
609 }
610 }
612 /**
613 * Adds the navigation bar for the Html page at the top and and the bottom.
614 *
615 * @param header If true print navigation bar at the top of the page else
616 * @param body the HtmlTree to which the nav links will be added
617 */
618 protected void addNavLinks(boolean header, Content body) {
619 if (!configuration.nonavbar) {
620 String allClassesId = "allclasses_";
621 HtmlTree navDiv = new HtmlTree(HtmlTag.DIV);
622 if (header) {
623 body.addContent(HtmlConstants.START_OF_TOP_NAVBAR);
624 navDiv.addStyle(HtmlStyle.topNav);
625 allClassesId += "navbar_top";
626 Content a = getMarkerAnchor("navbar_top");
627 navDiv.addContent(a);
628 Content skipLinkContent = getHyperLink("",
629 "skip-navbar_top", HtmlTree.EMPTY, configuration.getText(
630 "doclet.Skip_navigation_links"), "");
631 navDiv.addContent(skipLinkContent);
632 } else {
633 body.addContent(HtmlConstants.START_OF_BOTTOM_NAVBAR);
634 navDiv.addStyle(HtmlStyle.bottomNav);
635 allClassesId += "navbar_bottom";
636 Content a = getMarkerAnchor("navbar_bottom");
637 navDiv.addContent(a);
638 Content skipLinkContent = getHyperLink("",
639 "skip-navbar_bottom", HtmlTree.EMPTY, configuration.getText(
640 "doclet.Skip_navigation_links"), "");
641 navDiv.addContent(skipLinkContent);
642 }
643 if (header) {
644 navDiv.addContent(getMarkerAnchor("navbar_top_firstrow"));
645 } else {
646 navDiv.addContent(getMarkerAnchor("navbar_bottom_firstrow"));
647 }
648 HtmlTree navList = new HtmlTree(HtmlTag.UL);
649 navList.addStyle(HtmlStyle.navList);
650 navList.addAttr(HtmlAttr.TITLE, "Navigation");
651 if (configuration.createoverview) {
652 navList.addContent(getNavLinkContents());
653 }
654 if (configuration.packages.length == 1) {
655 navList.addContent(getNavLinkPackage(configuration.packages[0]));
656 } else if (configuration.packages.length > 1) {
657 navList.addContent(getNavLinkPackage());
658 }
659 navList.addContent(getNavLinkClass());
660 if(configuration.classuse) {
661 navList.addContent(getNavLinkClassUse());
662 }
663 if(configuration.createtree) {
664 navList.addContent(getNavLinkTree());
665 }
666 if(!(configuration.nodeprecated ||
667 configuration.nodeprecatedlist)) {
668 navList.addContent(getNavLinkDeprecated());
669 }
670 if(configuration.createindex) {
671 navList.addContent(getNavLinkIndex());
672 }
673 if (!configuration.nohelp) {
674 navList.addContent(getNavLinkHelp());
675 }
676 navDiv.addContent(navList);
677 Content aboutDiv = HtmlTree.DIV(HtmlStyle.aboutLanguage, getUserHeaderFooter(header));
678 navDiv.addContent(aboutDiv);
679 body.addContent(navDiv);
680 Content ulNav = HtmlTree.UL(HtmlStyle.navList, getNavLinkPrevious());
681 ulNav.addContent(getNavLinkNext());
682 Content subDiv = HtmlTree.DIV(HtmlStyle.subNav, ulNav);
683 Content ulFrames = HtmlTree.UL(HtmlStyle.navList, getNavShowLists());
684 ulFrames.addContent(getNavHideLists(filename));
685 subDiv.addContent(ulFrames);
686 HtmlTree ulAllClasses = HtmlTree.UL(HtmlStyle.navList, getNavLinkClassIndex());
687 ulAllClasses.addAttr(HtmlAttr.ID, allClassesId.toString());
688 subDiv.addContent(ulAllClasses);
689 subDiv.addContent(getAllClassesLinkScript(allClassesId.toString()));
690 addSummaryDetailLinks(subDiv);
691 if (header) {
692 subDiv.addContent(getMarkerAnchor("skip-navbar_top"));
693 body.addContent(subDiv);
694 body.addContent(HtmlConstants.END_OF_TOP_NAVBAR);
695 } else {
696 subDiv.addContent(getMarkerAnchor("skip-navbar_bottom"));
697 body.addContent(subDiv);
698 body.addContent(HtmlConstants.END_OF_BOTTOM_NAVBAR);
699 }
700 }
701 }
703 /**
704 * Print the word "NEXT" to indicate that no link is available. Override
705 * this method to customize next link.
706 */
707 protected void navLinkNext() {
708 navLinkNext(null);
709 }
711 /**
712 * Get the word "NEXT" to indicate that no link is available. Override
713 * this method to customize next link.
714 *
715 * @return a content tree for the link
716 */
717 protected Content getNavLinkNext() {
718 return getNavLinkNext(null);
719 }
721 /**
722 * Print the word "PREV" to indicate that no link is available. Override
723 * this method to customize prev link.
724 */
725 protected void navLinkPrevious() {
726 navLinkPrevious(null);
727 }
729 /**
730 * Get the word "PREV" to indicate that no link is available. Override
731 * this method to customize prev link.
732 *
733 * @return a content tree for the link
734 */
735 protected Content getNavLinkPrevious() {
736 return getNavLinkPrevious(null);
737 }
739 /**
740 * Do nothing. This is the default method.
741 */
742 protected void printSummaryDetailLinks() {
743 }
745 /**
746 * Do nothing. This is the default method.
747 */
748 protected void addSummaryDetailLinks(Content navDiv) {
749 }
751 /**
752 * Print link to the "overview-summary.html" page.
753 */
754 protected void navLinkContents() {
755 navCellStart();
756 printHyperLink(relativePath + "overview-summary.html", "",
757 configuration.getText("doclet.Overview"), true, "NavBarFont1");
758 navCellEnd();
759 }
761 /**
762 * Get link to the "overview-summary.html" page.
763 *
764 * @return a content tree for the link
765 */
766 protected Content getNavLinkContents() {
767 Content linkContent = getHyperLink(relativePath +
768 "overview-summary.html", "", overviewLabel, "", "");
769 Content li = HtmlTree.LI(linkContent);
770 return li;
771 }
773 /**
774 * Description for a cell in the navigation bar.
775 */
776 protected void navCellStart() {
777 print(" ");
778 tdBgcolorStyle("#EEEEFF", "NavBarCell1");
779 print(" ");
780 }
782 /**
783 * Description for a cell in the navigation bar, but with reverse
784 * high-light effect.
785 */
786 protected void navCellRevStart() {
787 print(" ");
788 tdBgcolorStyle("#FFFFFF", "NavBarCell1Rev");
789 print(" ");
790 space();
791 }
793 /**
794 * Closing tag for navigation bar cell.
795 */
796 protected void navCellEnd() {
797 space();
798 tdEnd();
799 }
801 /**
802 * Print link to the "package-summary.html" page for the package passed.
803 *
804 * @param pkg Package to which link will be generated.
805 */
806 protected void navLinkPackage(PackageDoc pkg) {
807 navCellStart();
808 printPackageLink(pkg, configuration.getText("doclet.Package"), true,
809 "NavBarFont1");
810 navCellEnd();
811 }
813 /**
814 * Get link to the "package-summary.html" page for the package passed.
815 *
816 * @param pkg Package to which link will be generated
817 * @return a content tree for the link
818 */
819 protected Content getNavLinkPackage(PackageDoc pkg) {
820 Content linkContent = getPackageLink(pkg,
821 packageLabel);
822 Content li = HtmlTree.LI(linkContent);
823 return li;
824 }
826 /**
827 * Print the word "Package" in the navigation bar cell, to indicate that
828 * link is not available here.
829 */
830 protected void navLinkPackage() {
831 navCellStart();
832 fontStyle("NavBarFont1");
833 printText("doclet.Package");
834 fontEnd();
835 navCellEnd();
836 }
838 /**
839 * Get the word "Package" , to indicate that link is not available here.
840 *
841 * @return a content tree for the link
842 */
843 protected Content getNavLinkPackage() {
844 Content li = HtmlTree.LI(packageLabel);
845 return li;
846 }
848 /**
849 * Print the word "Use" in the navigation bar cell, to indicate that link
850 * is not available.
851 */
852 protected void navLinkClassUse() {
853 navCellStart();
854 fontStyle("NavBarFont1");
855 printText("doclet.navClassUse");
856 fontEnd();
857 navCellEnd();
858 }
860 /**
861 * Get the word "Use", to indicate that link is not available.
862 *
863 * @return a content tree for the link
864 */
865 protected Content getNavLinkClassUse() {
866 Content li = HtmlTree.LI(useLabel);
867 return li;
868 }
870 /**
871 * Print link for previous file.
872 *
873 * @param prev File name for the prev link.
874 */
875 public void navLinkPrevious(String prev) {
876 String tag = configuration.getText("doclet.Prev");
877 if (prev != null) {
878 printHyperLink(prev, "", tag, true) ;
879 } else {
880 print(tag);
881 }
882 }
884 /**
885 * Get link for previous file.
886 *
887 * @param prev File name for the prev link
888 * @return a content tree for the link
889 */
890 public Content getNavLinkPrevious(String prev) {
891 Content li;
892 if (prev != null) {
893 li = HtmlTree.LI(getHyperLink(prev, "", prevLabel, "", ""));
894 }
895 else
896 li = HtmlTree.LI(prevLabel);
897 return li;
898 }
900 /**
901 * Print link for next file. If next is null, just print the label
902 * without linking it anywhere.
903 *
904 * @param next File name for the next link.
905 */
906 public void navLinkNext(String next) {
907 String tag = configuration.getText("doclet.Next");
908 if (next != null) {
909 printHyperLink(next, "", tag, true);
910 } else {
911 print(tag);
912 }
913 }
915 /**
916 * Get link for next file. If next is null, just print the label
917 * without linking it anywhere.
918 *
919 * @param next File name for the next link
920 * @return a content tree for the link
921 */
922 public Content getNavLinkNext(String next) {
923 Content li;
924 if (next != null) {
925 li = HtmlTree.LI(getHyperLink(next, "", nextLabel, "", ""));
926 }
927 else
928 li = HtmlTree.LI(nextLabel);
929 return li;
930 }
932 /**
933 * Print "FRAMES" link, to switch to the frame version of the output.
934 *
935 * @param link File to be linked, "index.html".
936 */
937 protected void navShowLists(String link) {
938 print(getHyperLinkString(link + "?" + path + filename, "",
939 configuration.getText("doclet.FRAMES"), true, "", "", "_top"));
940 }
942 /**
943 * Get "FRAMES" link, to switch to the frame version of the output.
944 *
945 * @param link File to be linked, "index.html"
946 * @return a content tree for the link
947 */
948 protected Content getNavShowLists(String link) {
949 Content framesContent = getHyperLink(link + "?" + path +
950 filename, "", framesLabel, "", "_top");
951 Content li = HtmlTree.LI(framesContent);
952 return li;
953 }
955 /**
956 * Print "FRAMES" link, to switch to the frame version of the output.
957 */
958 protected void navShowLists() {
959 navShowLists(relativePath + "index.html");
960 }
962 /**
963 * Get "FRAMES" link, to switch to the frame version of the output.
964 *
965 * @return a content tree for the link
966 */
967 protected Content getNavShowLists() {
968 return getNavShowLists(relativePath + "index.html");
969 }
971 /**
972 * Print "NO FRAMES" link, to switch to the non-frame version of the output.
973 *
974 * @param link File to be linked.
975 */
976 protected void navHideLists(String link) {
977 print(getHyperLinkString(link, "", configuration.getText("doclet.NO_FRAMES"),
978 true, "", "", "_top"));
979 }
981 /**
982 * Get "NO FRAMES" link, to switch to the non-frame version of the output.
983 *
984 * @param link File to be linked
985 * @return a content tree for the link
986 */
987 protected Content getNavHideLists(String link) {
988 Content noFramesContent = getHyperLink(link, "", noframesLabel, "", "_top");
989 Content li = HtmlTree.LI(noFramesContent);
990 return li;
991 }
993 /**
994 * Print "Tree" link in the navigation bar. If there is only one package
995 * specified on the command line, then the "Tree" link will be to the
996 * only "package-tree.html" file otherwise it will be to the
997 * "overview-tree.html" file.
998 */
999 protected void navLinkTree() {
1000 navCellStart();
1001 PackageDoc[] packages = configuration.root.specifiedPackages();
1002 if (packages.length == 1 && configuration.root.specifiedClasses().length == 0) {
1003 printHyperLink(pathString(packages[0], "package-tree.html"), "",
1004 configuration.getText("doclet.Tree"), true, "NavBarFont1");
1005 } else {
1006 printHyperLink(relativePath + "overview-tree.html", "",
1007 configuration.getText("doclet.Tree"), true, "NavBarFont1");
1008 }
1009 navCellEnd();
1010 }
1012 /**
1013 * Get "Tree" link in the navigation bar. If there is only one package
1014 * specified on the command line, then the "Tree" link will be to the
1015 * only "package-tree.html" file otherwise it will be to the
1016 * "overview-tree.html" file.
1017 *
1018 * @return a content tree for the link
1019 */
1020 protected Content getNavLinkTree() {
1021 Content treeLinkContent;
1022 PackageDoc[] packages = configuration.root.specifiedPackages();
1023 if (packages.length == 1 && configuration.root.specifiedClasses().length == 0) {
1024 treeLinkContent = getHyperLink(pathString(packages[0],
1025 "package-tree.html"), "", treeLabel,
1026 "", "");
1027 } else {
1028 treeLinkContent = getHyperLink(relativePath + "overview-tree.html",
1029 "", treeLabel, "", "");
1030 }
1031 Content li = HtmlTree.LI(treeLinkContent);
1032 return li;
1033 }
1035 /**
1036 * Get the overview tree link for the main tree.
1037 *
1038 * @param label the label for the link
1039 * @return a content tree for the link
1040 */
1041 protected Content getNavLinkMainTree(String label) {
1042 Content mainTreeContent = getHyperLink(relativePath + "overview-tree.html",
1043 new StringContent(label));
1044 Content li = HtmlTree.LI(mainTreeContent);
1045 return li;
1046 }
1048 /**
1049 * Print the word "Class" in the navigation bar cell, to indicate that
1050 * class link is not available.
1051 */
1052 protected void navLinkClass() {
1053 navCellStart();
1054 fontStyle("NavBarFont1");
1055 printText("doclet.Class");
1056 fontEnd();
1057 navCellEnd();
1058 }
1060 /**
1061 * Get the word "Class", to indicate that class link is not available.
1062 *
1063 * @return a content tree for the link
1064 */
1065 protected Content getNavLinkClass() {
1066 Content li = HtmlTree.LI(classLabel);
1067 return li;
1068 }
1070 /**
1071 * Print "Deprecated" API link in the navigation bar.
1072 */
1073 protected void navLinkDeprecated() {
1074 navCellStart();
1075 printHyperLink(relativePath + "deprecated-list.html", "",
1076 configuration.getText("doclet.navDeprecated"), true, "NavBarFont1");
1077 navCellEnd();
1078 }
1080 /**
1081 * Get "Deprecated" API link in the navigation bar.
1082 *
1083 * @return a content tree for the link
1084 */
1085 protected Content getNavLinkDeprecated() {
1086 Content linkContent = getHyperLink(relativePath +
1087 "deprecated-list.html", "", deprecatedLabel, "", "");
1088 Content li = HtmlTree.LI(linkContent);
1089 return li;
1090 }
1092 /**
1093 * Print link for generated index. If the user has used "-splitindex"
1094 * command line option, then link to file "index-files/index-1.html" is
1095 * generated otherwise link to file "index-all.html" is generated.
1096 */
1097 protected void navLinkClassIndex() {
1098 printNoFramesTargetHyperLink(relativePath +
1099 AllClassesFrameWriter.OUTPUT_FILE_NAME_NOFRAMES,
1100 "", "", configuration.getText("doclet.All_Classes"), true);
1101 }
1103 /**
1104 * Get link for generated index. If the user has used "-splitindex"
1105 * command line option, then link to file "index-files/index-1.html" is
1106 * generated otherwise link to file "index-all.html" is generated.
1107 *
1108 * @return a content tree for the link
1109 */
1110 protected Content getNavLinkClassIndex() {
1111 Content allClassesContent = getHyperLink(relativePath +
1112 AllClassesFrameWriter.OUTPUT_FILE_NAME_NOFRAMES, "",
1113 allclassesLabel, "", "");
1114 Content li = HtmlTree.LI(allClassesContent);
1115 return li;
1116 }
1117 /**
1118 * Print link for generated class index.
1119 */
1120 protected void navLinkIndex() {
1121 navCellStart();
1122 printHyperLink(relativePath +
1123 (configuration.splitindex?
1124 DirectoryManager.getPath("index-files") +
1125 fileseparator: "") +
1126 (configuration.splitindex?
1127 "index-1.html" : "index-all.html"), "",
1128 configuration.getText("doclet.Index"), true, "NavBarFont1");
1129 navCellEnd();
1130 }
1132 /**
1133 * Get link for generated class index.
1134 *
1135 * @return a content tree for the link
1136 */
1137 protected Content getNavLinkIndex() {
1138 Content linkContent = getHyperLink(relativePath +(configuration.splitindex?
1139 DirectoryManager.getPath("index-files") + fileseparator: "") +
1140 (configuration.splitindex?"index-1.html" : "index-all.html"), "",
1141 indexLabel, "", "");
1142 Content li = HtmlTree.LI(linkContent);
1143 return li;
1144 }
1146 /**
1147 * Print help file link. If user has provided a help file, then generate a
1148 * link to the user given file, which is already copied to current or
1149 * destination directory.
1150 */
1151 protected void navLinkHelp() {
1152 String helpfilenm = configuration.helpfile;
1153 if (helpfilenm.equals("")) {
1154 helpfilenm = "help-doc.html";
1155 } else {
1156 int lastsep;
1157 if ((lastsep = helpfilenm.lastIndexOf(File.separatorChar)) != -1) {
1158 helpfilenm = helpfilenm.substring(lastsep + 1);
1159 }
1160 }
1161 navCellStart();
1162 printHyperLink(relativePath + helpfilenm, "",
1163 configuration.getText("doclet.Help"), true, "NavBarFont1");
1164 navCellEnd();
1165 }
1167 /**
1168 * Get help file link. If user has provided a help file, then generate a
1169 * link to the user given file, which is already copied to current or
1170 * destination directory.
1171 *
1172 * @return a content tree for the link
1173 */
1174 protected Content getNavLinkHelp() {
1175 String helpfilenm = configuration.helpfile;
1176 if (helpfilenm.equals("")) {
1177 helpfilenm = "help-doc.html";
1178 } else {
1179 int lastsep;
1180 if ((lastsep = helpfilenm.lastIndexOf(File.separatorChar)) != -1) {
1181 helpfilenm = helpfilenm.substring(lastsep + 1);
1182 }
1183 }
1184 Content linkContent = getHyperLink(relativePath + helpfilenm, "",
1185 helpLabel, "", "");
1186 Content li = HtmlTree.LI(linkContent);
1187 return li;
1188 }
1190 /**
1191 * Print the word "Detail" in the navigation bar. No link is available.
1192 */
1193 protected void navDetail() {
1194 printText("doclet.Detail");
1195 }
1197 /**
1198 * Print the word "Summary" in the navigation bar. No link is available.
1199 */
1200 protected void navSummary() {
1201 printText("doclet.Summary");
1202 }
1204 /**
1205 * Print the Html table tag for the index summary tables. The table tag
1206 * printed is
1207 * {@code <TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%"> }
1208 */
1209 public void tableIndexSummary() {
1210 table(1, "100%", 3, 0);
1211 }
1213 /**
1214 * Print the Html table tag for the index summary tables.
1215 *
1216 * @param summary the summary for the table tag summary attribute.
1217 */
1218 public void tableIndexSummary(String summary) {
1219 table(1, "100%", 3, 0, summary);
1220 }
1222 /**
1223 * Same as {@link #tableIndexSummary()}.
1224 */
1225 public void tableIndexDetail() {
1226 table(1, "100%", 3, 0);
1227 }
1229 /**
1230 * Print Html tag for table elements. The tag printed is
1231 * <TD ALIGN="right" VALIGN="top" WIDTH="1%">.
1232 */
1233 public void tdIndex() {
1234 print("<TD ALIGN=\"right\" VALIGN=\"top\" WIDTH=\"1%\">");
1235 }
1237 /**
1238 * Print table caption.
1239 */
1240 public void tableCaptionStart() {
1241 captionStyle("TableCaption");
1242 }
1244 /**
1245 * Print table sub-caption.
1246 */
1247 public void tableSubCaptionStart() {
1248 captionStyle("TableSubCaption");
1249 }
1251 /**
1252 * Print table caption end tags.
1253 */
1254 public void tableCaptionEnd() {
1255 captionEnd();
1256 }
1258 /**
1259 * Print summary table header.
1260 */
1261 public void summaryTableHeader(String[] header, String scope) {
1262 tr();
1263 for ( int i=0; i < header.length; i++ ) {
1264 thScopeNoWrap("TableHeader", scope);
1265 print(header[i]);
1266 thEnd();
1267 }
1268 trEnd();
1269 }
1271 /**
1272 * Get summary table header.
1273 *
1274 * @param header the header for the table
1275 * @param scope the scope of the headers
1276 * @return a content tree for the header
1277 */
1278 public Content getSummaryTableHeader(String[] header, String scope) {
1279 Content tr = new HtmlTree(HtmlTag.TR);
1280 int size = header.length;
1281 Content tableHeader;
1282 if (size == 1) {
1283 tableHeader = new StringContent(header[0]);
1284 tr.addContent(HtmlTree.TH(HtmlStyle.colOne, scope, tableHeader));
1285 return tr;
1286 }
1287 for (int i = 0; i < size; i++) {
1288 tableHeader = new StringContent(header[i]);
1289 if(i == 0)
1290 tr.addContent(HtmlTree.TH(HtmlStyle.colFirst, scope, tableHeader));
1291 else if(i == (size - 1))
1292 tr.addContent(HtmlTree.TH(HtmlStyle.colLast, scope, tableHeader));
1293 else
1294 tr.addContent(HtmlTree.TH(scope, tableHeader));
1295 }
1296 return tr;
1297 }
1299 /**
1300 * Get table caption.
1301 *
1302 * @param rawText the caption for the table which could be raw Html
1303 * @return a content tree for the caption
1304 */
1305 public Content getTableCaption(String rawText) {
1306 Content title = new RawHtml(rawText);
1307 Content captionSpan = HtmlTree.SPAN(title);
1308 Content space = getSpace();
1309 Content tabSpan = HtmlTree.SPAN(HtmlStyle.tabEnd, space);
1310 Content caption = HtmlTree.CAPTION(captionSpan);
1311 caption.addContent(tabSpan);
1312 return caption;
1313 }
1315 /**
1316 * Get the marker anchor which will be added to the documentation tree.
1317 *
1318 * @param anchorName the anchor name attribute
1319 * @return a content tree for the marker anchor
1320 */
1321 public Content getMarkerAnchor(String anchorName) {
1322 return getMarkerAnchor(anchorName, null);
1323 }
1325 /**
1326 * Get the marker anchor which will be added to the documentation tree.
1327 *
1328 * @param anchorName the anchor name attribute
1329 * @param anchorContent the content that should be added to the anchor
1330 * @return a content tree for the marker anchor
1331 */
1332 public Content getMarkerAnchor(String anchorName, Content anchorContent) {
1333 if (anchorContent == null)
1334 anchorContent = new Comment(" ");
1335 Content markerAnchor = HtmlTree.A_NAME(anchorName, anchorContent);
1336 return markerAnchor;
1337 }
1339 /**
1340 * Returns a packagename content.
1341 *
1342 * @param packageDoc the package to check
1343 * @return package name content
1344 */
1345 public Content getPackageName(PackageDoc packageDoc) {
1346 return packageDoc == null || packageDoc.name().length() == 0 ?
1347 defaultPackageLabel :
1348 getPackageLabel(packageDoc.name());
1349 }
1351 /**
1352 * Returns a package name label.
1353 *
1354 * @param packageName the package name
1355 * @return the package name content
1356 */
1357 public Content getPackageLabel(String packageName) {
1358 return new StringContent(packageName);
1359 }
1361 /**
1362 * Add package deprecation information to the documentation tree
1363 *
1364 * @param deprPkgs list of deprecated packages
1365 * @param headingKey the caption for the deprecated package table
1366 * @param tableSummary the summary for the deprecated package table
1367 * @param tableHeader table headers for the deprecated package table
1368 * @param contentTree the content tree to which the deprecated package table will be added
1369 */
1370 protected void addPackageDeprecatedAPI(List<Doc> deprPkgs, String headingKey,
1371 String tableSummary, String[] tableHeader, Content contentTree) {
1372 if (deprPkgs.size() > 0) {
1373 Content table = HtmlTree.TABLE(0, 3, 0, tableSummary,
1374 getTableCaption(configuration().getText(headingKey)));
1375 table.addContent(getSummaryTableHeader(tableHeader, "col"));
1376 Content tbody = new HtmlTree(HtmlTag.TBODY);
1377 for (int i = 0; i < deprPkgs.size(); i++) {
1378 PackageDoc pkg = (PackageDoc) deprPkgs.get(i);
1379 HtmlTree td = HtmlTree.TD(HtmlStyle.colOne,
1380 getPackageLink(pkg, getPackageName(pkg)));
1381 if (pkg.tags("deprecated").length > 0) {
1382 addInlineDeprecatedComment(pkg, pkg.tags("deprecated")[0], td);
1383 }
1384 HtmlTree tr = HtmlTree.TR(td);
1385 if (i % 2 == 0) {
1386 tr.addStyle(HtmlStyle.altColor);
1387 } else {
1388 tr.addStyle(HtmlStyle.rowColor);
1389 }
1390 tbody.addContent(tr);
1391 }
1392 table.addContent(tbody);
1393 Content li = HtmlTree.LI(HtmlStyle.blockList, table);
1394 Content ul = HtmlTree.UL(HtmlStyle.blockList, li);
1395 contentTree.addContent(ul);
1396 }
1397 }
1399 /**
1400 * Prine table header information about color, column span and the font.
1401 *
1402 * @param color Background color.
1403 * @param span Column span.
1404 */
1405 public void tableHeaderStart(String color, int span) {
1406 trBgcolorStyle(color, "TableHeadingColor");
1407 thAlignColspan("left", span);
1408 font("+2");
1409 }
1411 /**
1412 * Print table header for the inherited members summary tables. Print the
1413 * background color information.
1414 *
1415 * @param color Background color.
1416 */
1417 public void tableInheritedHeaderStart(String color) {
1418 trBgcolorStyle(color, "TableSubHeadingColor");
1419 thAlign("left");
1420 }
1422 /**
1423 * Print "Use" table header. Print the background color and the column span.
1424 *
1425 * @param color Background color.
1426 */
1427 public void tableUseInfoHeaderStart(String color) {
1428 trBgcolorStyle(color, "TableSubHeadingColor");
1429 thAlignColspan("left", 2);
1430 }
1432 /**
1433 * Print table header with the background color with default column span 2.
1434 *
1435 * @param color Background color.
1436 */
1437 public void tableHeaderStart(String color) {
1438 tableHeaderStart(color, 2);
1439 }
1441 /**
1442 * Print table header with the column span, with the default color #CCCCFF.
1443 *
1444 * @param span Column span.
1445 */
1446 public void tableHeaderStart(int span) {
1447 tableHeaderStart("#CCCCFF", span);
1448 }
1450 /**
1451 * Print table header with default column span 2 and default color #CCCCFF.
1452 */
1453 public void tableHeaderStart() {
1454 tableHeaderStart(2);
1455 }
1457 /**
1458 * Print table header end tags for font, column and row.
1459 */
1460 public void tableHeaderEnd() {
1461 fontEnd();
1462 thEnd();
1463 trEnd();
1464 }
1466 /**
1467 * Print table header end tags in inherited tables for column and row.
1468 */
1469 public void tableInheritedHeaderEnd() {
1470 thEnd();
1471 trEnd();
1472 }
1474 /**
1475 * Print the summary table row cell attribute width.
1476 *
1477 * @param width Width of the table cell.
1478 */
1479 public void summaryRow(int width) {
1480 if (width != 0) {
1481 tdWidth(width + "%");
1482 } else {
1483 td();
1484 }
1485 }
1487 /**
1488 * Print the summary table row cell end tag.
1489 */
1490 public void summaryRowEnd() {
1491 tdEnd();
1492 }
1494 /**
1495 * Print the heading in Html {@literal <H2>} format.
1496 *
1497 * @param str The Header string.
1498 */
1499 public void printIndexHeading(String str) {
1500 h2();
1501 print(str);
1502 h2End();
1503 }
1505 /**
1506 * Print Html tag <FRAMESET=arg>.
1507 *
1508 * @param arg Argument for the tag.
1509 */
1510 public void frameSet(String arg) {
1511 println("<FRAMESET " + arg + ">");
1512 }
1514 /**
1515 * Print Html closing tag </FRAMESET>.
1516 */
1517 public void frameSetEnd() {
1518 println("</FRAMESET>");
1519 }
1521 /**
1522 * Print Html tag <FRAME=arg>.
1523 *
1524 * @param arg Argument for the tag.
1525 */
1526 public void frame(String arg) {
1527 println("<FRAME " + arg + ">");
1528 }
1530 /**
1531 * Print Html closing tag </FRAME>.
1532 */
1533 public void frameEnd() {
1534 println("</FRAME>");
1535 }
1537 /**
1538 * Return path to the class page for a classdoc. For example, the class
1539 * name is "java.lang.Object" and if the current file getting generated is
1540 * "java/io/File.html", then the path string to the class, returned is
1541 * "../../java/lang.Object.html".
1542 *
1543 * @param cd Class to which the path is requested.
1544 */
1545 protected String pathToClass(ClassDoc cd) {
1546 return pathString(cd.containingPackage(), cd.name() + ".html");
1547 }
1549 /**
1550 * Return the path to the class page for a classdoc. Works same as
1551 * {@link #pathToClass(ClassDoc)}.
1552 *
1553 * @param cd Class to which the path is requested.
1554 * @param name Name of the file(doesn't include path).
1555 */
1556 protected String pathString(ClassDoc cd, String name) {
1557 return pathString(cd.containingPackage(), name);
1558 }
1560 /**
1561 * Return path to the given file name in the given package. So if the name
1562 * passed is "Object.html" and the name of the package is "java.lang", and
1563 * if the relative path is "../.." then returned string will be
1564 * "../../java/lang/Object.html"
1565 *
1566 * @param pd Package in which the file name is assumed to be.
1567 * @param name File name, to which path string is.
1568 */
1569 protected String pathString(PackageDoc pd, String name) {
1570 StringBuilder buf = new StringBuilder(relativePath);
1571 buf.append(DirectoryManager.getPathToPackage(pd, name));
1572 return buf.toString();
1573 }
1575 /**
1576 * Print the link to the given package.
1577 *
1578 * @param pkg the package to link to.
1579 * @param label the label for the link.
1580 * @param isStrong true if the label should be strong.
1581 */
1582 public void printPackageLink(PackageDoc pkg, String label, boolean isStrong) {
1583 print(getPackageLinkString(pkg, label, isStrong));
1584 }
1586 /**
1587 * Print the link to the given package.
1588 *
1589 * @param pkg the package to link to.
1590 * @param label the label for the link.
1591 * @param isStrong true if the label should be strong.
1592 * @param style the font of the package link label.
1593 */
1594 public void printPackageLink(PackageDoc pkg, String label, boolean isStrong,
1595 String style) {
1596 print(getPackageLinkString(pkg, label, isStrong, style));
1597 }
1599 /**
1600 * Return the link to the given package.
1601 *
1602 * @param pkg the package to link to.
1603 * @param label the label for the link.
1604 * @param isStrong true if the label should be strong.
1605 * @return the link to the given package.
1606 */
1607 public String getPackageLinkString(PackageDoc pkg, String label,
1608 boolean isStrong) {
1609 return getPackageLinkString(pkg, label, isStrong, "");
1610 }
1612 /**
1613 * Return the link to the given package.
1614 *
1615 * @param pkg the package to link to.
1616 * @param label the label for the link.
1617 * @param isStrong true if the label should be strong.
1618 * @param style the font of the package link label.
1619 * @return the link to the given package.
1620 */
1621 public String getPackageLinkString(PackageDoc pkg, String label, boolean isStrong,
1622 String style) {
1623 boolean included = pkg != null && pkg.isIncluded();
1624 if (! included) {
1625 PackageDoc[] packages = configuration.packages;
1626 for (int i = 0; i < packages.length; i++) {
1627 if (packages[i].equals(pkg)) {
1628 included = true;
1629 break;
1630 }
1631 }
1632 }
1633 if (included || pkg == null) {
1634 return getHyperLinkString(pathString(pkg, "package-summary.html"),
1635 "", label, isStrong, style);
1636 } else {
1637 String crossPkgLink = getCrossPackageLink(Util.getPackageName(pkg));
1638 if (crossPkgLink != null) {
1639 return getHyperLinkString(crossPkgLink, "", label, isStrong, style);
1640 } else {
1641 return label;
1642 }
1643 }
1644 }
1646 /**
1647 * Return the link to the given package.
1648 *
1649 * @param pkg the package to link to.
1650 * @param label the label for the link.
1651 * @return a content tree for the package link.
1652 */
1653 public Content getPackageLink(PackageDoc pkg, Content label) {
1654 boolean included = pkg != null && pkg.isIncluded();
1655 if (! included) {
1656 PackageDoc[] packages = configuration.packages;
1657 for (int i = 0; i < packages.length; i++) {
1658 if (packages[i].equals(pkg)) {
1659 included = true;
1660 break;
1661 }
1662 }
1663 }
1664 if (included || pkg == null) {
1665 return getHyperLink(pathString(pkg, "package-summary.html"),
1666 "", label);
1667 } else {
1668 String crossPkgLink = getCrossPackageLink(Util.getPackageName(pkg));
1669 if (crossPkgLink != null) {
1670 return getHyperLink(crossPkgLink, "", label);
1671 } else {
1672 return label;
1673 }
1674 }
1675 }
1677 public String italicsClassName(ClassDoc cd, boolean qual) {
1678 String name = (qual)? cd.qualifiedName(): cd.name();
1679 return (cd.isInterface())? italicsText(name): name;
1680 }
1682 public void printSrcLink(ProgramElementDoc d, String label) {
1683 if (d == null) {
1684 return;
1685 }
1686 ClassDoc cd = d.containingClass();
1687 if (cd == null) {
1688 //d must be a class doc since in has no containing class.
1689 cd = (ClassDoc) d;
1690 }
1691 String href = relativePath + DocletConstants.SOURCE_OUTPUT_DIR_NAME
1692 + DirectoryManager.getDirectoryPath(cd.containingPackage())
1693 + cd.name() + ".html#" + SourceToHTMLConverter.getAnchorName(d);
1694 printHyperLink(href, "", label, true);
1695 }
1697 /**
1698 * Add the link to the content tree.
1699 *
1700 * @param doc program element doc for which the link will be added
1701 * @param label label for the link
1702 * @param htmltree the content tree to which the link will be added
1703 */
1704 public void addSrcLink(ProgramElementDoc doc, Content label, Content htmltree) {
1705 if (doc == null) {
1706 return;
1707 }
1708 ClassDoc cd = doc.containingClass();
1709 if (cd == null) {
1710 //d must be a class doc since in has no containing class.
1711 cd = (ClassDoc) doc;
1712 }
1713 String href = relativePath + DocletConstants.SOURCE_OUTPUT_DIR_NAME
1714 + DirectoryManager.getDirectoryPath(cd.containingPackage())
1715 + cd.name() + ".html#" + SourceToHTMLConverter.getAnchorName(doc);
1716 Content linkContent = getHyperLink(href, "", label, "", "");
1717 htmltree.addContent(linkContent);
1718 }
1720 /**
1721 * Return the link to the given class.
1722 *
1723 * @param linkInfo the information about the link.
1724 *
1725 * @return the link for the given class.
1726 */
1727 public String getLink(LinkInfoImpl linkInfo) {
1728 LinkFactoryImpl factory = new LinkFactoryImpl(this);
1729 String link = ((LinkOutputImpl) factory.getLinkOutput(linkInfo)).toString();
1730 displayLength += linkInfo.displayLength;
1731 return link;
1732 }
1734 /**
1735 * Return the type parameters for the given class.
1736 *
1737 * @param linkInfo the information about the link.
1738 * @return the type for the given class.
1739 */
1740 public String getTypeParameterLinks(LinkInfoImpl linkInfo) {
1741 LinkFactoryImpl factory = new LinkFactoryImpl(this);
1742 return ((LinkOutputImpl)
1743 factory.getTypeParameterLinks(linkInfo, false)).toString();
1744 }
1746 /**
1747 * Print the link to the given class.
1748 */
1749 public void printLink(LinkInfoImpl linkInfo) {
1750 print(getLink(linkInfo));
1751 }
1753 /*************************************************************
1754 * Return a class cross link to external class documentation.
1755 * The name must be fully qualified to determine which package
1756 * the class is in. The -link option does not allow users to
1757 * link to external classes in the "default" package.
1758 *
1759 * @param qualifiedClassName the qualified name of the external class.
1760 * @param refMemName the name of the member being referenced. This should
1761 * be null or empty string if no member is being referenced.
1762 * @param label the label for the external link.
1763 * @param strong true if the link should be strong.
1764 * @param style the style of the link.
1765 * @param code true if the label should be code font.
1766 */
1767 public String getCrossClassLink(String qualifiedClassName, String refMemName,
1768 String label, boolean strong, String style,
1769 boolean code) {
1770 String className = "",
1771 packageName = qualifiedClassName == null ? "" : qualifiedClassName;
1772 int periodIndex;
1773 while((periodIndex = packageName.lastIndexOf('.')) != -1) {
1774 className = packageName.substring(periodIndex + 1, packageName.length()) +
1775 (className.length() > 0 ? "." + className : "");
1776 String defaultLabel = code ? getCode() + className + getCodeEnd() : className;
1777 packageName = packageName.substring(0, periodIndex);
1778 if (getCrossPackageLink(packageName) != null) {
1779 //The package exists in external documentation, so link to the external
1780 //class (assuming that it exists). This is definitely a limitation of
1781 //the -link option. There are ways to determine if an external package
1782 //exists, but no way to determine if the external class exists. We just
1783 //have to assume that it does.
1784 return getHyperLinkString(
1785 configuration.extern.getExternalLink(packageName, relativePath,
1786 className + ".html?is-external=true"),
1787 refMemName == null ? "" : refMemName,
1788 label == null || label.length() == 0 ? defaultLabel : label,
1789 strong, style,
1790 configuration.getText("doclet.Href_Class_Or_Interface_Title", packageName),
1791 "");
1792 }
1793 }
1794 return null;
1795 }
1797 public boolean isClassLinkable(ClassDoc cd) {
1798 if (cd.isIncluded()) {
1799 return configuration.isGeneratedDoc(cd);
1800 }
1801 return configuration.extern.isExternal(cd);
1802 }
1804 public String getCrossPackageLink(String pkgName) {
1805 return configuration.extern.getExternalLink(pkgName, relativePath,
1806 "package-summary.html?is-external=true");
1807 }
1809 /**
1810 * Get the class link.
1811 *
1812 * @param context the id of the context where the link will be added
1813 * @param cd the class doc to link to
1814 * @return a content tree for the link
1815 */
1816 public Content getQualifiedClassLink(int context, ClassDoc cd) {
1817 return new RawHtml(getLink(new LinkInfoImpl(context, cd,
1818 configuration.getClassName(cd), "")));
1819 }
1821 /**
1822 * Add the class link.
1823 *
1824 * @param context the id of the context where the link will be added
1825 * @param cd the class doc to link to
1826 * @param contentTree the content tree to which the link will be added
1827 */
1828 public void addPreQualifiedClassLink(int context, ClassDoc cd, Content contentTree) {
1829 addPreQualifiedClassLink(context, cd, false, contentTree);
1830 }
1832 /**
1833 * Retrieve the class link with the package portion of the label in
1834 * plain text. If the qualifier is excluded, it willnot be included in the
1835 * link label.
1836 *
1837 * @param cd the class to link to.
1838 * @param isStrong true if the link should be strong.
1839 * @return the link with the package portion of the label in plain text.
1840 */
1841 public String getPreQualifiedClassLink(int context,
1842 ClassDoc cd, boolean isStrong) {
1843 String classlink = "";
1844 PackageDoc pd = cd.containingPackage();
1845 if(pd != null && ! configuration.shouldExcludeQualifier(pd.name())) {
1846 classlink = getPkgName(cd);
1847 }
1848 classlink += getLink(new LinkInfoImpl(context, cd, cd.name(), isStrong));
1849 return classlink;
1850 }
1852 /**
1853 * Add the class link with the package portion of the label in
1854 * plain text. If the qualifier is excluded, it will not be included in the
1855 * link label.
1856 *
1857 * @param context the id of the context where the link will be added
1858 * @param cd the class to link to
1859 * @param isStrong true if the link should be strong
1860 * @param contentTree the content tree to which the link with be added
1861 */
1862 public void addPreQualifiedClassLink(int context,
1863 ClassDoc cd, boolean isStrong, Content contentTree) {
1864 PackageDoc pd = cd.containingPackage();
1865 if(pd != null && ! configuration.shouldExcludeQualifier(pd.name())) {
1866 contentTree.addContent(getPkgName(cd));
1867 }
1868 contentTree.addContent(new RawHtml(getLink(new LinkInfoImpl(
1869 context, cd, cd.name(), isStrong))));
1870 }
1872 /**
1873 * Add the class link, with only class name as the strong link and prefixing
1874 * plain package name.
1875 *
1876 * @param context the id of the context where the link will be added
1877 * @param cd the class to link to
1878 * @param contentTree the content tree to which the link with be added
1879 */
1880 public void addPreQualifiedStrongClassLink(int context, ClassDoc cd, Content contentTree) {
1881 addPreQualifiedClassLink(context, cd, true, contentTree);
1882 }
1884 public void printText(String key) {
1885 print(configuration.getText(key));
1886 }
1888 public void printText(String key, String a1) {
1889 print(configuration.getText(key, a1));
1890 }
1892 public void printText(String key, String a1, String a2) {
1893 print(configuration.getText(key, a1, a2));
1894 }
1896 public void strongText(String key) {
1897 strong(configuration.getText(key));
1898 }
1900 public void strongText(String key, String a1) {
1901 strong(configuration.getText(key, a1));
1902 }
1904 public void strongText(String key, String a1, String a2) {
1905 strong(configuration.getText(key, a1, a2));
1906 }
1908 /**
1909 * Get the link for the given member.
1910 *
1911 * @param context the id of the context where the link will be added
1912 * @param doc the member being linked to
1913 * @param label the label for the link
1914 * @return a content tree for the doc link
1915 */
1916 public Content getDocLink(int context, MemberDoc doc, String label) {
1917 return getDocLink(context, doc.containingClass(), doc, label);
1918 }
1920 /**
1921 * Print the link for the given member.
1922 *
1923 * @param context the id of the context where the link will be printed.
1924 * @param classDoc the classDoc that we should link to. This is not
1925 * necessarily equal to doc.containingClass(). We may be
1926 * inheriting comments.
1927 * @param doc the member being linked to.
1928 * @param label the label for the link.
1929 * @param strong true if the link should be strong.
1930 */
1931 public void printDocLink(int context, ClassDoc classDoc, MemberDoc doc,
1932 String label, boolean strong) {
1933 print(getDocLink(context, classDoc, doc, label, strong));
1934 }
1936 /**
1937 * Return the link for the given member.
1938 *
1939 * @param context the id of the context where the link will be printed.
1940 * @param doc the member being linked to.
1941 * @param label the label for the link.
1942 * @param strong true if the link should be strong.
1943 * @return the link for the given member.
1944 */
1945 public String getDocLink(int context, MemberDoc doc, String label,
1946 boolean strong) {
1947 return getDocLink(context, doc.containingClass(), doc, label, strong);
1948 }
1950 /**
1951 * Return the link for the given member.
1952 *
1953 * @param context the id of the context where the link will be printed.
1954 * @param classDoc the classDoc that we should link to. This is not
1955 * necessarily equal to doc.containingClass(). We may be
1956 * inheriting comments.
1957 * @param doc the member being linked to.
1958 * @param label the label for the link.
1959 * @param strong true if the link should be strong.
1960 * @return the link for the given member.
1961 */
1962 public String getDocLink(int context, ClassDoc classDoc, MemberDoc doc,
1963 String label, boolean strong) {
1964 if (! (doc.isIncluded() ||
1965 Util.isLinkable(classDoc, configuration()))) {
1966 return label;
1967 } else if (doc instanceof ExecutableMemberDoc) {
1968 ExecutableMemberDoc emd = (ExecutableMemberDoc)doc;
1969 return getLink(new LinkInfoImpl(context, classDoc,
1970 getAnchor(emd), label, strong));
1971 } else if (doc instanceof MemberDoc) {
1972 return getLink(new LinkInfoImpl(context, classDoc,
1973 doc.name(), label, strong));
1974 } else {
1975 return label;
1976 }
1977 }
1979 /**
1980 * Return the link for the given member.
1981 *
1982 * @param context the id of the context where the link will be added
1983 * @param classDoc the classDoc that we should link to. This is not
1984 * necessarily equal to doc.containingClass(). We may be
1985 * inheriting comments
1986 * @param doc the member being linked to
1987 * @param label the label for the link
1988 * @return the link for the given member
1989 */
1990 public Content getDocLink(int context, ClassDoc classDoc, MemberDoc doc,
1991 String label) {
1992 if (! (doc.isIncluded() ||
1993 Util.isLinkable(classDoc, configuration()))) {
1994 return new StringContent(label);
1995 } else if (doc instanceof ExecutableMemberDoc) {
1996 ExecutableMemberDoc emd = (ExecutableMemberDoc)doc;
1997 return new RawHtml(getLink(new LinkInfoImpl(context, classDoc,
1998 getAnchor(emd), label, false)));
1999 } else if (doc instanceof MemberDoc) {
2000 return new RawHtml(getLink(new LinkInfoImpl(context, classDoc,
2001 doc.name(), label, false)));
2002 } else {
2003 return new StringContent(label);
2004 }
2005 }
2007 public void anchor(ExecutableMemberDoc emd) {
2008 anchor(getAnchor(emd));
2009 }
2011 public String getAnchor(ExecutableMemberDoc emd) {
2012 StringBuilder signature = new StringBuilder(emd.signature());
2013 StringBuilder signatureParsed = new StringBuilder();
2014 int counter = 0;
2015 for (int i = 0; i < signature.length(); i++) {
2016 char c = signature.charAt(i);
2017 if (c == '<') {
2018 counter++;
2019 } else if (c == '>') {
2020 counter--;
2021 } else if (counter == 0) {
2022 signatureParsed.append(c);
2023 }
2024 }
2025 return emd.name() + signatureParsed.toString();
2026 }
2028 public String seeTagToString(SeeTag see) {
2029 String tagName = see.name();
2030 if (! (tagName.startsWith("@link") || tagName.equals("@see"))) {
2031 return "";
2032 }
2033 StringBuilder result = new StringBuilder();
2034 boolean isplaintext = tagName.toLowerCase().equals("@linkplain");
2035 String label = see.label();
2036 label = (label.length() > 0)?
2037 ((isplaintext) ? label :
2038 getCode() + label + getCodeEnd()):"";
2039 String seetext = replaceDocRootDir(see.text());
2041 //Check if @see is an href or "string"
2042 if (seetext.startsWith("<") || seetext.startsWith("\"")) {
2043 result.append(seetext);
2044 return result.toString();
2045 }
2047 //The text from the @see tag. We will output this text when a label is not specified.
2048 String text = (isplaintext) ? seetext : getCode() + seetext + getCodeEnd();
2050 ClassDoc refClass = see.referencedClass();
2051 String refClassName = see.referencedClassName();
2052 MemberDoc refMem = see.referencedMember();
2053 String refMemName = see.referencedMemberName();
2054 if (refClass == null) {
2055 //@see is not referencing an included class
2056 PackageDoc refPackage = see.referencedPackage();
2057 if (refPackage != null && refPackage.isIncluded()) {
2058 //@see is referencing an included package
2059 String packageName = isplaintext ? refPackage.name() :
2060 getCode() + refPackage.name() + getCodeEnd();
2061 result.append(getPackageLinkString(refPackage,
2062 label.length() == 0 ? packageName : label, false));
2063 } else {
2064 //@see is not referencing an included class or package. Check for cross links.
2065 String classCrossLink, packageCrossLink = getCrossPackageLink(refClassName);
2066 if (packageCrossLink != null) {
2067 //Package cross link found
2068 result.append(getHyperLinkString(packageCrossLink, "",
2069 (label.length() == 0)? text : label, false));
2070 } else if ((classCrossLink = getCrossClassLink(refClassName,
2071 refMemName, label, false, "", ! isplaintext)) != null) {
2072 //Class cross link found (possiblly to a member in the class)
2073 result.append(classCrossLink);
2074 } else {
2075 //No cross link found so print warning
2076 configuration.getDocletSpecificMsg().warning(see.position(), "doclet.see.class_or_package_not_found",
2077 tagName, seetext);
2078 result.append((label.length() == 0)? text: label);
2079 }
2080 }
2081 } else if (refMemName == null) {
2082 // Must be a class reference since refClass is not null and refMemName is null.
2083 if (label.length() == 0) {
2084 label = (isplaintext) ? refClass.name() : getCode() + refClass.name() + getCodeEnd();
2085 result.append(getLink(new LinkInfoImpl(refClass, label)));
2086 } else {
2087 result.append(getLink(new LinkInfoImpl(refClass, label)));
2088 }
2089 } else if (refMem == null) {
2090 // Must be a member reference since refClass is not null and refMemName is not null.
2091 // However, refMem is null, so this referenced member does not exist.
2092 result.append((label.length() == 0)? text: label);
2093 } else {
2094 // Must be a member reference since refClass is not null and refMemName is not null.
2095 // refMem is not null, so this @see tag must be referencing a valid member.
2096 ClassDoc containing = refMem.containingClass();
2097 if (see.text().trim().startsWith("#") &&
2098 ! (containing.isPublic() ||
2099 Util.isLinkable(containing, configuration()))) {
2100 // Since the link is relative and the holder is not even being
2101 // documented, this must be an inherited link. Redirect it.
2102 // The current class either overrides the referenced member or
2103 // inherits it automatically.
2104 if (this instanceof ClassWriterImpl) {
2105 containing = ((ClassWriterImpl) this).getClassDoc();
2106 } else if (!containing.isPublic()){
2107 configuration.getDocletSpecificMsg().warning(
2108 see.position(), "doclet.see.class_or_package_not_accessible",
2109 tagName, containing.qualifiedName());
2110 } else {
2111 configuration.getDocletSpecificMsg().warning(
2112 see.position(), "doclet.see.class_or_package_not_found",
2113 tagName, seetext);
2114 }
2115 }
2116 if (configuration.currentcd != containing) {
2117 refMemName = containing.name() + "." + refMemName;
2118 }
2119 if (refMem instanceof ExecutableMemberDoc) {
2120 if (refMemName.indexOf('(') < 0) {
2121 refMemName += ((ExecutableMemberDoc)refMem).signature();
2122 }
2123 }
2124 text = (isplaintext) ?
2125 refMemName : getCode() + Util.escapeHtmlChars(refMemName) + getCodeEnd();
2127 result.append(getDocLink(LinkInfoImpl.CONTEXT_SEE_TAG, containing,
2128 refMem, (label.length() == 0)? text: label, false));
2129 }
2130 return result.toString();
2131 }
2133 public void printInlineComment(Doc doc, Tag tag) {
2134 printCommentTags(doc, tag.inlineTags(), false, false);
2135 }
2137 /**
2138 * Add the inline comment.
2139 *
2140 * @param doc the doc for which the inline comment will be added
2141 * @param tag the inline tag to be added
2142 * @param htmltree the content tree to which the comment will be added
2143 */
2144 public void addInlineComment(Doc doc, Tag tag, Content htmltree) {
2145 addCommentTags(doc, tag.inlineTags(), false, false, htmltree);
2146 }
2148 public void printInlineDeprecatedComment(Doc doc, Tag tag) {
2149 printCommentTags(doc, tag.inlineTags(), true, false);
2150 }
2152 /**
2153 * Add the inline deprecated comment.
2154 *
2155 * @param doc the doc for which the inline deprecated comment will be added
2156 * @param tag the inline tag to be added
2157 * @param htmltree the content tree to which the comment will be added
2158 */
2159 public void addInlineDeprecatedComment(Doc doc, Tag tag, Content htmltree) {
2160 addCommentTags(doc, tag.inlineTags(), true, false, htmltree);
2161 }
2163 public void printSummaryComment(Doc doc) {
2164 printSummaryComment(doc, doc.firstSentenceTags());
2165 }
2167 /**
2168 * Adds the summary content.
2169 *
2170 * @param doc the doc for which the summary will be generated
2171 * @param htmltree the documentation tree to which the summary will be added
2172 */
2173 public void addSummaryComment(Doc doc, Content htmltree) {
2174 addSummaryComment(doc, doc.firstSentenceTags(), htmltree);
2175 }
2177 public void printSummaryComment(Doc doc, Tag[] firstSentenceTags) {
2178 printCommentTags(doc, firstSentenceTags, false, true);
2179 }
2181 /**
2182 * Adds the summary content.
2183 *
2184 * @param doc the doc for which the summary will be generated
2185 * @param firstSentenceTags the first sentence tags for the doc
2186 * @param htmltree the documentation tree to which the summary will be added
2187 */
2188 public void addSummaryComment(Doc doc, Tag[] firstSentenceTags, Content htmltree) {
2189 addCommentTags(doc, firstSentenceTags, false, true, htmltree);
2190 }
2192 public void printSummaryDeprecatedComment(Doc doc) {
2193 printCommentTags(doc, doc.firstSentenceTags(), true, true);
2194 }
2196 public void printSummaryDeprecatedComment(Doc doc, Tag tag) {
2197 printCommentTags(doc, tag.firstSentenceTags(), true, true);
2198 }
2200 public void addSummaryDeprecatedComment(Doc doc, Tag tag, Content htmltree) {
2201 addCommentTags(doc, tag.firstSentenceTags(), true, true, htmltree);
2202 }
2204 public void printInlineComment(Doc doc) {
2205 printCommentTags(doc, doc.inlineTags(), false, false);
2206 p();
2207 }
2209 /**
2210 * Adds the inline comment.
2211 *
2212 * @param doc the doc for which the inline comments will be generated
2213 * @param htmltree the documentation tree to which the inline comments will be added
2214 */
2215 public void addInlineComment(Doc doc, Content htmltree) {
2216 addCommentTags(doc, doc.inlineTags(), false, false, htmltree);
2217 }
2219 public void printInlineDeprecatedComment(Doc doc) {
2220 printCommentTags(doc, doc.inlineTags(), true, false);
2221 }
2223 private void printCommentTags(Doc doc, Tag[] tags, boolean depr, boolean first) {
2224 if(configuration.nocomment){
2225 return;
2226 }
2227 if (depr) {
2228 italic();
2229 }
2230 String result = commentTagsToString(null, doc, tags, first);
2231 print(result);
2232 if (depr) {
2233 italicEnd();
2234 }
2235 if (tags.length == 0) {
2236 space();
2237 }
2238 }
2240 /**
2241 * Adds the comment tags.
2242 *
2243 * @param doc the doc for which the comment tags will be generated
2244 * @param tags the first sentence tags for the doc
2245 * @param depr true if it is deprecated
2246 * @param first true if the first sentenge tags should be added
2247 * @param htmltree the documentation tree to which the comment tags will be added
2248 */
2249 private void addCommentTags(Doc doc, Tag[] tags, boolean depr,
2250 boolean first, Content htmltree) {
2251 if(configuration.nocomment){
2252 return;
2253 }
2254 Content div;
2255 Content result = new RawHtml(commentTagsToString(null, doc, tags, first));
2256 if (depr) {
2257 Content italic = HtmlTree.I(result);
2258 div = HtmlTree.DIV(HtmlStyle.block, italic);
2259 htmltree.addContent(div);
2260 }
2261 else {
2262 div = HtmlTree.DIV(HtmlStyle.block, result);
2263 htmltree.addContent(div);
2264 }
2265 if (tags.length == 0) {
2266 htmltree.addContent(getSpace());
2267 }
2268 }
2270 /**
2271 * Converts inline tags and text to text strings, expanding the
2272 * inline tags along the way. Called wherever text can contain
2273 * an inline tag, such as in comments or in free-form text arguments
2274 * to non-inline tags.
2275 *
2276 * @param holderTag specific tag where comment resides
2277 * @param doc specific doc where comment resides
2278 * @param tags array of text tags and inline tags (often alternating)
2279 * present in the text of interest for this doc
2280 * @param isFirstSentence true if text is first sentence
2281 */
2282 public String commentTagsToString(Tag holderTag, Doc doc, Tag[] tags,
2283 boolean isFirstSentence) {
2284 StringBuilder result = new StringBuilder();
2285 boolean textTagChange = false;
2286 // Array of all possible inline tags for this javadoc run
2287 configuration.tagletManager.checkTags(doc, tags, true);
2288 for (int i = 0; i < tags.length; i++) {
2289 Tag tagelem = tags[i];
2290 String tagName = tagelem.name();
2291 if (tagelem instanceof SeeTag) {
2292 result.append(seeTagToString((SeeTag)tagelem));
2293 } else if (! tagName.equals("Text")) {
2294 int originalLength = result.length();
2295 TagletOutput output = TagletWriter.getInlineTagOuput(
2296 configuration.tagletManager, holderTag,
2297 tagelem, getTagletWriterInstance(isFirstSentence));
2298 result.append(output == null ? "" : output.toString());
2299 if (originalLength == 0 && isFirstSentence && tagelem.name().equals("@inheritDoc") && result.length() > 0) {
2300 break;
2301 } else if (configuration.docrootparent.length() > 0 &&
2302 tagelem.name().equals("@docRoot") &&
2303 ((tags[i + 1]).text()).startsWith("/..")) {
2304 //If Xdocrootparent switch ON, set the flag to remove the /.. occurance after
2305 //{@docRoot} tag in the very next Text tag.
2306 textTagChange = true;
2307 continue;
2308 } else {
2309 continue;
2310 }
2311 } else {
2312 String text = tagelem.text();
2313 //If Xdocrootparent switch ON, remove the /.. occurance after {@docRoot} tag.
2314 if (textTagChange) {
2315 text = text.replaceFirst("/..", "");
2316 textTagChange = false;
2317 }
2318 //This is just a regular text tag. The text may contain html links (<a>)
2319 //or inline tag {@docRoot}, which will be handled as special cases.
2320 text = redirectRelativeLinks(tagelem.holder(), text);
2322 // Replace @docRoot only if not represented by an instance of DocRootTaglet,
2323 // that is, only if it was not present in a source file doc comment.
2324 // This happens when inserted by the doclet (a few lines
2325 // above in this method). [It might also happen when passed in on the command
2326 // line as a text argument to an option (like -header).]
2327 text = replaceDocRootDir(text);
2328 if (isFirstSentence) {
2329 text = removeNonInlineHtmlTags(text);
2330 }
2331 StringTokenizer lines = new StringTokenizer(text, "\r\n", true);
2332 StringBuilder textBuff = new StringBuilder();
2333 while (lines.hasMoreTokens()) {
2334 StringBuilder line = new StringBuilder(lines.nextToken());
2335 Util.replaceTabs(configuration.sourcetab, line);
2336 textBuff.append(line.toString());
2337 }
2338 result.append(textBuff);
2339 }
2340 }
2341 return result.toString();
2342 }
2344 /**
2345 * Return true if relative links should not be redirected.
2346 *
2347 * @return Return true if a relative link should not be redirected.
2348 */
2349 private boolean shouldNotRedirectRelativeLinks() {
2350 return this instanceof AnnotationTypeWriter ||
2351 this instanceof ClassWriter ||
2352 this instanceof PackageSummaryWriter;
2353 }
2355 /**
2356 * Suppose a piece of documentation has a relative link. When you copy
2357 * that documetation to another place such as the index or class-use page,
2358 * that relative link will no longer work. We should redirect those links
2359 * so that they will work again.
2360 * <p>
2361 * Here is the algorithm used to fix the link:
2362 * <p>
2363 * {@literal <relative link> => docRoot + <relative path to file> + <relative link> }
2364 * <p>
2365 * For example, suppose com.sun.javadoc.RootDoc has this link:
2366 * {@literal <a href="package-summary.html">The package Page</a> }
2367 * <p>
2368 * If this link appeared in the index, we would redirect
2369 * the link like this:
2370 *
2371 * {@literal <a href="./com/sun/javadoc/package-summary.html">The package Page</a>}
2372 *
2373 * @param doc the Doc object whose documentation is being written.
2374 * @param text the text being written.
2375 *
2376 * @return the text, with all the relative links redirected to work.
2377 */
2378 private String redirectRelativeLinks(Doc doc, String text) {
2379 if (doc == null || shouldNotRedirectRelativeLinks()) {
2380 return text;
2381 }
2383 String redirectPathFromRoot;
2384 if (doc instanceof ClassDoc) {
2385 redirectPathFromRoot = DirectoryManager.getDirectoryPath(((ClassDoc) doc).containingPackage());
2386 } else if (doc instanceof MemberDoc) {
2387 redirectPathFromRoot = DirectoryManager.getDirectoryPath(((MemberDoc) doc).containingPackage());
2388 } else if (doc instanceof PackageDoc) {
2389 redirectPathFromRoot = DirectoryManager.getDirectoryPath((PackageDoc) doc);
2390 } else {
2391 return text;
2392 }
2394 if (! redirectPathFromRoot.endsWith(DirectoryManager.URL_FILE_SEPARATOR)) {
2395 redirectPathFromRoot += DirectoryManager.URL_FILE_SEPARATOR;
2396 }
2398 //Redirect all relative links.
2399 int end, begin = text.toLowerCase().indexOf("<a");
2400 if(begin >= 0){
2401 StringBuilder textBuff = new StringBuilder(text);
2403 while(begin >=0){
2404 if (textBuff.length() > begin + 2 && ! Character.isWhitespace(textBuff.charAt(begin+2))) {
2405 begin = textBuff.toString().toLowerCase().indexOf("<a", begin + 1);
2406 continue;
2407 }
2409 begin = textBuff.indexOf("=", begin) + 1;
2410 end = textBuff.indexOf(">", begin +1);
2411 if(begin == 0){
2412 //Link has no equal symbol.
2413 configuration.root.printWarning(
2414 doc.position(),
2415 configuration.getText("doclet.malformed_html_link_tag", text));
2416 break;
2417 }
2418 if (end == -1) {
2419 //Break without warning. This <a> tag is not necessarily malformed. The text
2420 //might be missing '>' character because the href has an inline tag.
2421 break;
2422 }
2423 if(textBuff.substring(begin, end).indexOf("\"") != -1){
2424 begin = textBuff.indexOf("\"", begin) + 1;
2425 end = textBuff.indexOf("\"", begin +1);
2426 if(begin == 0 || end == -1){
2427 //Link is missing a quote.
2428 break;
2429 }
2430 }
2431 String relativeLink = textBuff.substring(begin, end);
2432 if(!(relativeLink.toLowerCase().startsWith("mailto:") ||
2433 relativeLink.toLowerCase().startsWith("http:") ||
2434 relativeLink.toLowerCase().startsWith("https:") ||
2435 relativeLink.toLowerCase().startsWith("file:"))){
2436 relativeLink = "{@"+(new DocRootTaglet()).getName() + "}"
2437 + redirectPathFromRoot
2438 + relativeLink;
2439 textBuff.replace(begin, end, relativeLink);
2440 }
2441 begin = textBuff.toString().toLowerCase().indexOf("<a", begin + 1);
2442 }
2443 return textBuff.toString();
2444 }
2445 return text;
2446 }
2448 public String removeNonInlineHtmlTags(String text) {
2449 if (text.indexOf('<') < 0) {
2450 return text;
2451 }
2452 String noninlinetags[] = { "<ul>", "</ul>", "<ol>", "</ol>",
2453 "<dl>", "</dl>", "<table>", "</table>",
2454 "<tr>", "</tr>", "<td>", "</td>",
2455 "<th>", "</th>", "<p>", "</p>",
2456 "<li>", "</li>", "<dd>", "</dd>",
2457 "<dir>", "</dir>", "<dt>", "</dt>",
2458 "<h1>", "</h1>", "<h2>", "</h2>",
2459 "<h3>", "</h3>", "<h4>", "</h4>",
2460 "<h5>", "</h5>", "<h6>", "</h6>",
2461 "<pre>", "</pre>", "<menu>", "</menu>",
2462 "<listing>", "</listing>", "<hr>",
2463 "<blockquote>", "</blockquote>",
2464 "<center>", "</center>",
2465 "<UL>", "</UL>", "<OL>", "</OL>",
2466 "<DL>", "</DL>", "<TABLE>", "</TABLE>",
2467 "<TR>", "</TR>", "<TD>", "</TD>",
2468 "<TH>", "</TH>", "<P>", "</P>",
2469 "<LI>", "</LI>", "<DD>", "</DD>",
2470 "<DIR>", "</DIR>", "<DT>", "</DT>",
2471 "<H1>", "</H1>", "<H2>", "</H2>",
2472 "<H3>", "</H3>", "<H4>", "</H4>",
2473 "<H5>", "</H5>", "<H6>", "</H6>",
2474 "<PRE>", "</PRE>", "<MENU>", "</MENU>",
2475 "<LISTING>", "</LISTING>", "<HR>",
2476 "<BLOCKQUOTE>", "</BLOCKQUOTE>",
2477 "<CENTER>", "</CENTER>"
2478 };
2479 for (int i = 0; i < noninlinetags.length; i++) {
2480 text = replace(text, noninlinetags[i], "");
2481 }
2482 return text;
2483 }
2485 public String replace(String text, String tobe, String by) {
2486 while (true) {
2487 int startindex = text.indexOf(tobe);
2488 if (startindex < 0) {
2489 return text;
2490 }
2491 int endindex = startindex + tobe.length();
2492 StringBuilder replaced = new StringBuilder();
2493 if (startindex > 0) {
2494 replaced.append(text.substring(0, startindex));
2495 }
2496 replaced.append(by);
2497 if (text.length() > endindex) {
2498 replaced.append(text.substring(endindex));
2499 }
2500 text = replaced.toString();
2501 }
2502 }
2504 public void printStyleSheetProperties() {
2505 String filename = configuration.stylesheetfile;
2506 if (filename.length() > 0) {
2507 File stylefile = new File(filename);
2508 String parent = stylefile.getParent();
2509 filename = (parent == null)?
2510 filename:
2511 filename.substring(parent.length() + 1);
2512 } else {
2513 filename = "stylesheet.css";
2514 }
2515 filename = relativePath + filename;
2516 link("REL =\"stylesheet\" TYPE=\"text/css\" HREF=\"" +
2517 filename + "\" " + "TITLE=\"Style\"");
2518 }
2520 /**
2521 * Returns a link to the stylesheet file.
2522 *
2523 * @return an HtmlTree for the lINK tag which provides the stylesheet location
2524 */
2525 public HtmlTree getStyleSheetProperties() {
2526 String filename = configuration.stylesheetfile;
2527 if (filename.length() > 0) {
2528 File stylefile = new File(filename);
2529 String parent = stylefile.getParent();
2530 filename = (parent == null)?
2531 filename:
2532 filename.substring(parent.length() + 1);
2533 } else {
2534 filename = "stylesheet.css";
2535 }
2536 filename = relativePath + filename;
2537 HtmlTree link = HtmlTree.LINK("stylesheet", "text/css", filename, "Style");
2538 return link;
2539 }
2541 /**
2542 * According to
2543 * <cite>The Java™ Language Specification</cite>,
2544 * all the outer classes and static nested classes are core classes.
2545 */
2546 public boolean isCoreClass(ClassDoc cd) {
2547 return cd.containingClass() == null || cd.isStatic();
2548 }
2550 /**
2551 * Write the annotatation types for the given packageDoc.
2552 *
2553 * @param packageDoc the package to write annotations for.
2554 */
2555 public void writeAnnotationInfo(PackageDoc packageDoc) {
2556 writeAnnotationInfo(packageDoc, packageDoc.annotations());
2557 }
2559 /**
2560 * Adds the annotatation types for the given packageDoc.
2561 *
2562 * @param packageDoc the package to write annotations for.
2563 * @param htmltree the documentation tree to which the annotation info will be
2564 * added
2565 */
2566 public void addAnnotationInfo(PackageDoc packageDoc, Content htmltree) {
2567 addAnnotationInfo(packageDoc, packageDoc.annotations(), htmltree);
2568 }
2570 /**
2571 * Write the annotatation types for the given doc.
2572 *
2573 * @param doc the doc to write annotations for.
2574 */
2575 public void writeAnnotationInfo(ProgramElementDoc doc) {
2576 writeAnnotationInfo(doc, doc.annotations());
2577 }
2579 /**
2580 * Adds the annotatation types for the given doc.
2581 *
2582 * @param doc the package to write annotations for
2583 * @param htmltree the content tree to which the annotation types will be added
2584 */
2585 public void addAnnotationInfo(ProgramElementDoc doc, Content htmltree) {
2586 addAnnotationInfo(doc, doc.annotations(), htmltree);
2587 }
2589 /**
2590 * Write the annotatation types for the given doc and parameter.
2591 *
2592 * @param indent the number of spaced to indent the parameters.
2593 * @param doc the doc to write annotations for.
2594 * @param param the parameter to write annotations for.
2595 */
2596 public boolean writeAnnotationInfo(int indent, Doc doc, Parameter param) {
2597 return writeAnnotationInfo(indent, doc, param.annotations(), false);
2598 }
2600 /**
2601 * Add the annotatation types for the given doc and parameter.
2602 *
2603 * @param indent the number of spaces to indent the parameters.
2604 * @param doc the doc to write annotations for.
2605 * @param param the parameter to write annotations for.
2606 * @param tree the content tree to which the annotation types will be added
2607 */
2608 public boolean addAnnotationInfo(int indent, Doc doc, Parameter param,
2609 Content tree) {
2610 return addAnnotationInfo(indent, doc, param.annotations(), false, tree);
2611 }
2613 /**
2614 * Write the annotatation types for the given doc.
2615 *
2616 * @param doc the doc to write annotations for.
2617 * @param descList the array of {@link AnnotationDesc}.
2618 */
2619 private void writeAnnotationInfo(Doc doc, AnnotationDesc[] descList) {
2620 writeAnnotationInfo(0, doc, descList, true);
2621 }
2623 /**
2624 * Adds the annotatation types for the given doc.
2625 *
2626 * @param doc the doc to write annotations for.
2627 * @param descList the array of {@link AnnotationDesc}.
2628 * @param htmltree the documentation tree to which the annotation info will be
2629 * added
2630 */
2631 private void addAnnotationInfo(Doc doc, AnnotationDesc[] descList,
2632 Content htmltree) {
2633 addAnnotationInfo(0, doc, descList, true, htmltree);
2634 }
2636 /**
2637 * Write the annotatation types for the given doc.
2638 *
2639 * @param indent the number of extra spaces to indent the annotations.
2640 * @param doc the doc to write annotations for.
2641 * @param descList the array of {@link AnnotationDesc}.
2642 */
2643 private boolean writeAnnotationInfo(int indent, Doc doc, AnnotationDesc[] descList, boolean lineBreak) {
2644 List<String> annotations = getAnnotations(indent, descList, lineBreak);
2645 if (annotations.size() == 0) {
2646 return false;
2647 }
2648 fontNoNewLine("-1");
2649 for (Iterator<String> iter = annotations.iterator(); iter.hasNext();) {
2650 print(iter.next());
2651 }
2652 fontEnd();
2653 return true;
2654 }
2656 /**
2657 * Adds the annotatation types for the given doc.
2658 *
2659 * @param indent the number of extra spaces to indent the annotations.
2660 * @param doc the doc to write annotations for.
2661 * @param descList the array of {@link AnnotationDesc}.
2662 * @param htmltree the documentation tree to which the annotation info will be
2663 * added
2664 */
2665 private boolean addAnnotationInfo(int indent, Doc doc,
2666 AnnotationDesc[] descList, boolean lineBreak, Content htmltree) {
2667 List<String> annotations = getAnnotations(indent, descList, lineBreak);
2668 if (annotations.size() == 0) {
2669 return false;
2670 }
2671 Content annotationContent;
2672 for (Iterator<String> iter = annotations.iterator(); iter.hasNext();) {
2673 annotationContent = new RawHtml(iter.next());
2674 htmltree.addContent(annotationContent);
2675 }
2676 return true;
2677 }
2679 /**
2680 * Return the string representations of the annotation types for
2681 * the given doc.
2682 *
2683 * @param indent the number of extra spaces to indent the annotations.
2684 * @param descList the array of {@link AnnotationDesc}.
2685 * @param linkBreak if true, add new line between each member value.
2686 * @return an array of strings representing the annotations being
2687 * documented.
2688 */
2689 private List<String> getAnnotations(int indent, AnnotationDesc[] descList, boolean linkBreak) {
2690 List<String> results = new ArrayList<String>();
2691 StringBuilder annotation;
2692 for (int i = 0; i < descList.length; i++) {
2693 AnnotationTypeDoc annotationDoc = descList[i].annotationType();
2694 if (! Util.isDocumentedAnnotation(annotationDoc)){
2695 continue;
2696 }
2697 annotation = new StringBuilder();
2698 LinkInfoImpl linkInfo = new LinkInfoImpl(
2699 LinkInfoImpl.CONTEXT_ANNOTATION, annotationDoc);
2700 linkInfo.label = "@" + annotationDoc.name();
2701 annotation.append(getLink(linkInfo));
2702 AnnotationDesc.ElementValuePair[] pairs = descList[i].elementValues();
2703 if (pairs.length > 0) {
2704 annotation.append('(');
2705 for (int j = 0; j < pairs.length; j++) {
2706 if (j > 0) {
2707 annotation.append(",");
2708 if (linkBreak) {
2709 annotation.append(DocletConstants.NL);
2710 int spaces = annotationDoc.name().length() + 2;
2711 for (int k = 0; k < (spaces + indent); k++) {
2712 annotation.append(' ');
2713 }
2714 }
2715 }
2716 annotation.append(getDocLink(LinkInfoImpl.CONTEXT_ANNOTATION,
2717 pairs[j].element(), pairs[j].element().name(), false));
2718 annotation.append('=');
2719 AnnotationValue annotationValue = pairs[j].value();
2720 List<AnnotationValue> annotationTypeValues = new ArrayList<AnnotationValue>();
2721 if (annotationValue.value() instanceof AnnotationValue[]) {
2722 AnnotationValue[] annotationArray =
2723 (AnnotationValue[]) annotationValue.value();
2724 for (int k = 0; k < annotationArray.length; k++) {
2725 annotationTypeValues.add(annotationArray[k]);
2726 }
2727 } else {
2728 annotationTypeValues.add(annotationValue);
2729 }
2730 annotation.append(annotationTypeValues.size() == 1 ? "" : "{");
2731 for (Iterator<AnnotationValue> iter = annotationTypeValues.iterator(); iter.hasNext(); ) {
2732 annotation.append(annotationValueToString(iter.next()));
2733 annotation.append(iter.hasNext() ? "," : "");
2734 }
2735 annotation.append(annotationTypeValues.size() == 1 ? "" : "}");
2736 }
2737 annotation.append(")");
2738 }
2739 annotation.append(linkBreak ? DocletConstants.NL : "");
2740 results.add(annotation.toString());
2741 }
2742 return results;
2743 }
2745 private String annotationValueToString(AnnotationValue annotationValue) {
2746 if (annotationValue.value() instanceof Type) {
2747 Type type = (Type) annotationValue.value();
2748 if (type.asClassDoc() != null) {
2749 LinkInfoImpl linkInfo = new LinkInfoImpl(
2750 LinkInfoImpl.CONTEXT_ANNOTATION, type);
2751 linkInfo.label = (type.asClassDoc().isIncluded() ?
2752 type.typeName() :
2753 type.qualifiedTypeName()) + type.dimension() + ".class";
2754 return getLink(linkInfo);
2755 } else {
2756 return type.typeName() + type.dimension() + ".class";
2757 }
2758 } else if (annotationValue.value() instanceof AnnotationDesc) {
2759 List<String> list = getAnnotations(0,
2760 new AnnotationDesc[]{(AnnotationDesc) annotationValue.value()},
2761 false);
2762 StringBuilder buf = new StringBuilder();
2763 for (String s: list) {
2764 buf.append(s);
2765 }
2766 return buf.toString();
2767 } else if (annotationValue.value() instanceof MemberDoc) {
2768 return getDocLink(LinkInfoImpl.CONTEXT_ANNOTATION,
2769 (MemberDoc) annotationValue.value(),
2770 ((MemberDoc) annotationValue.value()).name(), false);
2771 } else {
2772 return annotationValue.toString();
2773 }
2774 }
2776 /**
2777 * Return the configuation for this doclet.
2778 *
2779 * @return the configuration for this doclet.
2780 */
2781 public Configuration configuration() {
2782 return configuration;
2783 }
2784 }