PackageWriterImpl.java revision 3824:376ee1fd40c3 
1/*
2 * Copyright (c) 1997, 2016, 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
26package jdk.javadoc.internal.doclets.formats.html;
27
28import java.util.*;
29
30import javax.lang.model.element.ModuleElement;
31import javax.lang.model.element.PackageElement;
32import javax.lang.model.element.TypeElement;
33
34import com.sun.source.doctree.DocTree;
35import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants;
36import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
37import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
38import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
39import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
40import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
41import jdk.javadoc.internal.doclets.toolkit.Content;
42import jdk.javadoc.internal.doclets.toolkit.PackageSummaryWriter;
43import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
44import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
45import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
46import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
47
48/**
49 * Class to generate file for each package contents in the right-hand
50 * frame. This will list all the Class Kinds in the package. A click on any
51 * class-kind will update the frame with the clicked class-kind page.
52 *
53 *  <p><b>This is NOT part of any supported API.
54 *  If you write code that depends on this, you do so at your own risk.
55 *  This code and its internal interfaces are subject to change or
56 *  deletion without notice.</b>
57 *
58 * @author Atul M Dambalkar
59 * @author Bhavesh Patel (Modified)
60 */
61public class PackageWriterImpl extends HtmlDocletWriter
62    implements PackageSummaryWriter {
63
64    /**
65     * The prev package name in the alpha-order list.
66     */
67    protected PackageElement prev;
68
69    /**
70     * The next package name in the alpha-order list.
71     */
72    protected PackageElement next;
73
74    /**
75     * The package being documented.
76     */
77    protected PackageElement packageElement;
78
79    /**
80     * The HTML tree for main tag.
81     */
82    protected HtmlTree mainTree = HtmlTree.MAIN();
83
84    /**
85     * The HTML tree for section tag.
86     */
87    protected HtmlTree sectionTree = HtmlTree.SECTION();
88
89    /**
90     * Constructor to construct PackageWriter object and to generate
91     * "package-summary.html" file in the respective package directory.
92     * For example for package "java.lang" this will generate file
93     * "package-summary.html" file in the "java/lang" directory. It will also
94     * create "java/lang" directory in the current or the destination directory
95     * if it doesn't exist.
96     *
97     * @param configuration the configuration of the doclet.
98     * @param packageElement    PackageElement under consideration.
99     * @param prev          Previous package in the sorted array.
100     * @param next            Next package in the sorted array.
101     */
102    public PackageWriterImpl(ConfigurationImpl configuration,
103            PackageElement packageElement, PackageElement prev, PackageElement next) {
104        super(configuration, DocPath
105                .forPackage(packageElement)
106                .resolve(DocPaths.PACKAGE_SUMMARY));
107        this.prev = prev;
108        this.next = next;
109        this.packageElement = packageElement;
110    }
111
112    /**
113     * {@inheritDoc}
114     */
115    @Override
116    public Content getPackageHeader(String heading) {
117        HtmlTree bodyTree = getBody(true, getWindowTitle(utils.getPackageName(packageElement)));
118        HtmlTree htmlTree = (configuration.allowTag(HtmlTag.HEADER))
119                ? HtmlTree.HEADER()
120                : bodyTree;
121        addTop(htmlTree);
122        addNavLinks(true, htmlTree);
123        if (configuration.allowTag(HtmlTag.HEADER)) {
124            bodyTree.addContent(htmlTree);
125        }
126        HtmlTree div = new HtmlTree(HtmlTag.DIV);
127        div.addStyle(HtmlStyle.header);
128        if (configuration.showModules) {
129            ModuleElement mdle = configuration.docEnv.getElementUtils().getModuleOf(packageElement);
130            Content classModuleLabel = HtmlTree.SPAN(HtmlStyle.moduleLabelInClass, contents.moduleLabel);
131            Content moduleNameDiv = HtmlTree.DIV(HtmlStyle.subTitle, classModuleLabel);
132            moduleNameDiv.addContent(Contents.SPACE);
133            moduleNameDiv.addContent(getModuleLink(mdle,
134                    new StringContent(mdle.getQualifiedName().toString())));
135            div.addContent(moduleNameDiv);
136        }
137        Content annotationContent = new HtmlTree(HtmlTag.P);
138        addAnnotationInfo(packageElement, annotationContent);
139        div.addContent(annotationContent);
140        Content tHeading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, true,
141                HtmlStyle.title, contents.packageLabel);
142        tHeading.addContent(Contents.SPACE);
143        Content packageHead = new StringContent(heading);
144        tHeading.addContent(packageHead);
145        div.addContent(tHeading);
146        if (configuration.allowTag(HtmlTag.MAIN)) {
147            mainTree.addContent(div);
148        } else {
149            bodyTree.addContent(div);
150        }
151        return bodyTree;
152    }
153
154    /**
155     * {@inheritDoc}
156     */
157    @Override
158    public Content getContentHeader() {
159        HtmlTree div = new HtmlTree(HtmlTag.DIV);
160        div.addStyle(HtmlStyle.contentContainer);
161        return div;
162    }
163
164    /**
165     * Add the package deprecation information to the documentation tree.
166     *
167     * @param div the content tree to which the deprecation information will be added
168     */
169    public void addDeprecationInfo(Content div) {
170        List<? extends DocTree> deprs = utils.getBlockTags(packageElement, DocTree.Kind.DEPRECATED);
171        if (utils.isDeprecated(packageElement)) {
172            CommentHelper ch = utils.getCommentHelper(packageElement);
173            HtmlTree deprDiv = new HtmlTree(HtmlTag.DIV);
174            deprDiv.addStyle(HtmlStyle.deprecatedContent);
175            Content deprPhrase = HtmlTree.SPAN(HtmlStyle.deprecatedLabel, getDeprecatedPhrase(packageElement));
176            deprDiv.addContent(deprPhrase);
177            if (!deprs.isEmpty()) {
178                List<? extends DocTree> commentTags = ch.getDescription(configuration, deprs.get(0));
179                if (!commentTags.isEmpty()) {
180                    addInlineDeprecatedComment(packageElement, deprs.get(0), deprDiv);
181                }
182            }
183            div.addContent(deprDiv);
184        }
185    }
186
187    /**
188     * {@inheritDoc}
189     */
190    @Override
191    public Content getSummaryHeader() {
192        HtmlTree ul = new HtmlTree(HtmlTag.UL);
193        ul.addStyle(HtmlStyle.blockList);
194        return ul;
195    }
196
197    /**
198     * {@inheritDoc}
199     */
200    @Override
201    public void addClassesSummary(SortedSet<TypeElement> classes, String label,
202            String tableSummary, List<String> tableHeader, Content summaryContentTree) {
203        if(!classes.isEmpty()) {
204            Content caption = getTableCaption(new RawHtml(label));
205            Content table = (configuration.isOutputHtml5())
206                    ? HtmlTree.TABLE(HtmlStyle.typeSummary, caption)
207                    : HtmlTree.TABLE(HtmlStyle.typeSummary, tableSummary, caption);
208            table.addContent(getSummaryTableHeader(tableHeader, "col"));
209            Content tbody = new HtmlTree(HtmlTag.TBODY);
210            boolean altColor = false;
211            for (TypeElement klass : classes) {
212                altColor = !altColor;
213                if (!utils.isCoreClass(klass) ||
214                    !configuration.isGeneratedDoc(klass)) {
215                    continue;
216                }
217                Content classContent = getLink(new LinkInfoImpl(
218                        configuration, LinkInfoImpl.Kind.PACKAGE, klass));
219                Content thClass = HtmlTree.TH_ROW_SCOPE(HtmlStyle.colFirst, classContent);
220                HtmlTree tr = HtmlTree.TR(thClass);
221                tr.addStyle(altColor ? HtmlStyle.altColor : HtmlStyle.rowColor);
222
223                HtmlTree tdClassDescription = new HtmlTree(HtmlTag.TD);
224                tdClassDescription.addStyle(HtmlStyle.colLast);
225                if (utils.isDeprecated(klass)) {
226                    tdClassDescription.addContent(getDeprecatedPhrase(klass));
227                    List<? extends DocTree> tags = utils.getDeprecatedTrees(klass);
228                    if (!tags.isEmpty()) {
229                        addSummaryDeprecatedComment(klass, tags.get(0), tdClassDescription);
230                    }
231                } else {
232                    addSummaryComment(klass, tdClassDescription);
233                }
234                tr.addContent(tdClassDescription);
235                tbody.addContent(tr);
236            }
237            table.addContent(tbody);
238            Content li = HtmlTree.LI(HtmlStyle.blockList, table);
239            summaryContentTree.addContent(li);
240        }
241    }
242
243    /**
244     * {@inheritDoc}
245     */
246    @Override
247    public void addPackageDescription(Content packageContentTree) {
248        if (!utils.getBody(packageElement).isEmpty()) {
249            Content tree = configuration.allowTag(HtmlTag.SECTION) ? sectionTree : packageContentTree;
250            addDeprecationInfo(tree);
251            addInlineComment(packageElement, tree);
252        }
253    }
254
255    /**
256     * {@inheritDoc}
257     */
258    @Override
259    public void addPackageTags(Content packageContentTree) {
260        Content htmlTree = (configuration.allowTag(HtmlTag.SECTION))
261                ? sectionTree
262                : packageContentTree;
263        addTagsInfo(packageElement, htmlTree);
264        if (configuration.allowTag(HtmlTag.SECTION)) {
265            packageContentTree.addContent(sectionTree);
266        }
267    }
268
269    /**
270     * {@inheritDoc}
271     */
272    @Override
273    public void addPackageContent(Content contentTree, Content packageContentTree) {
274        if (configuration.allowTag(HtmlTag.MAIN)) {
275            mainTree.addContent(packageContentTree);
276            contentTree.addContent(mainTree);
277        } else {
278            contentTree.addContent(packageContentTree);
279        }
280    }
281
282    /**
283     * {@inheritDoc}
284     */
285    @Override
286    public void addPackageFooter(Content contentTree) {
287        Content htmlTree = (configuration.allowTag(HtmlTag.FOOTER))
288                ? HtmlTree.FOOTER()
289                : contentTree;
290        addNavLinks(false, htmlTree);
291        addBottom(htmlTree);
292        if (configuration.allowTag(HtmlTag.FOOTER)) {
293            contentTree.addContent(htmlTree);
294        }
295    }
296
297    /**
298     * {@inheritDoc}
299     */
300    @Override
301    public void printDocument(Content contentTree) throws DocFileIOException {
302        printHtmlDocument(configuration.metakeywords.getMetaKeywords(packageElement),
303                true, contentTree);
304    }
305
306    /**
307     * Get "Use" link for this pacakge in the navigation bar.
308     *
309     * @return a content tree for the class use link
310     */
311    @Override
312    protected Content getNavLinkClassUse() {
313        Content useLink = getHyperLink(DocPaths.PACKAGE_USE,
314                contents.useLabel, "", "");
315        Content li = HtmlTree.LI(useLink);
316        return li;
317    }
318
319    /**
320     * Get "PREV PACKAGE" link in the navigation bar.
321     *
322     * @return a content tree for the previous link
323     */
324    @Override
325    public Content getNavLinkPrevious() {
326        Content li;
327        if (prev == null) {
328            li = HtmlTree.LI(contents.prevPackageLabel);
329        } else {
330            DocPath path = DocPath.relativePath(packageElement, prev);
331            li = HtmlTree.LI(getHyperLink(path.resolve(DocPaths.PACKAGE_SUMMARY),
332                contents.prevPackageLabel, "", ""));
333        }
334        return li;
335    }
336
337    /**
338     * Get "NEXT PACKAGE" link in the navigation bar.
339     *
340     * @return a content tree for the next link
341     */
342    @Override
343    public Content getNavLinkNext() {
344        Content li;
345        if (next == null) {
346            li = HtmlTree.LI(contents.nextPackageLabel);
347        } else {
348            DocPath path = DocPath.relativePath(packageElement, next);
349            li = HtmlTree.LI(getHyperLink(path.resolve(DocPaths.PACKAGE_SUMMARY),
350                contents.nextPackageLabel, "", ""));
351        }
352        return li;
353    }
354
355    /**
356     * Get "Tree" link in the navigation bar. This will be link to the package
357     * tree file.
358     *
359     * @return a content tree for the tree link
360     */
361    @Override
362    protected Content getNavLinkTree() {
363        Content useLink = getHyperLink(DocPaths.PACKAGE_TREE,
364                contents.treeLabel, "", "");
365        Content li = HtmlTree.LI(useLink);
366        return li;
367    }
368
369    /**
370     * Get the module link.
371     *
372     * @return a content tree for the module link
373     */
374    @Override
375    protected Content getNavLinkModule() {
376        Content linkContent = getModuleLink(utils.elementUtils.getModuleOf(packageElement),
377                contents.moduleLabel);
378        Content li = HtmlTree.LI(linkContent);
379        return li;
380    }
381
382    /**
383     * Highlight "Package" in the navigation bar, as this is the package page.
384     *
385     * @return a content tree for the package link
386     */
387    @Override
388    protected Content getNavLinkPackage() {
389        Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, contents.packageLabel);
390        return li;
391    }
392}
393