View Javadoc
1   /*
2    * Copyright (c) 2013, 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   */
25  
26  package com.sun.tools.doclets.formats.html;
27  
28  import java.io.*;
29  import java.util.*;
30  
31  import com.sun.javadoc.*;
32  import com.sun.tools.javac.jvm.Profile;
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.util.*;
36  
37  /**
38   * Class to generate file for each profile package contents in the right-hand
39   * frame. This will list all the Class Kinds in the package. A click on any
40   * class-kind will update the frame with the clicked class-kind page.
41   *
42   *  <p><b>This is NOT part of any supported API.
43   *  If you write code that depends on this, you do so at your own risk.
44   *  This code and its internal interfaces are subject to change or
45   *  deletion without notice.</b>
46   *
47   * @author Bhavesh Patel
48   */
49  public class ProfilePackageWriterImpl extends HtmlDocletWriter
50      implements ProfilePackageSummaryWriter {
51  
52      /**
53       * The prev package name in the alpha-order list.
54       */
55      protected PackageDoc prev;
56  
57      /**
58       * The next package name in the alpha-order list.
59       */
60      protected PackageDoc next;
61  
62      /**
63       * The profile package being documented.
64       */
65      protected PackageDoc packageDoc;
66  
67      /**
68       * The name of the profile being documented.
69       */
70      protected String profileName;
71  
72      /**
73       * The value of the profile being documented.
74       */
75      protected int profileValue;
76  
77      /**
78       * Constructor to construct ProfilePackageWriter object and to generate
79       * "profilename-package-summary.html" file in the respective package directory.
80       * For example for profile compact1 and package "java.lang" this will generate file
81       * "compact1-package-summary.html" file in the "java/lang" directory. It will also
82       * create "java/lang" directory in the current or the destination directory
83       * if it doesn't exist.
84       *
85       * @param configuration the configuration of the doclet.
86       * @param packageDoc    PackageDoc under consideration.
87       * @param prev          Previous package in the sorted array.
88       * @param next          Next package in the sorted array.
89       * @param profile       The profile being documented.
90       */
91      public ProfilePackageWriterImpl(ConfigurationImpl configuration,
92              PackageDoc packageDoc, PackageDoc prev, PackageDoc next,
93              Profile profile) throws IOException {
94          super(configuration, DocPath.forPackage(packageDoc).resolve(
95                  DocPaths.profilePackageSummary(profile.name)));
96          this.prev = prev;
97          this.next = next;
98          this.packageDoc = packageDoc;
99          this.profileName = profile.name;
100         this.profileValue = profile.value;
101     }
102 
103     /**
104      * {@inheritDoc}
105      */
106     public Content getPackageHeader(String heading) {
107         String pkgName = packageDoc.name();
108         Content bodyTree = getBody(true, getWindowTitle(pkgName));
109         addTop(bodyTree);
110         addNavLinks(true, bodyTree);
111         HtmlTree div = new HtmlTree(HtmlTag.DIV);
112         div.addStyle(HtmlStyle.header);
113         Content profileContent = new StringContent(profileName);
114         Content profileNameDiv = HtmlTree.DIV(HtmlStyle.subTitle, profileContent);
115         div.addContent(profileNameDiv);
116         Content annotationContent = new HtmlTree(HtmlTag.P);
117         addAnnotationInfo(packageDoc, annotationContent);
118         div.addContent(annotationContent);
119         Content tHeading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, true,
120                 HtmlStyle.title, packageLabel);
121         tHeading.addContent(getSpace());
122         Content packageHead = new RawHtml(heading);
123         tHeading.addContent(packageHead);
124         div.addContent(tHeading);
125         addDeprecationInfo(div);
126         if (packageDoc.inlineTags().length > 0 && ! configuration.nocomment) {
127             HtmlTree docSummaryDiv = new HtmlTree(HtmlTag.DIV);
128             docSummaryDiv.addStyle(HtmlStyle.docSummary);
129             addSummaryComment(packageDoc, docSummaryDiv);
130             div.addContent(docSummaryDiv);
131             Content space = getSpace();
132             Content descLink = getHyperLink(getDocLink(
133                     SectionName.PACKAGE_DESCRIPTION),
134                     descriptionLabel, "", "");
135             Content descPara = new HtmlTree(HtmlTag.P, seeLabel, space, descLink);
136             div.addContent(descPara);
137         }
138         bodyTree.addContent(div);
139         return bodyTree;
140     }
141 
142     /**
143      * {@inheritDoc}
144      */
145     public Content getContentHeader() {
146         HtmlTree div = new HtmlTree(HtmlTag.DIV);
147         div.addStyle(HtmlStyle.contentContainer);
148         return div;
149     }
150 
151     /**
152      * Add the package deprecation information to the documentation tree.
153      *
154      * @param div the content tree to which the deprecation information will be added
155      */
156     public void addDeprecationInfo(Content div) {
157         Tag[] deprs = packageDoc.tags("deprecated");
158         if (Util.isDeprecated(packageDoc)) {
159             HtmlTree deprDiv = new HtmlTree(HtmlTag.DIV);
160             deprDiv.addStyle(HtmlStyle.deprecatedContent);
161             Content deprPhrase = HtmlTree.SPAN(HtmlStyle.deprecatedLabel, deprecatedPhrase);
162             deprDiv.addContent(deprPhrase);
163             if (deprs.length > 0) {
164                 Tag[] commentTags = deprs[0].inlineTags();
165                 if (commentTags.length > 0) {
166                     addInlineDeprecatedComment(packageDoc, deprs[0], deprDiv);
167                 }
168             }
169             div.addContent(deprDiv);
170         }
171     }
172 
173     /**
174      * {@inheritDoc}
175      */
176     public void addClassesSummary(ClassDoc[] classes, String label,
177             String tableSummary, String[] tableHeader, Content packageSummaryContentTree) {
178         HtmlTree li = new HtmlTree(HtmlTag.LI);
179         li.addStyle(HtmlStyle.blockList);
180         addClassesSummary(classes, label, tableSummary, tableHeader,
181                 li, profileValue);
182         packageSummaryContentTree.addContent(li);
183     }
184 
185     /**
186      * {@inheritDoc}
187      */
188     public Content getSummaryHeader() {
189         HtmlTree ul = new HtmlTree(HtmlTag.UL);
190         ul.addStyle(HtmlStyle.blockList);
191         return ul;
192     }
193 
194     /**
195      * {@inheritDoc}
196      */
197     public void addPackageDescription(Content packageContentTree) {
198         if (packageDoc.inlineTags().length > 0) {
199             packageContentTree.addContent(
200                     getMarkerAnchor(SectionName.PACKAGE_DESCRIPTION));
201             Content h2Content = new StringContent(
202                     configuration.getText("doclet.Package_Description",
203                     packageDoc.name()));
204             packageContentTree.addContent(HtmlTree.HEADING(HtmlConstants.PACKAGE_HEADING,
205                     true, h2Content));
206             addInlineComment(packageDoc, packageContentTree);
207         }
208     }
209 
210     /**
211      * {@inheritDoc}
212      */
213     public void addPackageTags(Content packageContentTree) {
214         addTagsInfo(packageDoc, packageContentTree);
215     }
216 
217     /**
218      * {@inheritDoc}
219      */
220     public void addPackageFooter(Content contentTree) {
221         addNavLinks(false, contentTree);
222         addBottom(contentTree);
223     }
224 
225     /**
226      * {@inheritDoc}
227      */
228     public void printDocument(Content contentTree) throws IOException {
229         printHtmlDocument(configuration.metakeywords.getMetaKeywords(packageDoc),
230                 true, contentTree);
231     }
232 
233     /**
234      * Get "Use" link for this package in the navigation bar.
235      *
236      * @return a content tree for the class use link
237      */
238     protected Content getNavLinkClassUse() {
239         Content useLink = getHyperLink(DocPaths.PACKAGE_USE,
240                 useLabel, "", "");
241         Content li = HtmlTree.LI(useLink);
242         return li;
243     }
244 
245     /**
246      * Get "PREV PACKAGE" link in the navigation bar.
247      *
248      * @return a content tree for the previous link
249      */
250     public Content getNavLinkPrevious() {
251         Content li;
252         if (prev == null) {
253             li = HtmlTree.LI(prevpackageLabel);
254         } else {
255             DocPath path = DocPath.relativePath(packageDoc, prev);
256             li = HtmlTree.LI(getHyperLink(path.resolve(DocPaths.profilePackageSummary(profileName)),
257                 prevpackageLabel, "", ""));
258         }
259         return li;
260     }
261 
262     /**
263      * Get "NEXT PACKAGE" link in the navigation bar.
264      *
265      * @return a content tree for the next link
266      */
267     public Content getNavLinkNext() {
268         Content li;
269         if (next == null) {
270             li = HtmlTree.LI(nextpackageLabel);
271         } else {
272             DocPath path = DocPath.relativePath(packageDoc, next);
273             li = HtmlTree.LI(getHyperLink(path.resolve(DocPaths.profilePackageSummary(profileName)),
274                 nextpackageLabel, "", ""));
275         }
276         return li;
277     }
278 
279     /**
280      * Get "Tree" link in the navigation bar. This will be link to the package
281      * tree file.
282      *
283      * @return a content tree for the tree link
284      */
285     protected Content getNavLinkTree() {
286         Content useLink = getHyperLink(DocPaths.PACKAGE_TREE,
287                 treeLabel, "", "");
288         Content li = HtmlTree.LI(useLink);
289         return li;
290     }
291 
292     /**
293      * Highlight "Package" in the navigation bar, as this is the package page.
294      *
295      * @return a content tree for the package link
296      */
297     protected Content getNavLinkPackage() {
298         Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, packageLabel);
299         return li;
300     }
301 }