Tue, 16 Oct 2012 21:03:36 -0700
8000673: remove dead code from HtmlWriter and subtypes
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 * Get the script to show or hide the All classes link.
210 *
211 * @param id id of the element to show or hide
212 * @return a content tree for the script
213 */
214 public Content getAllClassesLinkScript(String id) {
215 HtmlTree script = new HtmlTree(HtmlTag.SCRIPT);
216 script.addAttr(HtmlAttr.TYPE, "text/javascript");
217 String scriptCode = "<!--" + DocletConstants.NL +
218 " allClassesLink = document.getElementById(\"" + id + "\");" + DocletConstants.NL +
219 " if(window==top) {" + DocletConstants.NL +
220 " allClassesLink.style.display = \"block\";" + DocletConstants.NL +
221 " }" + DocletConstants.NL +
222 " else {" + DocletConstants.NL +
223 " allClassesLink.style.display = \"none\";" + DocletConstants.NL +
224 " }" + DocletConstants.NL +
225 " //-->" + DocletConstants.NL;
226 Content scriptContent = new RawHtml(scriptCode);
227 script.addContent(scriptContent);
228 Content div = HtmlTree.DIV(script);
229 return div;
230 }
232 /**
233 * Add method information.
234 *
235 * @param method the method to be documented
236 * @param dl the content tree to which the method information will be added
237 */
238 private void addMethodInfo(MethodDoc method, Content dl) {
239 ClassDoc[] intfacs = method.containingClass().interfaces();
240 MethodDoc overriddenMethod = method.overriddenMethod();
241 // Check whether there is any implementation or overridden info to be
242 // printed. If no overridden or implementation info needs to be
243 // printed, do not print this section.
244 if ((intfacs.length > 0 &&
245 new ImplementedMethods(method, this.configuration).build().length > 0) ||
246 overriddenMethod != null) {
247 MethodWriterImpl.addImplementsInfo(this, method, dl);
248 if (overriddenMethod != null) {
249 MethodWriterImpl.addOverridden(this,
250 method.overriddenType(), overriddenMethod, dl);
251 }
252 }
253 }
255 /**
256 * Adds the tags information.
257 *
258 * @param doc the doc for which the tags will be generated
259 * @param htmltree the documentation tree to which the tags will be added
260 */
261 protected void addTagsInfo(Doc doc, Content htmltree) {
262 if (configuration.nocomment) {
263 return;
264 }
265 Content dl = new HtmlTree(HtmlTag.DL);
266 if (doc instanceof MethodDoc) {
267 addMethodInfo((MethodDoc) doc, dl);
268 }
269 TagletOutputImpl output = new TagletOutputImpl("");
270 TagletWriter.genTagOuput(configuration.tagletManager, doc,
271 configuration.tagletManager.getCustomTags(doc),
272 getTagletWriterInstance(false), output);
273 String outputString = output.toString().trim();
274 if (!outputString.isEmpty()) {
275 Content resultString = new RawHtml(outputString);
276 dl.addContent(resultString);
277 }
278 htmltree.addContent(dl);
279 }
281 /**
282 * Check whether there are any tags for Serialization Overview
283 * section to be printed.
284 *
285 * @param field the FieldDoc object to check for tags.
286 * @return true if there are tags to be printed else return false.
287 */
288 protected boolean hasSerializationOverviewTags(FieldDoc field) {
289 TagletOutputImpl output = new TagletOutputImpl("");
290 TagletWriter.genTagOuput(configuration.tagletManager, field,
291 configuration.tagletManager.getCustomTags(field),
292 getTagletWriterInstance(false), output);
293 return (!output.toString().trim().isEmpty());
294 }
296 /**
297 * Returns a TagletWriter that knows how to write HTML.
298 *
299 * @return a TagletWriter that knows how to write HTML.
300 */
301 public TagletWriter getTagletWriterInstance(boolean isFirstSentence) {
302 return new TagletWriterImpl(this, isFirstSentence);
303 }
305 /**
306 * Get Package link, with target frame.
307 *
308 * @param pd The link will be to the "package-summary.html" page for this package
309 * @param target name of the target frame
310 * @param label tag for the link
311 * @return a content for the target package link
312 */
313 public Content getTargetPackageLink(PackageDoc pd, String target,
314 Content label) {
315 return getHyperLink(pathString(pd, "package-summary.html"), "", label, "", target);
316 }
318 /**
319 * Generates the HTML document tree and prints it out.
320 *
321 * @param metakeywords Array of String keywords for META tag. Each element
322 * of the array is assigned to a separate META tag.
323 * Pass in null for no array
324 * @param includeScript true if printing windowtitle script
325 * false for files that appear in the left-hand frames
326 * @param body the body htmltree to be included in the document
327 */
328 public void printHtmlDocument(String[] metakeywords, boolean includeScript,
329 Content body) throws IOException {
330 Content htmlDocType = DocType.Transitional();
331 Content htmlComment = new Comment(configuration.getText("doclet.New_Page"));
332 Content head = new HtmlTree(HtmlTag.HEAD);
333 if (!configuration.notimestamp) {
334 Content headComment = new Comment(getGeneratedByString());
335 head.addContent(headComment);
336 }
337 if (configuration.charset.length() > 0) {
338 Content meta = HtmlTree.META("Content-Type", "text/html",
339 configuration.charset);
340 head.addContent(meta);
341 }
342 head.addContent(getTitle());
343 if (!configuration.notimestamp) {
344 SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
345 Content meta = HtmlTree.META("date", dateFormat.format(new Date()));
346 head.addContent(meta);
347 }
348 if (metakeywords != null) {
349 for (int i=0; i < metakeywords.length; i++) {
350 Content meta = HtmlTree.META("keywords", metakeywords[i]);
351 head.addContent(meta);
352 }
353 }
354 head.addContent(getStyleSheetProperties());
355 Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(),
356 head, body);
357 Content htmlDocument = new HtmlDocument(htmlDocType,
358 htmlComment, htmlTree);
359 write(htmlDocument);
360 }
362 /**
363 * Get the window title.
364 *
365 * @param title the title string to construct the complete window title
366 * @return the window title string
367 */
368 public String getWindowTitle(String title) {
369 if (configuration.windowtitle.length() > 0) {
370 title += " (" + configuration.windowtitle + ")";
371 }
372 return title;
373 }
375 /**
376 * Get user specified header and the footer.
377 *
378 * @param header if true print the user provided header else print the
379 * user provided footer.
380 */
381 public Content getUserHeaderFooter(boolean header) {
382 String content;
383 if (header) {
384 content = replaceDocRootDir(configuration.header);
385 } else {
386 if (configuration.footer.length() != 0) {
387 content = replaceDocRootDir(configuration.footer);
388 } else {
389 content = replaceDocRootDir(configuration.header);
390 }
391 }
392 Content rawContent = new RawHtml(content);
393 Content em = HtmlTree.EM(rawContent);
394 return em;
395 }
397 /**
398 * Adds the user specified top.
399 *
400 * @param body the content tree to which user specified top will be added
401 */
402 public void addTop(Content body) {
403 Content top = new RawHtml(replaceDocRootDir(configuration.top));
404 body.addContent(top);
405 }
407 /**
408 * Adds the user specified bottom.
409 *
410 * @param body the content tree to which user specified bottom will be added
411 */
412 public void addBottom(Content body) {
413 Content bottom = new RawHtml(replaceDocRootDir(configuration.bottom));
414 Content small = HtmlTree.SMALL(bottom);
415 Content p = HtmlTree.P(HtmlStyle.legalCopy, small);
416 body.addContent(p);
417 }
419 /**
420 * Adds the navigation bar for the Html page at the top and and the bottom.
421 *
422 * @param header If true print navigation bar at the top of the page else
423 * @param body the HtmlTree to which the nav links will be added
424 */
425 protected void addNavLinks(boolean header, Content body) {
426 if (!configuration.nonavbar) {
427 String allClassesId = "allclasses_";
428 HtmlTree navDiv = new HtmlTree(HtmlTag.DIV);
429 if (header) {
430 body.addContent(HtmlConstants.START_OF_TOP_NAVBAR);
431 navDiv.addStyle(HtmlStyle.topNav);
432 allClassesId += "navbar_top";
433 Content a = getMarkerAnchor("navbar_top");
434 navDiv.addContent(a);
435 Content skipLinkContent = getHyperLink("",
436 "skip-navbar_top", HtmlTree.EMPTY, configuration.getText(
437 "doclet.Skip_navigation_links"), "");
438 navDiv.addContent(skipLinkContent);
439 } else {
440 body.addContent(HtmlConstants.START_OF_BOTTOM_NAVBAR);
441 navDiv.addStyle(HtmlStyle.bottomNav);
442 allClassesId += "navbar_bottom";
443 Content a = getMarkerAnchor("navbar_bottom");
444 navDiv.addContent(a);
445 Content skipLinkContent = getHyperLink("",
446 "skip-navbar_bottom", HtmlTree.EMPTY, configuration.getText(
447 "doclet.Skip_navigation_links"), "");
448 navDiv.addContent(skipLinkContent);
449 }
450 if (header) {
451 navDiv.addContent(getMarkerAnchor("navbar_top_firstrow"));
452 } else {
453 navDiv.addContent(getMarkerAnchor("navbar_bottom_firstrow"));
454 }
455 HtmlTree navList = new HtmlTree(HtmlTag.UL);
456 navList.addStyle(HtmlStyle.navList);
457 navList.addAttr(HtmlAttr.TITLE, "Navigation");
458 if (configuration.createoverview) {
459 navList.addContent(getNavLinkContents());
460 }
461 if (configuration.packages.length == 1) {
462 navList.addContent(getNavLinkPackage(configuration.packages[0]));
463 } else if (configuration.packages.length > 1) {
464 navList.addContent(getNavLinkPackage());
465 }
466 navList.addContent(getNavLinkClass());
467 if(configuration.classuse) {
468 navList.addContent(getNavLinkClassUse());
469 }
470 if(configuration.createtree) {
471 navList.addContent(getNavLinkTree());
472 }
473 if(!(configuration.nodeprecated ||
474 configuration.nodeprecatedlist)) {
475 navList.addContent(getNavLinkDeprecated());
476 }
477 if(configuration.createindex) {
478 navList.addContent(getNavLinkIndex());
479 }
480 if (!configuration.nohelp) {
481 navList.addContent(getNavLinkHelp());
482 }
483 navDiv.addContent(navList);
484 Content aboutDiv = HtmlTree.DIV(HtmlStyle.aboutLanguage, getUserHeaderFooter(header));
485 navDiv.addContent(aboutDiv);
486 body.addContent(navDiv);
487 Content ulNav = HtmlTree.UL(HtmlStyle.navList, getNavLinkPrevious());
488 ulNav.addContent(getNavLinkNext());
489 Content subDiv = HtmlTree.DIV(HtmlStyle.subNav, ulNav);
490 Content ulFrames = HtmlTree.UL(HtmlStyle.navList, getNavShowLists());
491 ulFrames.addContent(getNavHideLists(filename));
492 subDiv.addContent(ulFrames);
493 HtmlTree ulAllClasses = HtmlTree.UL(HtmlStyle.navList, getNavLinkClassIndex());
494 ulAllClasses.addAttr(HtmlAttr.ID, allClassesId.toString());
495 subDiv.addContent(ulAllClasses);
496 subDiv.addContent(getAllClassesLinkScript(allClassesId.toString()));
497 addSummaryDetailLinks(subDiv);
498 if (header) {
499 subDiv.addContent(getMarkerAnchor("skip-navbar_top"));
500 body.addContent(subDiv);
501 body.addContent(HtmlConstants.END_OF_TOP_NAVBAR);
502 } else {
503 subDiv.addContent(getMarkerAnchor("skip-navbar_bottom"));
504 body.addContent(subDiv);
505 body.addContent(HtmlConstants.END_OF_BOTTOM_NAVBAR);
506 }
507 }
508 }
510 /**
511 * Get the word "NEXT" to indicate that no link is available. Override
512 * this method to customize next link.
513 *
514 * @return a content tree for the link
515 */
516 protected Content getNavLinkNext() {
517 return getNavLinkNext(null);
518 }
520 /**
521 * Get the word "PREV" to indicate that no link is available. Override
522 * this method to customize prev link.
523 *
524 * @return a content tree for the link
525 */
526 protected Content getNavLinkPrevious() {
527 return getNavLinkPrevious(null);
528 }
530 /**
531 * Do nothing. This is the default method.
532 */
533 protected void addSummaryDetailLinks(Content navDiv) {
534 }
536 /**
537 * Get link to the "overview-summary.html" page.
538 *
539 * @return a content tree for the link
540 */
541 protected Content getNavLinkContents() {
542 Content linkContent = getHyperLink(relativePath +
543 "overview-summary.html", "", overviewLabel, "", "");
544 Content li = HtmlTree.LI(linkContent);
545 return li;
546 }
548 /**
549 * Get link to the "package-summary.html" page for the package passed.
550 *
551 * @param pkg Package to which link will be generated
552 * @return a content tree for the link
553 */
554 protected Content getNavLinkPackage(PackageDoc pkg) {
555 Content linkContent = getPackageLink(pkg,
556 packageLabel);
557 Content li = HtmlTree.LI(linkContent);
558 return li;
559 }
561 /**
562 * Get the word "Package" , to indicate that link is not available here.
563 *
564 * @return a content tree for the link
565 */
566 protected Content getNavLinkPackage() {
567 Content li = HtmlTree.LI(packageLabel);
568 return li;
569 }
571 /**
572 * Get the word "Use", to indicate that link is not available.
573 *
574 * @return a content tree for the link
575 */
576 protected Content getNavLinkClassUse() {
577 Content li = HtmlTree.LI(useLabel);
578 return li;
579 }
581 /**
582 * Get link for previous file.
583 *
584 * @param prev File name for the prev link
585 * @return a content tree for the link
586 */
587 public Content getNavLinkPrevious(String prev) {
588 Content li;
589 if (prev != null) {
590 li = HtmlTree.LI(getHyperLink(prev, "", prevLabel, "", ""));
591 }
592 else
593 li = HtmlTree.LI(prevLabel);
594 return li;
595 }
597 /**
598 * Get link for next file. If next is null, just print the label
599 * without linking it anywhere.
600 *
601 * @param next File name for the next link
602 * @return a content tree for the link
603 */
604 public Content getNavLinkNext(String next) {
605 Content li;
606 if (next != null) {
607 li = HtmlTree.LI(getHyperLink(next, "", nextLabel, "", ""));
608 }
609 else
610 li = HtmlTree.LI(nextLabel);
611 return li;
612 }
614 /**
615 * Get "FRAMES" link, to switch to the frame version of the output.
616 *
617 * @param link File to be linked, "index.html"
618 * @return a content tree for the link
619 */
620 protected Content getNavShowLists(String link) {
621 Content framesContent = getHyperLink(link + "?" + path +
622 filename, "", framesLabel, "", "_top");
623 Content li = HtmlTree.LI(framesContent);
624 return li;
625 }
627 /**
628 * Get "FRAMES" link, to switch to the frame version of the output.
629 *
630 * @return a content tree for the link
631 */
632 protected Content getNavShowLists() {
633 return getNavShowLists(relativePath + "index.html");
634 }
636 /**
637 * Get "NO FRAMES" link, to switch to the non-frame version of the output.
638 *
639 * @param link File to be linked
640 * @return a content tree for the link
641 */
642 protected Content getNavHideLists(String link) {
643 Content noFramesContent = getHyperLink(link, "", noframesLabel, "", "_top");
644 Content li = HtmlTree.LI(noFramesContent);
645 return li;
646 }
648 /**
649 * Get "Tree" link in the navigation bar. If there is only one package
650 * specified on the command line, then the "Tree" link will be to the
651 * only "package-tree.html" file otherwise it will be to the
652 * "overview-tree.html" file.
653 *
654 * @return a content tree for the link
655 */
656 protected Content getNavLinkTree() {
657 Content treeLinkContent;
658 PackageDoc[] packages = configuration.root.specifiedPackages();
659 if (packages.length == 1 && configuration.root.specifiedClasses().length == 0) {
660 treeLinkContent = getHyperLink(pathString(packages[0],
661 "package-tree.html"), "", treeLabel,
662 "", "");
663 } else {
664 treeLinkContent = getHyperLink(relativePath + "overview-tree.html",
665 "", treeLabel, "", "");
666 }
667 Content li = HtmlTree.LI(treeLinkContent);
668 return li;
669 }
671 /**
672 * Get the overview tree link for the main tree.
673 *
674 * @param label the label for the link
675 * @return a content tree for the link
676 */
677 protected Content getNavLinkMainTree(String label) {
678 Content mainTreeContent = getHyperLink(relativePath + "overview-tree.html",
679 new StringContent(label));
680 Content li = HtmlTree.LI(mainTreeContent);
681 return li;
682 }
684 /**
685 * Get the word "Class", to indicate that class link is not available.
686 *
687 * @return a content tree for the link
688 */
689 protected Content getNavLinkClass() {
690 Content li = HtmlTree.LI(classLabel);
691 return li;
692 }
694 /**
695 * Get "Deprecated" API link in the navigation bar.
696 *
697 * @return a content tree for the link
698 */
699 protected Content getNavLinkDeprecated() {
700 Content linkContent = getHyperLink(relativePath +
701 "deprecated-list.html", "", deprecatedLabel, "", "");
702 Content li = HtmlTree.LI(linkContent);
703 return li;
704 }
706 /**
707 * Get link for generated index. If the user has used "-splitindex"
708 * command line option, then link to file "index-files/index-1.html" is
709 * generated otherwise link to file "index-all.html" is generated.
710 *
711 * @return a content tree for the link
712 */
713 protected Content getNavLinkClassIndex() {
714 Content allClassesContent = getHyperLink(relativePath +
715 AllClassesFrameWriter.OUTPUT_FILE_NAME_NOFRAMES, "",
716 allclassesLabel, "", "");
717 Content li = HtmlTree.LI(allClassesContent);
718 return li;
719 }
721 /**
722 * Get link for generated class index.
723 *
724 * @return a content tree for the link
725 */
726 protected Content getNavLinkIndex() {
727 Content linkContent = getHyperLink(relativePath +(configuration.splitindex?
728 DirectoryManager.getPath("index-files") + fileseparator: "") +
729 (configuration.splitindex?"index-1.html" : "index-all.html"), "",
730 indexLabel, "", "");
731 Content li = HtmlTree.LI(linkContent);
732 return li;
733 }
735 /**
736 * Get help file link. If user has provided a help file, then generate a
737 * link to the user given file, which is already copied to current or
738 * destination directory.
739 *
740 * @return a content tree for the link
741 */
742 protected Content getNavLinkHelp() {
743 String helpfilenm = configuration.helpfile;
744 if (helpfilenm.equals("")) {
745 helpfilenm = "help-doc.html";
746 } else {
747 int lastsep;
748 if ((lastsep = helpfilenm.lastIndexOf(File.separatorChar)) != -1) {
749 helpfilenm = helpfilenm.substring(lastsep + 1);
750 }
751 }
752 Content linkContent = getHyperLink(relativePath + helpfilenm, "",
753 helpLabel, "", "");
754 Content li = HtmlTree.LI(linkContent);
755 return li;
756 }
758 /**
759 * Get summary table header.
760 *
761 * @param header the header for the table
762 * @param scope the scope of the headers
763 * @return a content tree for the header
764 */
765 public Content getSummaryTableHeader(String[] header, String scope) {
766 Content tr = new HtmlTree(HtmlTag.TR);
767 int size = header.length;
768 Content tableHeader;
769 if (size == 1) {
770 tableHeader = new StringContent(header[0]);
771 tr.addContent(HtmlTree.TH(HtmlStyle.colOne, scope, tableHeader));
772 return tr;
773 }
774 for (int i = 0; i < size; i++) {
775 tableHeader = new StringContent(header[i]);
776 if(i == 0)
777 tr.addContent(HtmlTree.TH(HtmlStyle.colFirst, scope, tableHeader));
778 else if(i == (size - 1))
779 tr.addContent(HtmlTree.TH(HtmlStyle.colLast, scope, tableHeader));
780 else
781 tr.addContent(HtmlTree.TH(scope, tableHeader));
782 }
783 return tr;
784 }
786 /**
787 * Get table caption.
788 *
789 * @param rawText the caption for the table which could be raw Html
790 * @return a content tree for the caption
791 */
792 public Content getTableCaption(String rawText) {
793 Content title = new RawHtml(rawText);
794 Content captionSpan = HtmlTree.SPAN(title);
795 Content space = getSpace();
796 Content tabSpan = HtmlTree.SPAN(HtmlStyle.tabEnd, space);
797 Content caption = HtmlTree.CAPTION(captionSpan);
798 caption.addContent(tabSpan);
799 return caption;
800 }
802 /**
803 * Get the marker anchor which will be added to the documentation tree.
804 *
805 * @param anchorName the anchor name attribute
806 * @return a content tree for the marker anchor
807 */
808 public Content getMarkerAnchor(String anchorName) {
809 return getMarkerAnchor(anchorName, null);
810 }
812 /**
813 * Get the marker anchor which will be added to the documentation tree.
814 *
815 * @param anchorName the anchor name attribute
816 * @param anchorContent the content that should be added to the anchor
817 * @return a content tree for the marker anchor
818 */
819 public Content getMarkerAnchor(String anchorName, Content anchorContent) {
820 if (anchorContent == null)
821 anchorContent = new Comment(" ");
822 Content markerAnchor = HtmlTree.A_NAME(anchorName, anchorContent);
823 return markerAnchor;
824 }
826 /**
827 * Returns a packagename content.
828 *
829 * @param packageDoc the package to check
830 * @return package name content
831 */
832 public Content getPackageName(PackageDoc packageDoc) {
833 return packageDoc == null || packageDoc.name().length() == 0 ?
834 defaultPackageLabel :
835 getPackageLabel(packageDoc.name());
836 }
838 /**
839 * Returns a package name label.
840 *
841 * @param packageName the package name
842 * @return the package name content
843 */
844 public Content getPackageLabel(String packageName) {
845 return new StringContent(packageName);
846 }
848 /**
849 * Add package deprecation information to the documentation tree
850 *
851 * @param deprPkgs list of deprecated packages
852 * @param headingKey the caption for the deprecated package table
853 * @param tableSummary the summary for the deprecated package table
854 * @param tableHeader table headers for the deprecated package table
855 * @param contentTree the content tree to which the deprecated package table will be added
856 */
857 protected void addPackageDeprecatedAPI(List<Doc> deprPkgs, String headingKey,
858 String tableSummary, String[] tableHeader, Content contentTree) {
859 if (deprPkgs.size() > 0) {
860 Content table = HtmlTree.TABLE(0, 3, 0, tableSummary,
861 getTableCaption(configuration().getText(headingKey)));
862 table.addContent(getSummaryTableHeader(tableHeader, "col"));
863 Content tbody = new HtmlTree(HtmlTag.TBODY);
864 for (int i = 0; i < deprPkgs.size(); i++) {
865 PackageDoc pkg = (PackageDoc) deprPkgs.get(i);
866 HtmlTree td = HtmlTree.TD(HtmlStyle.colOne,
867 getPackageLink(pkg, getPackageName(pkg)));
868 if (pkg.tags("deprecated").length > 0) {
869 addInlineDeprecatedComment(pkg, pkg.tags("deprecated")[0], td);
870 }
871 HtmlTree tr = HtmlTree.TR(td);
872 if (i % 2 == 0) {
873 tr.addStyle(HtmlStyle.altColor);
874 } else {
875 tr.addStyle(HtmlStyle.rowColor);
876 }
877 tbody.addContent(tr);
878 }
879 table.addContent(tbody);
880 Content li = HtmlTree.LI(HtmlStyle.blockList, table);
881 Content ul = HtmlTree.UL(HtmlStyle.blockList, li);
882 contentTree.addContent(ul);
883 }
884 }
886 /**
887 * Return path to the class page for a classdoc. For example, the class
888 * name is "java.lang.Object" and if the current file getting generated is
889 * "java/io/File.html", then the path string to the class, returned is
890 * "../../java/lang.Object.html".
891 *
892 * @param cd Class to which the path is requested.
893 */
894 protected String pathToClass(ClassDoc cd) {
895 return pathString(cd.containingPackage(), cd.name() + ".html");
896 }
898 /**
899 * Return the path to the class page for a classdoc. Works same as
900 * {@link #pathToClass(ClassDoc)}.
901 *
902 * @param cd Class to which the path is requested.
903 * @param name Name of the file(doesn't include path).
904 */
905 protected String pathString(ClassDoc cd, String name) {
906 return pathString(cd.containingPackage(), name);
907 }
909 /**
910 * Return path to the given file name in the given package. So if the name
911 * passed is "Object.html" and the name of the package is "java.lang", and
912 * if the relative path is "../.." then returned string will be
913 * "../../java/lang/Object.html"
914 *
915 * @param pd Package in which the file name is assumed to be.
916 * @param name File name, to which path string is.
917 */
918 protected String pathString(PackageDoc pd, String name) {
919 StringBuilder buf = new StringBuilder(relativePath);
920 buf.append(DirectoryManager.getPathToPackage(pd, name));
921 return buf.toString();
922 }
924 /**
925 * Return the link to the given package.
926 *
927 * @param pkg the package to link to.
928 * @param label the label for the link.
929 * @param isStrong true if the label should be strong.
930 * @return the link to the given package.
931 */
932 public String getPackageLinkString(PackageDoc pkg, String label,
933 boolean isStrong) {
934 return getPackageLinkString(pkg, label, isStrong, "");
935 }
937 /**
938 * Return the link to the given package.
939 *
940 * @param pkg the package to link to.
941 * @param label the label for the link.
942 * @param isStrong true if the label should be strong.
943 * @param style the font of the package link label.
944 * @return the link to the given package.
945 */
946 public String getPackageLinkString(PackageDoc pkg, String label, boolean isStrong,
947 String style) {
948 boolean included = pkg != null && pkg.isIncluded();
949 if (! included) {
950 PackageDoc[] packages = configuration.packages;
951 for (int i = 0; i < packages.length; i++) {
952 if (packages[i].equals(pkg)) {
953 included = true;
954 break;
955 }
956 }
957 }
958 if (included || pkg == null) {
959 return getHyperLinkString(pathString(pkg, "package-summary.html"),
960 "", label, isStrong, style);
961 } else {
962 String crossPkgLink = getCrossPackageLink(Util.getPackageName(pkg));
963 if (crossPkgLink != null) {
964 return getHyperLinkString(crossPkgLink, "", label, isStrong, style);
965 } else {
966 return label;
967 }
968 }
969 }
971 /**
972 * Return the link to the given package.
973 *
974 * @param pkg the package to link to.
975 * @param label the label for the link.
976 * @return a content tree for the package link.
977 */
978 public Content getPackageLink(PackageDoc pkg, Content label) {
979 boolean included = pkg != null && pkg.isIncluded();
980 if (! included) {
981 PackageDoc[] packages = configuration.packages;
982 for (int i = 0; i < packages.length; i++) {
983 if (packages[i].equals(pkg)) {
984 included = true;
985 break;
986 }
987 }
988 }
989 if (included || pkg == null) {
990 return getHyperLink(pathString(pkg, "package-summary.html"),
991 "", label);
992 } else {
993 String crossPkgLink = getCrossPackageLink(Util.getPackageName(pkg));
994 if (crossPkgLink != null) {
995 return getHyperLink(crossPkgLink, "", label);
996 } else {
997 return label;
998 }
999 }
1000 }
1002 public String italicsClassName(ClassDoc cd, boolean qual) {
1003 String name = (qual)? cd.qualifiedName(): cd.name();
1004 return (cd.isInterface())? italicsText(name): name;
1005 }
1007 /**
1008 * Add the link to the content tree.
1009 *
1010 * @param doc program element doc for which the link will be added
1011 * @param label label for the link
1012 * @param htmltree the content tree to which the link will be added
1013 */
1014 public void addSrcLink(ProgramElementDoc doc, Content label, Content htmltree) {
1015 if (doc == null) {
1016 return;
1017 }
1018 ClassDoc cd = doc.containingClass();
1019 if (cd == null) {
1020 //d must be a class doc since in has no containing class.
1021 cd = (ClassDoc) doc;
1022 }
1023 String href = relativePath + DocletConstants.SOURCE_OUTPUT_DIR_NAME
1024 + DirectoryManager.getDirectoryPath(cd.containingPackage())
1025 + cd.name() + ".html#" + SourceToHTMLConverter.getAnchorName(doc);
1026 Content linkContent = getHyperLink(href, "", label, "", "");
1027 htmltree.addContent(linkContent);
1028 }
1030 /**
1031 * Return the link to the given class.
1032 *
1033 * @param linkInfo the information about the link.
1034 *
1035 * @return the link for the given class.
1036 */
1037 public String getLink(LinkInfoImpl linkInfo) {
1038 LinkFactoryImpl factory = new LinkFactoryImpl(this);
1039 String link = ((LinkOutputImpl) factory.getLinkOutput(linkInfo)).toString();
1040 displayLength += linkInfo.displayLength;
1041 return link;
1042 }
1044 /**
1045 * Return the type parameters for the given class.
1046 *
1047 * @param linkInfo the information about the link.
1048 * @return the type for the given class.
1049 */
1050 public String getTypeParameterLinks(LinkInfoImpl linkInfo) {
1051 LinkFactoryImpl factory = new LinkFactoryImpl(this);
1052 return ((LinkOutputImpl)
1053 factory.getTypeParameterLinks(linkInfo, false)).toString();
1054 }
1056 /*************************************************************
1057 * Return a class cross link to external class documentation.
1058 * The name must be fully qualified to determine which package
1059 * the class is in. The -link option does not allow users to
1060 * link to external classes in the "default" package.
1061 *
1062 * @param qualifiedClassName the qualified name of the external class.
1063 * @param refMemName the name of the member being referenced. This should
1064 * be null or empty string if no member is being referenced.
1065 * @param label the label for the external link.
1066 * @param strong true if the link should be strong.
1067 * @param style the style of the link.
1068 * @param code true if the label should be code font.
1069 */
1070 public String getCrossClassLink(String qualifiedClassName, String refMemName,
1071 String label, boolean strong, String style,
1072 boolean code) {
1073 String className = "",
1074 packageName = qualifiedClassName == null ? "" : qualifiedClassName;
1075 int periodIndex;
1076 while((periodIndex = packageName.lastIndexOf('.')) != -1) {
1077 className = packageName.substring(periodIndex + 1, packageName.length()) +
1078 (className.length() > 0 ? "." + className : "");
1079 String defaultLabel = code ? codeText(className) : className;
1080 packageName = packageName.substring(0, periodIndex);
1081 if (getCrossPackageLink(packageName) != null) {
1082 //The package exists in external documentation, so link to the external
1083 //class (assuming that it exists). This is definitely a limitation of
1084 //the -link option. There are ways to determine if an external package
1085 //exists, but no way to determine if the external class exists. We just
1086 //have to assume that it does.
1087 return getHyperLinkString(
1088 configuration.extern.getExternalLink(packageName, relativePath,
1089 className + ".html?is-external=true"),
1090 refMemName == null ? "" : refMemName,
1091 label == null || label.length() == 0 ? defaultLabel : label,
1092 strong, style,
1093 configuration.getText("doclet.Href_Class_Or_Interface_Title", packageName),
1094 "");
1095 }
1096 }
1097 return null;
1098 }
1100 public boolean isClassLinkable(ClassDoc cd) {
1101 if (cd.isIncluded()) {
1102 return configuration.isGeneratedDoc(cd);
1103 }
1104 return configuration.extern.isExternal(cd);
1105 }
1107 public String getCrossPackageLink(String pkgName) {
1108 return configuration.extern.getExternalLink(pkgName, relativePath,
1109 "package-summary.html?is-external=true");
1110 }
1112 /**
1113 * Get the class link.
1114 *
1115 * @param context the id of the context where the link will be added
1116 * @param cd the class doc to link to
1117 * @return a content tree for the link
1118 */
1119 public Content getQualifiedClassLink(int context, ClassDoc cd) {
1120 return new RawHtml(getLink(new LinkInfoImpl(context, cd,
1121 configuration.getClassName(cd), "")));
1122 }
1124 /**
1125 * Add the class link.
1126 *
1127 * @param context the id of the context where the link will be added
1128 * @param cd the class doc to link to
1129 * @param contentTree the content tree to which the link will be added
1130 */
1131 public void addPreQualifiedClassLink(int context, ClassDoc cd, Content contentTree) {
1132 addPreQualifiedClassLink(context, cd, false, contentTree);
1133 }
1135 /**
1136 * Retrieve the class link with the package portion of the label in
1137 * plain text. If the qualifier is excluded, it willnot be included in the
1138 * link label.
1139 *
1140 * @param cd the class to link to.
1141 * @param isStrong true if the link should be strong.
1142 * @return the link with the package portion of the label in plain text.
1143 */
1144 public String getPreQualifiedClassLink(int context,
1145 ClassDoc cd, boolean isStrong) {
1146 String classlink = "";
1147 PackageDoc pd = cd.containingPackage();
1148 if(pd != null && ! configuration.shouldExcludeQualifier(pd.name())) {
1149 classlink = getPkgName(cd);
1150 }
1151 classlink += getLink(new LinkInfoImpl(context, cd, cd.name(), isStrong));
1152 return classlink;
1153 }
1155 /**
1156 * Add the class link with the package portion of the label in
1157 * plain text. If the qualifier is excluded, it will not be included in the
1158 * link label.
1159 *
1160 * @param context the id of the context where the link will be added
1161 * @param cd the class to link to
1162 * @param isStrong true if the link should be strong
1163 * @param contentTree the content tree to which the link with be added
1164 */
1165 public void addPreQualifiedClassLink(int context,
1166 ClassDoc cd, boolean isStrong, Content contentTree) {
1167 PackageDoc pd = cd.containingPackage();
1168 if(pd != null && ! configuration.shouldExcludeQualifier(pd.name())) {
1169 contentTree.addContent(getPkgName(cd));
1170 }
1171 contentTree.addContent(new RawHtml(getLink(new LinkInfoImpl(
1172 context, cd, cd.name(), isStrong))));
1173 }
1175 /**
1176 * Add the class link, with only class name as the strong link and prefixing
1177 * plain package name.
1178 *
1179 * @param context the id of the context where the link will be added
1180 * @param cd the class to link to
1181 * @param contentTree the content tree to which the link with be added
1182 */
1183 public void addPreQualifiedStrongClassLink(int context, ClassDoc cd, Content contentTree) {
1184 addPreQualifiedClassLink(context, cd, true, contentTree);
1185 }
1187 /**
1188 * Get the link for the given member.
1189 *
1190 * @param context the id of the context where the link will be added
1191 * @param doc the member being linked to
1192 * @param label the label for the link
1193 * @return a content tree for the doc link
1194 */
1195 public Content getDocLink(int context, MemberDoc doc, String label) {
1196 return getDocLink(context, doc.containingClass(), doc, label);
1197 }
1199 /**
1200 * Return the link for the given member.
1201 *
1202 * @param context the id of the context where the link will be printed.
1203 * @param doc the member being linked to.
1204 * @param label the label for the link.
1205 * @param strong true if the link should be strong.
1206 * @return the link for the given member.
1207 */
1208 public String getDocLink(int context, MemberDoc doc, String label,
1209 boolean strong) {
1210 return getDocLink(context, doc.containingClass(), doc, label, strong);
1211 }
1213 /**
1214 * Return the link for the given member.
1215 *
1216 * @param context the id of the context where the link will be printed.
1217 * @param classDoc the classDoc that we should link to. This is not
1218 * necessarily equal to doc.containingClass(). We may be
1219 * inheriting comments.
1220 * @param doc the member being linked to.
1221 * @param label the label for the link.
1222 * @param strong true if the link should be strong.
1223 * @return the link for the given member.
1224 */
1225 public String getDocLink(int context, ClassDoc classDoc, MemberDoc doc,
1226 String label, boolean strong) {
1227 if (! (doc.isIncluded() ||
1228 Util.isLinkable(classDoc, configuration()))) {
1229 return label;
1230 } else if (doc instanceof ExecutableMemberDoc) {
1231 ExecutableMemberDoc emd = (ExecutableMemberDoc)doc;
1232 return getLink(new LinkInfoImpl(context, classDoc,
1233 getAnchor(emd), label, strong));
1234 } else if (doc instanceof MemberDoc) {
1235 return getLink(new LinkInfoImpl(context, classDoc,
1236 doc.name(), label, strong));
1237 } else {
1238 return label;
1239 }
1240 }
1242 /**
1243 * Return the link for the given member.
1244 *
1245 * @param context the id of the context where the link will be added
1246 * @param classDoc the classDoc that we should link to. This is not
1247 * necessarily equal to doc.containingClass(). We may be
1248 * inheriting comments
1249 * @param doc the member being linked to
1250 * @param label the label for the link
1251 * @return the link for the given member
1252 */
1253 public Content getDocLink(int context, ClassDoc classDoc, MemberDoc doc,
1254 String label) {
1255 if (! (doc.isIncluded() ||
1256 Util.isLinkable(classDoc, configuration()))) {
1257 return new StringContent(label);
1258 } else if (doc instanceof ExecutableMemberDoc) {
1259 ExecutableMemberDoc emd = (ExecutableMemberDoc)doc;
1260 return new RawHtml(getLink(new LinkInfoImpl(context, classDoc,
1261 getAnchor(emd), label, false)));
1262 } else if (doc instanceof MemberDoc) {
1263 return new RawHtml(getLink(new LinkInfoImpl(context, classDoc,
1264 doc.name(), label, false)));
1265 } else {
1266 return new StringContent(label);
1267 }
1268 }
1270 public String getAnchor(ExecutableMemberDoc emd) {
1271 StringBuilder signature = new StringBuilder(emd.signature());
1272 StringBuilder signatureParsed = new StringBuilder();
1273 int counter = 0;
1274 for (int i = 0; i < signature.length(); i++) {
1275 char c = signature.charAt(i);
1276 if (c == '<') {
1277 counter++;
1278 } else if (c == '>') {
1279 counter--;
1280 } else if (counter == 0) {
1281 signatureParsed.append(c);
1282 }
1283 }
1284 return emd.name() + signatureParsed.toString();
1285 }
1287 public String seeTagToString(SeeTag see) {
1288 String tagName = see.name();
1289 if (! (tagName.startsWith("@link") || tagName.equals("@see"))) {
1290 return "";
1291 }
1293 String seetext = replaceDocRootDir(see.text());
1295 //Check if @see is an href or "string"
1296 if (seetext.startsWith("<") || seetext.startsWith("\"")) {
1297 return seetext;
1298 }
1300 boolean plain = tagName.equalsIgnoreCase("@linkplain");
1301 String label = plainOrCodeText(plain, see.label());
1303 //The text from the @see tag. We will output this text when a label is not specified.
1304 String text = plainOrCodeText(plain, seetext);
1306 ClassDoc refClass = see.referencedClass();
1307 String refClassName = see.referencedClassName();
1308 MemberDoc refMem = see.referencedMember();
1309 String refMemName = see.referencedMemberName();
1311 if (refClass == null) {
1312 //@see is not referencing an included class
1313 PackageDoc refPackage = see.referencedPackage();
1314 if (refPackage != null && refPackage.isIncluded()) {
1315 //@see is referencing an included package
1316 if (label.isEmpty())
1317 label = plainOrCodeText(plain, refPackage.name());
1318 return getPackageLinkString(refPackage, label, false);
1319 } else {
1320 //@see is not referencing an included class or package. Check for cross links.
1321 String classCrossLink, packageCrossLink = getCrossPackageLink(refClassName);
1322 if (packageCrossLink != null) {
1323 //Package cross link found
1324 return getHyperLinkString(packageCrossLink, "",
1325 (label.isEmpty() ? text : label), false);
1326 } else if ((classCrossLink = getCrossClassLink(refClassName,
1327 refMemName, label, false, "", !plain)) != null) {
1328 //Class cross link found (possibly to a member in the class)
1329 return classCrossLink;
1330 } else {
1331 //No cross link found so print warning
1332 configuration.getDocletSpecificMsg().warning(see.position(), "doclet.see.class_or_package_not_found",
1333 tagName, seetext);
1334 return (label.isEmpty() ? text: label);
1335 }
1336 }
1337 } else if (refMemName == null) {
1338 // Must be a class reference since refClass is not null and refMemName is null.
1339 if (label.isEmpty()) {
1340 label = plainOrCodeText(plain, refClass.name());
1341 }
1342 return getLink(new LinkInfoImpl(refClass, label));
1343 } else if (refMem == null) {
1344 // Must be a member reference since refClass is not null and refMemName is not null.
1345 // However, refMem is null, so this referenced member does not exist.
1346 return (label.isEmpty() ? text: label);
1347 } else {
1348 // Must be a member reference since refClass is not null and refMemName is not null.
1349 // refMem is not null, so this @see tag must be referencing a valid member.
1350 ClassDoc containing = refMem.containingClass();
1351 if (see.text().trim().startsWith("#") &&
1352 ! (containing.isPublic() ||
1353 Util.isLinkable(containing, configuration()))) {
1354 // Since the link is relative and the holder is not even being
1355 // documented, this must be an inherited link. Redirect it.
1356 // The current class either overrides the referenced member or
1357 // inherits it automatically.
1358 if (this instanceof ClassWriterImpl) {
1359 containing = ((ClassWriterImpl) this).getClassDoc();
1360 } else if (!containing.isPublic()){
1361 configuration.getDocletSpecificMsg().warning(
1362 see.position(), "doclet.see.class_or_package_not_accessible",
1363 tagName, containing.qualifiedName());
1364 } else {
1365 configuration.getDocletSpecificMsg().warning(
1366 see.position(), "doclet.see.class_or_package_not_found",
1367 tagName, seetext);
1368 }
1369 }
1370 if (configuration.currentcd != containing) {
1371 refMemName = containing.name() + "." + refMemName;
1372 }
1373 if (refMem instanceof ExecutableMemberDoc) {
1374 if (refMemName.indexOf('(') < 0) {
1375 refMemName += ((ExecutableMemberDoc)refMem).signature();
1376 }
1377 }
1379 text = plainOrCodeText(plain, Util.escapeHtmlChars(refMemName));
1381 return getDocLink(LinkInfoImpl.CONTEXT_SEE_TAG, containing,
1382 refMem, (label.isEmpty() ? text: label), false);
1383 }
1384 }
1386 private String plainOrCodeText(boolean plain, String text) {
1387 return (plain || text.isEmpty()) ? text : codeText(text);
1388 }
1390 /**
1391 * Add the inline comment.
1392 *
1393 * @param doc the doc for which the inline comment will be added
1394 * @param tag the inline tag to be added
1395 * @param htmltree the content tree to which the comment will be added
1396 */
1397 public void addInlineComment(Doc doc, Tag tag, Content htmltree) {
1398 addCommentTags(doc, tag.inlineTags(), false, false, htmltree);
1399 }
1401 /**
1402 * Add the inline deprecated comment.
1403 *
1404 * @param doc the doc for which the inline deprecated comment will be added
1405 * @param tag the inline tag to be added
1406 * @param htmltree the content tree to which the comment will be added
1407 */
1408 public void addInlineDeprecatedComment(Doc doc, Tag tag, Content htmltree) {
1409 addCommentTags(doc, tag.inlineTags(), true, false, htmltree);
1410 }
1412 /**
1413 * Adds the summary content.
1414 *
1415 * @param doc the doc for which the summary will be generated
1416 * @param htmltree the documentation tree to which the summary will be added
1417 */
1418 public void addSummaryComment(Doc doc, Content htmltree) {
1419 addSummaryComment(doc, doc.firstSentenceTags(), htmltree);
1420 }
1422 /**
1423 * Adds the summary content.
1424 *
1425 * @param doc the doc for which the summary will be generated
1426 * @param firstSentenceTags the first sentence tags for the doc
1427 * @param htmltree the documentation tree to which the summary will be added
1428 */
1429 public void addSummaryComment(Doc doc, Tag[] firstSentenceTags, Content htmltree) {
1430 addCommentTags(doc, firstSentenceTags, false, true, htmltree);
1431 }
1433 public void addSummaryDeprecatedComment(Doc doc, Tag tag, Content htmltree) {
1434 addCommentTags(doc, tag.firstSentenceTags(), true, true, htmltree);
1435 }
1437 /**
1438 * Adds the inline comment.
1439 *
1440 * @param doc the doc for which the inline comments will be generated
1441 * @param htmltree the documentation tree to which the inline comments will be added
1442 */
1443 public void addInlineComment(Doc doc, Content htmltree) {
1444 addCommentTags(doc, doc.inlineTags(), false, false, htmltree);
1445 }
1447 /**
1448 * Adds the comment tags.
1449 *
1450 * @param doc the doc for which the comment tags will be generated
1451 * @param tags the first sentence tags for the doc
1452 * @param depr true if it is deprecated
1453 * @param first true if the first sentenge tags should be added
1454 * @param htmltree the documentation tree to which the comment tags will be added
1455 */
1456 private void addCommentTags(Doc doc, Tag[] tags, boolean depr,
1457 boolean first, Content htmltree) {
1458 if(configuration.nocomment){
1459 return;
1460 }
1461 Content div;
1462 Content result = new RawHtml(commentTagsToString(null, doc, tags, first));
1463 if (depr) {
1464 Content italic = HtmlTree.I(result);
1465 div = HtmlTree.DIV(HtmlStyle.block, italic);
1466 htmltree.addContent(div);
1467 }
1468 else {
1469 div = HtmlTree.DIV(HtmlStyle.block, result);
1470 htmltree.addContent(div);
1471 }
1472 if (tags.length == 0) {
1473 htmltree.addContent(getSpace());
1474 }
1475 }
1477 /**
1478 * Converts inline tags and text to text strings, expanding the
1479 * inline tags along the way. Called wherever text can contain
1480 * an inline tag, such as in comments or in free-form text arguments
1481 * to non-inline tags.
1482 *
1483 * @param holderTag specific tag where comment resides
1484 * @param doc specific doc where comment resides
1485 * @param tags array of text tags and inline tags (often alternating)
1486 * present in the text of interest for this doc
1487 * @param isFirstSentence true if text is first sentence
1488 */
1489 public String commentTagsToString(Tag holderTag, Doc doc, Tag[] tags,
1490 boolean isFirstSentence) {
1491 StringBuilder result = new StringBuilder();
1492 boolean textTagChange = false;
1493 // Array of all possible inline tags for this javadoc run
1494 configuration.tagletManager.checkTags(doc, tags, true);
1495 for (int i = 0; i < tags.length; i++) {
1496 Tag tagelem = tags[i];
1497 String tagName = tagelem.name();
1498 if (tagelem instanceof SeeTag) {
1499 result.append(seeTagToString((SeeTag)tagelem));
1500 } else if (! tagName.equals("Text")) {
1501 int originalLength = result.length();
1502 TagletOutput output = TagletWriter.getInlineTagOuput(
1503 configuration.tagletManager, holderTag,
1504 tagelem, getTagletWriterInstance(isFirstSentence));
1505 result.append(output == null ? "" : output.toString());
1506 if (originalLength == 0 && isFirstSentence && tagelem.name().equals("@inheritDoc") && result.length() > 0) {
1507 break;
1508 } else if (configuration.docrootparent.length() > 0 &&
1509 tagelem.name().equals("@docRoot") &&
1510 ((tags[i + 1]).text()).startsWith("/..")) {
1511 //If Xdocrootparent switch ON, set the flag to remove the /.. occurance after
1512 //{@docRoot} tag in the very next Text tag.
1513 textTagChange = true;
1514 continue;
1515 } else {
1516 continue;
1517 }
1518 } else {
1519 String text = tagelem.text();
1520 //If Xdocrootparent switch ON, remove the /.. occurance after {@docRoot} tag.
1521 if (textTagChange) {
1522 text = text.replaceFirst("/..", "");
1523 textTagChange = false;
1524 }
1525 //This is just a regular text tag. The text may contain html links (<a>)
1526 //or inline tag {@docRoot}, which will be handled as special cases.
1527 text = redirectRelativeLinks(tagelem.holder(), text);
1529 // Replace @docRoot only if not represented by an instance of DocRootTaglet,
1530 // that is, only if it was not present in a source file doc comment.
1531 // This happens when inserted by the doclet (a few lines
1532 // above in this method). [It might also happen when passed in on the command
1533 // line as a text argument to an option (like -header).]
1534 text = replaceDocRootDir(text);
1535 if (isFirstSentence) {
1536 text = removeNonInlineHtmlTags(text);
1537 }
1538 StringTokenizer lines = new StringTokenizer(text, "\r\n", true);
1539 StringBuilder textBuff = new StringBuilder();
1540 while (lines.hasMoreTokens()) {
1541 StringBuilder line = new StringBuilder(lines.nextToken());
1542 Util.replaceTabs(configuration.sourcetab, line);
1543 textBuff.append(line.toString());
1544 }
1545 result.append(textBuff);
1546 }
1547 }
1548 return result.toString();
1549 }
1551 /**
1552 * Return true if relative links should not be redirected.
1553 *
1554 * @return Return true if a relative link should not be redirected.
1555 */
1556 private boolean shouldNotRedirectRelativeLinks() {
1557 return this instanceof AnnotationTypeWriter ||
1558 this instanceof ClassWriter ||
1559 this instanceof PackageSummaryWriter;
1560 }
1562 /**
1563 * Suppose a piece of documentation has a relative link. When you copy
1564 * that documetation to another place such as the index or class-use page,
1565 * that relative link will no longer work. We should redirect those links
1566 * so that they will work again.
1567 * <p>
1568 * Here is the algorithm used to fix the link:
1569 * <p>
1570 * {@literal <relative link> => docRoot + <relative path to file> + <relative link> }
1571 * <p>
1572 * For example, suppose com.sun.javadoc.RootDoc has this link:
1573 * {@literal <a href="package-summary.html">The package Page</a> }
1574 * <p>
1575 * If this link appeared in the index, we would redirect
1576 * the link like this:
1577 *
1578 * {@literal <a href="./com/sun/javadoc/package-summary.html">The package Page</a>}
1579 *
1580 * @param doc the Doc object whose documentation is being written.
1581 * @param text the text being written.
1582 *
1583 * @return the text, with all the relative links redirected to work.
1584 */
1585 private String redirectRelativeLinks(Doc doc, String text) {
1586 if (doc == null || shouldNotRedirectRelativeLinks()) {
1587 return text;
1588 }
1590 String redirectPathFromRoot;
1591 if (doc instanceof ClassDoc) {
1592 redirectPathFromRoot = DirectoryManager.getDirectoryPath(((ClassDoc) doc).containingPackage());
1593 } else if (doc instanceof MemberDoc) {
1594 redirectPathFromRoot = DirectoryManager.getDirectoryPath(((MemberDoc) doc).containingPackage());
1595 } else if (doc instanceof PackageDoc) {
1596 redirectPathFromRoot = DirectoryManager.getDirectoryPath((PackageDoc) doc);
1597 } else {
1598 return text;
1599 }
1601 if (! redirectPathFromRoot.endsWith(DirectoryManager.URL_FILE_SEPARATOR)) {
1602 redirectPathFromRoot += DirectoryManager.URL_FILE_SEPARATOR;
1603 }
1605 //Redirect all relative links.
1606 int end, begin = text.toLowerCase().indexOf("<a");
1607 if(begin >= 0){
1608 StringBuilder textBuff = new StringBuilder(text);
1610 while(begin >=0){
1611 if (textBuff.length() > begin + 2 && ! Character.isWhitespace(textBuff.charAt(begin+2))) {
1612 begin = textBuff.toString().toLowerCase().indexOf("<a", begin + 1);
1613 continue;
1614 }
1616 begin = textBuff.indexOf("=", begin) + 1;
1617 end = textBuff.indexOf(">", begin +1);
1618 if(begin == 0){
1619 //Link has no equal symbol.
1620 configuration.root.printWarning(
1621 doc.position(),
1622 configuration.getText("doclet.malformed_html_link_tag", text));
1623 break;
1624 }
1625 if (end == -1) {
1626 //Break without warning. This <a> tag is not necessarily malformed. The text
1627 //might be missing '>' character because the href has an inline tag.
1628 break;
1629 }
1630 if(textBuff.substring(begin, end).indexOf("\"") != -1){
1631 begin = textBuff.indexOf("\"", begin) + 1;
1632 end = textBuff.indexOf("\"", begin +1);
1633 if(begin == 0 || end == -1){
1634 //Link is missing a quote.
1635 break;
1636 }
1637 }
1638 String relativeLink = textBuff.substring(begin, end);
1639 if(!(relativeLink.toLowerCase().startsWith("mailto:") ||
1640 relativeLink.toLowerCase().startsWith("http:") ||
1641 relativeLink.toLowerCase().startsWith("https:") ||
1642 relativeLink.toLowerCase().startsWith("file:"))){
1643 relativeLink = "{@"+(new DocRootTaglet()).getName() + "}"
1644 + redirectPathFromRoot
1645 + relativeLink;
1646 textBuff.replace(begin, end, relativeLink);
1647 }
1648 begin = textBuff.toString().toLowerCase().indexOf("<a", begin + 1);
1649 }
1650 return textBuff.toString();
1651 }
1652 return text;
1653 }
1655 public String removeNonInlineHtmlTags(String text) {
1656 if (text.indexOf('<') < 0) {
1657 return text;
1658 }
1659 String noninlinetags[] = { "<ul>", "</ul>", "<ol>", "</ol>",
1660 "<dl>", "</dl>", "<table>", "</table>",
1661 "<tr>", "</tr>", "<td>", "</td>",
1662 "<th>", "</th>", "<p>", "</p>",
1663 "<li>", "</li>", "<dd>", "</dd>",
1664 "<dir>", "</dir>", "<dt>", "</dt>",
1665 "<h1>", "</h1>", "<h2>", "</h2>",
1666 "<h3>", "</h3>", "<h4>", "</h4>",
1667 "<h5>", "</h5>", "<h6>", "</h6>",
1668 "<pre>", "</pre>", "<menu>", "</menu>",
1669 "<listing>", "</listing>", "<hr>",
1670 "<blockquote>", "</blockquote>",
1671 "<center>", "</center>",
1672 "<UL>", "</UL>", "<OL>", "</OL>",
1673 "<DL>", "</DL>", "<TABLE>", "</TABLE>",
1674 "<TR>", "</TR>", "<TD>", "</TD>",
1675 "<TH>", "</TH>", "<P>", "</P>",
1676 "<LI>", "</LI>", "<DD>", "</DD>",
1677 "<DIR>", "</DIR>", "<DT>", "</DT>",
1678 "<H1>", "</H1>", "<H2>", "</H2>",
1679 "<H3>", "</H3>", "<H4>", "</H4>",
1680 "<H5>", "</H5>", "<H6>", "</H6>",
1681 "<PRE>", "</PRE>", "<MENU>", "</MENU>",
1682 "<LISTING>", "</LISTING>", "<HR>",
1683 "<BLOCKQUOTE>", "</BLOCKQUOTE>",
1684 "<CENTER>", "</CENTER>"
1685 };
1686 for (int i = 0; i < noninlinetags.length; i++) {
1687 text = replace(text, noninlinetags[i], "");
1688 }
1689 return text;
1690 }
1692 public String replace(String text, String tobe, String by) {
1693 while (true) {
1694 int startindex = text.indexOf(tobe);
1695 if (startindex < 0) {
1696 return text;
1697 }
1698 int endindex = startindex + tobe.length();
1699 StringBuilder replaced = new StringBuilder();
1700 if (startindex > 0) {
1701 replaced.append(text.substring(0, startindex));
1702 }
1703 replaced.append(by);
1704 if (text.length() > endindex) {
1705 replaced.append(text.substring(endindex));
1706 }
1707 text = replaced.toString();
1708 }
1709 }
1711 /**
1712 * Returns a link to the stylesheet file.
1713 *
1714 * @return an HtmlTree for the lINK tag which provides the stylesheet location
1715 */
1716 public HtmlTree getStyleSheetProperties() {
1717 String filename = configuration.stylesheetfile;
1718 if (filename.length() > 0) {
1719 File stylefile = new File(filename);
1720 String parent = stylefile.getParent();
1721 filename = (parent == null)?
1722 filename:
1723 filename.substring(parent.length() + 1);
1724 } else {
1725 filename = "stylesheet.css";
1726 }
1727 filename = relativePath + filename;
1728 HtmlTree link = HtmlTree.LINK("stylesheet", "text/css", filename, "Style");
1729 return link;
1730 }
1732 /**
1733 * According to
1734 * <cite>The Java™ Language Specification</cite>,
1735 * all the outer classes and static nested classes are core classes.
1736 */
1737 public boolean isCoreClass(ClassDoc cd) {
1738 return cd.containingClass() == null || cd.isStatic();
1739 }
1741 /**
1742 * Adds the annotatation types for the given packageDoc.
1743 *
1744 * @param packageDoc the package to write annotations for.
1745 * @param htmltree the documentation tree to which the annotation info will be
1746 * added
1747 */
1748 public void addAnnotationInfo(PackageDoc packageDoc, Content htmltree) {
1749 addAnnotationInfo(packageDoc, packageDoc.annotations(), htmltree);
1750 }
1752 /**
1753 * Adds the annotatation types for the given doc.
1754 *
1755 * @param doc the package to write annotations for
1756 * @param htmltree the content tree to which the annotation types will be added
1757 */
1758 public void addAnnotationInfo(ProgramElementDoc doc, Content htmltree) {
1759 addAnnotationInfo(doc, doc.annotations(), htmltree);
1760 }
1762 /**
1763 * Add the annotatation types for the given doc and parameter.
1764 *
1765 * @param indent the number of spaces to indent the parameters.
1766 * @param doc the doc to write annotations for.
1767 * @param param the parameter to write annotations for.
1768 * @param tree the content tree to which the annotation types will be added
1769 */
1770 public boolean addAnnotationInfo(int indent, Doc doc, Parameter param,
1771 Content tree) {
1772 return addAnnotationInfo(indent, doc, param.annotations(), false, tree);
1773 }
1775 /**
1776 * Adds the annotatation types for the given doc.
1777 *
1778 * @param doc the doc to write annotations for.
1779 * @param descList the array of {@link AnnotationDesc}.
1780 * @param htmltree the documentation tree to which the annotation info will be
1781 * added
1782 */
1783 private void addAnnotationInfo(Doc doc, AnnotationDesc[] descList,
1784 Content htmltree) {
1785 addAnnotationInfo(0, doc, descList, true, htmltree);
1786 }
1788 /**
1789 * Adds the annotatation types for the given doc.
1790 *
1791 * @param indent the number of extra spaces to indent the annotations.
1792 * @param doc the doc to write annotations for.
1793 * @param descList the array of {@link AnnotationDesc}.
1794 * @param htmltree the documentation tree to which the annotation info will be
1795 * added
1796 */
1797 private boolean addAnnotationInfo(int indent, Doc doc,
1798 AnnotationDesc[] descList, boolean lineBreak, Content htmltree) {
1799 List<String> annotations = getAnnotations(indent, descList, lineBreak);
1800 if (annotations.size() == 0) {
1801 return false;
1802 }
1803 Content annotationContent;
1804 for (Iterator<String> iter = annotations.iterator(); iter.hasNext();) {
1805 annotationContent = new RawHtml(iter.next());
1806 htmltree.addContent(annotationContent);
1807 }
1808 return true;
1809 }
1811 /**
1812 * Return the string representations of the annotation types for
1813 * the given doc.
1814 *
1815 * @param indent the number of extra spaces to indent the annotations.
1816 * @param descList the array of {@link AnnotationDesc}.
1817 * @param linkBreak if true, add new line between each member value.
1818 * @return an array of strings representing the annotations being
1819 * documented.
1820 */
1821 private List<String> getAnnotations(int indent, AnnotationDesc[] descList, boolean linkBreak) {
1822 List<String> results = new ArrayList<String>();
1823 StringBuilder annotation;
1824 for (int i = 0; i < descList.length; i++) {
1825 AnnotationTypeDoc annotationDoc = descList[i].annotationType();
1826 if (! Util.isDocumentedAnnotation(annotationDoc)){
1827 continue;
1828 }
1829 annotation = new StringBuilder();
1830 LinkInfoImpl linkInfo = new LinkInfoImpl(
1831 LinkInfoImpl.CONTEXT_ANNOTATION, annotationDoc);
1832 linkInfo.label = "@" + annotationDoc.name();
1833 annotation.append(getLink(linkInfo));
1834 AnnotationDesc.ElementValuePair[] pairs = descList[i].elementValues();
1835 if (pairs.length > 0) {
1836 annotation.append('(');
1837 for (int j = 0; j < pairs.length; j++) {
1838 if (j > 0) {
1839 annotation.append(",");
1840 if (linkBreak) {
1841 annotation.append(DocletConstants.NL);
1842 int spaces = annotationDoc.name().length() + 2;
1843 for (int k = 0; k < (spaces + indent); k++) {
1844 annotation.append(' ');
1845 }
1846 }
1847 }
1848 annotation.append(getDocLink(LinkInfoImpl.CONTEXT_ANNOTATION,
1849 pairs[j].element(), pairs[j].element().name(), false));
1850 annotation.append('=');
1851 AnnotationValue annotationValue = pairs[j].value();
1852 List<AnnotationValue> annotationTypeValues = new ArrayList<AnnotationValue>();
1853 if (annotationValue.value() instanceof AnnotationValue[]) {
1854 AnnotationValue[] annotationArray =
1855 (AnnotationValue[]) annotationValue.value();
1856 for (int k = 0; k < annotationArray.length; k++) {
1857 annotationTypeValues.add(annotationArray[k]);
1858 }
1859 } else {
1860 annotationTypeValues.add(annotationValue);
1861 }
1862 annotation.append(annotationTypeValues.size() == 1 ? "" : "{");
1863 for (Iterator<AnnotationValue> iter = annotationTypeValues.iterator(); iter.hasNext(); ) {
1864 annotation.append(annotationValueToString(iter.next()));
1865 annotation.append(iter.hasNext() ? "," : "");
1866 }
1867 annotation.append(annotationTypeValues.size() == 1 ? "" : "}");
1868 }
1869 annotation.append(")");
1870 }
1871 annotation.append(linkBreak ? DocletConstants.NL : "");
1872 results.add(annotation.toString());
1873 }
1874 return results;
1875 }
1877 private String annotationValueToString(AnnotationValue annotationValue) {
1878 if (annotationValue.value() instanceof Type) {
1879 Type type = (Type) annotationValue.value();
1880 if (type.asClassDoc() != null) {
1881 LinkInfoImpl linkInfo = new LinkInfoImpl(
1882 LinkInfoImpl.CONTEXT_ANNOTATION, type);
1883 linkInfo.label = (type.asClassDoc().isIncluded() ?
1884 type.typeName() :
1885 type.qualifiedTypeName()) + type.dimension() + ".class";
1886 return getLink(linkInfo);
1887 } else {
1888 return type.typeName() + type.dimension() + ".class";
1889 }
1890 } else if (annotationValue.value() instanceof AnnotationDesc) {
1891 List<String> list = getAnnotations(0,
1892 new AnnotationDesc[]{(AnnotationDesc) annotationValue.value()},
1893 false);
1894 StringBuilder buf = new StringBuilder();
1895 for (String s: list) {
1896 buf.append(s);
1897 }
1898 return buf.toString();
1899 } else if (annotationValue.value() instanceof MemberDoc) {
1900 return getDocLink(LinkInfoImpl.CONTEXT_ANNOTATION,
1901 (MemberDoc) annotationValue.value(),
1902 ((MemberDoc) annotationValue.value()).name(), false);
1903 } else {
1904 return annotationValue.toString();
1905 }
1906 }
1908 /**
1909 * Return the configuation for this doclet.
1910 *
1911 * @return the configuration for this doclet.
1912 */
1913 public Configuration configuration() {
1914 return configuration;
1915 }
1916 }