1 /*

     2  * Copyright (c) 2013, 2015, 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 

    30 import com.sun.javadoc.*;

    31 import com.sun.tools.javac.jvm.Profile;

    32 import com.sun.tools.doclets.formats.html.markup.*;

    33 import com.sun.tools.doclets.internal.toolkit.*;

    34 import com.sun.tools.doclets.internal.toolkit.util.*;

    35 

    36 /**

    37  * Class to generate file for each profile package contents in the right-hand

    38  * frame. This will list all the Class Kinds in the package. A click on any

    39  * class-kind will update the frame with the clicked class-kind page.

    40  *

    41  *  <p><b>This is NOT part of any supported API.

    42  *  If you write code that depends on this, you do so at your own risk.

    43  *  This code and its internal interfaces are subject to change or

    44  *  deletion without notice.</b>

    45  *

    46  * @author Bhavesh Patel

    47  */

    48 public class ProfilePackageWriterImpl extends HtmlDocletWriter

    49     implements ProfilePackageSummaryWriter {

    50 

    51     /**

    52      * The prev package name in the alpha-order list.

    53      */

    54     protected PackageDoc prev;

    55 

    56     /**

    57      * The next package name in the alpha-order list.

    58      */

    59     protected PackageDoc next;

    60 

    61     /**

    62      * The profile package being documented.

    63      */

    64     protected PackageDoc packageDoc;

    65 

    66     /**

    67      * The name of the profile being documented.

    68      */

    69     protected String profileName;

    70 

    71     /**

    72      * The value of the profile being documented.

    73      */

    74     protected int profileValue;

    75 

    76     /**

    77      * The HTML tree for main tag.

    78      */

    79     protected HtmlTree mainTree = HtmlTree.MAIN();

    80 

    81     /**

    82      * The HTML tree for section tag.

    83      */

    84     protected HtmlTree sectionTree = HtmlTree.SECTION();

    85 

    86     /**

    87      * Constructor to construct ProfilePackageWriter object and to generate

    88      * "profilename-package-summary.html" file in the respective package directory.

    89      * For example for profile compact1 and package "java.lang" this will generate file

    90      * "compact1-package-summary.html" file in the "java/lang" directory. It will also

    91      * create "java/lang" directory in the current or the destination directory

    92      * if it doesn't exist.

    93      *

    94      * @param configuration the configuration of the doclet.

    95      * @param packageDoc    PackageDoc under consideration.

    96      * @param prev          Previous package in the sorted array.

    97      * @param next          Next package in the sorted array.

    98      * @param profile       The profile being documented.

    99      */

   100     public ProfilePackageWriterImpl(ConfigurationImpl configuration,

   101             PackageDoc packageDoc, PackageDoc prev, PackageDoc next,

   102             Profile profile) throws IOException {

   103         super(configuration, DocPath.forPackage(packageDoc).resolve(

   104                 DocPaths.profilePackageSummary(profile.name)));

   105         this.prev = prev;

   106         this.next = next;

   107         this.packageDoc = packageDoc;

   108         this.profileName = profile.name;

   109         this.profileValue = profile.value;

   110     }

   111 

   112     /**

   113      * {@inheritDoc}

   114      */

   115     public Content getPackageHeader(String heading) {

   116         HtmlTree bodyTree = getBody(true, getWindowTitle(utils.getPackageName(packageDoc)));

   117         HtmlTree htmlTree = (configuration.allowTag(HtmlTag.HEADER))

   118                 ? HtmlTree.HEADER()

   119                 : bodyTree;

   120         addTop(htmlTree);

   121         addNavLinks(true, htmlTree);

   122         if (configuration.allowTag(HtmlTag.HEADER)) {

   123             bodyTree.addContent(htmlTree);

   124         }

   125         HtmlTree div = new HtmlTree(HtmlTag.DIV);

   126         div.addStyle(HtmlStyle.header);

   127         Content profileContent = new StringContent(profileName);

   128         Content profileNameDiv = HtmlTree.DIV(HtmlStyle.subTitle, profileContent);

   129         div.addContent(profileNameDiv);

   130         Content annotationContent = new HtmlTree(HtmlTag.P);

   131         addAnnotationInfo(packageDoc, annotationContent);

   132         div.addContent(annotationContent);

   133         Content tHeading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, true,

   134                 HtmlStyle.title, packageLabel);

   135         tHeading.addContent(getSpace());

   136         Content packageHead = new RawHtml(heading);

   137         tHeading.addContent(packageHead);

   138         div.addContent(tHeading);

   139         addDeprecationInfo(div);

   140         if (packageDoc.inlineTags().length > 0 && ! configuration.nocomment) {

   141             HtmlTree docSummaryDiv = new HtmlTree(HtmlTag.DIV);

   142             docSummaryDiv.addStyle(HtmlStyle.docSummary);

   143             addSummaryComment(packageDoc, docSummaryDiv);

   144             div.addContent(docSummaryDiv);

   145             Content space = getSpace();

   146             Content descLink = getHyperLink(getDocLink(

   147                     SectionName.PACKAGE_DESCRIPTION),

   148                     descriptionLabel, "", "");

   149             Content descPara = new HtmlTree(HtmlTag.P, seeLabel, space, descLink);

   150             div.addContent(descPara);

   151         }

   152         if (configuration.allowTag(HtmlTag.MAIN)) {

   153             mainTree.addContent(div);

   154         } else {

   155             bodyTree.addContent(div);

   156         }

   157         return bodyTree;

   158     }

   159 

   160     /**

   161      * {@inheritDoc}

   162      */

   163     public Content getContentHeader() {

   164         HtmlTree div = new HtmlTree(HtmlTag.DIV);

   165         div.addStyle(HtmlStyle.contentContainer);

   166         return div;

   167     }

   168 

   169     /**

   170      * Add the package deprecation information to the documentation tree.

   171      *

   172      * @param div the content tree to which the deprecation information will be added

   173      */

   174     public void addDeprecationInfo(Content div) {

   175         Tag[] deprs = packageDoc.tags("deprecated");

   176         if (utils.isDeprecated(packageDoc)) {

   177             HtmlTree deprDiv = new HtmlTree(HtmlTag.DIV);

   178             deprDiv.addStyle(HtmlStyle.deprecatedContent);

   179             Content deprPhrase = HtmlTree.SPAN(HtmlStyle.deprecatedLabel, deprecatedPhrase);

   180             deprDiv.addContent(deprPhrase);

   181             if (deprs.length > 0) {

   182                 Tag[] commentTags = deprs[0].inlineTags();

   183                 if (commentTags.length > 0) {

   184                     addInlineDeprecatedComment(packageDoc, deprs[0], deprDiv);

   185                 }

   186             }

   187             div.addContent(deprDiv);

   188         }

   189     }

   190 

   191     /**

   192      * {@inheritDoc}

   193      */

   194     public void addClassesSummary(ClassDoc[] classes, String label,

   195             String tableSummary, String[] tableHeader, Content packageSummaryContentTree) {

   196         HtmlTree li = new HtmlTree(HtmlTag.LI);

   197         li.addStyle(HtmlStyle.blockList);

   198         addClassesSummary(classes, label, tableSummary, tableHeader,

   199                 li, profileValue);

   200         packageSummaryContentTree.addContent(li);

   201     }

   202 

   203     /**

   204      * {@inheritDoc}

   205      */

   206     public Content getSummaryHeader() {

   207         HtmlTree ul = new HtmlTree(HtmlTag.UL);

   208         ul.addStyle(HtmlStyle.blockList);

   209         return ul;

   210     }

   211 

   212     /**

   213      * {@inheritDoc}

   214      */

   215     public void addPackageDescription(Content packageContentTree) {

   216         if (packageDoc.inlineTags().length > 0) {

   217             packageContentTree.addContent(

   218                     getMarkerAnchor(SectionName.PACKAGE_DESCRIPTION));

   219             Content h2Content = new StringContent(

   220                     configuration.getText("doclet.Package_Description",

   221                     packageDoc.name()));

   222             Content heading = HtmlTree.HEADING(HtmlConstants.PACKAGE_HEADING, true, h2Content);

   223             if (configuration.allowTag(HtmlTag.SECTION)) {

   224                 sectionTree.addContent(heading);

   225                 addInlineComment(packageDoc, sectionTree);

   226             } else {

   227                 packageContentTree.addContent(heading);

   228                 addInlineComment(packageDoc, packageContentTree);

   229             }

   230         }

   231     }

   232 

   233     /**

   234      * {@inheritDoc}

   235      */

   236     public void addPackageTags(Content packageContentTree) {

   237         Content htmlTree = (configuration.allowTag(HtmlTag.SECTION))

   238                 ? sectionTree

   239                 : packageContentTree;

   240         addTagsInfo(packageDoc, htmlTree);

   241     }

   242 

   243     /**

   244      * {@inheritDoc}

   245      */

   246     public void addPackageContent(Content contentTree, Content packageContentTree) {

   247         if (configuration.allowTag(HtmlTag.MAIN)) {

   248             packageContentTree.addContent(sectionTree);

   249             mainTree.addContent(packageContentTree);

   250             contentTree.addContent(mainTree);

   251         } else {

   252             contentTree.addContent(packageContentTree);

   253         }

   254     }

   255 

   256     /**

   257      * {@inheritDoc}

   258      */

   259     public void addPackageFooter(Content contentTree) {

   260         Content htmlTree = (configuration.allowTag(HtmlTag.FOOTER))

   261                 ? HtmlTree.FOOTER()

   262                 : contentTree;

   263         addNavLinks(false, htmlTree);

   264         addBottom(htmlTree);

   265         if (configuration.allowTag(HtmlTag.FOOTER)) {

   266             contentTree.addContent(htmlTree);

   267         }

   268     }

   269 

   270     /**

   271      * {@inheritDoc}

   272      */

   273     public void printDocument(Content contentTree) throws IOException {

   274         printHtmlDocument(configuration.metakeywords.getMetaKeywords(packageDoc),

   275                 true, contentTree);

   276     }

   277 

   278     /**

   279      * Get "Use" link for this package in the navigation bar.

   280      *

   281      * @return a content tree for the class use link

   282      */

   283     protected Content getNavLinkClassUse() {

   284         Content useLink = getHyperLink(DocPaths.PACKAGE_USE,

   285                 useLabel, "", "");

   286         Content li = HtmlTree.LI(useLink);

   287         return li;

   288     }

   289 

   290     /**

   291      * Get "PREV PACKAGE" link in the navigation bar.

   292      *

   293      * @return a content tree for the previous link

   294      */

   295     public Content getNavLinkPrevious() {

   296         Content li;

   297         if (prev == null) {

   298             li = HtmlTree.LI(prevpackageLabel);

   299         } else {

   300             DocPath path = DocPath.relativePath(packageDoc, prev);

   301             li = HtmlTree.LI(getHyperLink(path.resolve(DocPaths.profilePackageSummary(profileName)),

   302                 prevpackageLabel, "", ""));

   303         }

   304         return li;

   305     }

   306 

   307     /**

   308      * Get "NEXT PACKAGE" link in the navigation bar.

   309      *

   310      * @return a content tree for the next link

   311      */

   312     public Content getNavLinkNext() {

   313         Content li;

   314         if (next == null) {

   315             li = HtmlTree.LI(nextpackageLabel);

   316         } else {

   317             DocPath path = DocPath.relativePath(packageDoc, next);

   318             li = HtmlTree.LI(getHyperLink(path.resolve(DocPaths.profilePackageSummary(profileName)),

   319                 nextpackageLabel, "", ""));

   320         }

   321         return li;

   322     }

   323 

   324     /**

   325      * Get "Tree" link in the navigation bar. This will be link to the package

   326      * tree file.

   327      *

   328      * @return a content tree for the tree link

   329      */

   330     protected Content getNavLinkTree() {

   331         Content useLink = getHyperLink(DocPaths.PACKAGE_TREE,

   332                 treeLabel, "", "");

   333         Content li = HtmlTree.LI(useLink);

   334         return li;

   335     }

   336 

   337     /**

   338      * Highlight "Package" in the navigation bar, as this is the package page.

   339      *

   340      * @return a content tree for the package link

   341      */

   342     protected Content getNavLinkPackage() {

   343         Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, packageLabel);

   344         return li;

   345     }

   346 }