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(DocLink.fragment("package_description"),

   133                     descriptionLabel, "", "");

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

   135             div.addContent(descPara);

   136         }

   137         bodyTree.addContent(div);

   138         return bodyTree;

   139     }

   140 

   141     /**

   142      * {@inheritDoc}

   143      */

   144     public Content getContentHeader() {

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

   146         div.addStyle(HtmlStyle.contentContainer);

   147         return div;

   148     }

   149 

   150     /**

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

   152      *

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

   154      */

   155     public void addDeprecationInfo(Content div) {

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

   157         if (Util.isDeprecated(packageDoc)) {

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

   159             deprDiv.addStyle(HtmlStyle.deprecatedContent);

   160             Content deprPhrase = HtmlTree.SPAN(HtmlStyle.strong, deprecatedPhrase);

   161             deprDiv.addContent(deprPhrase);

   162             if (deprs.length > 0) {

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

   164                 if (commentTags.length > 0) {

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

   166                 }

   167             }

   168             div.addContent(deprDiv);

   169         }

   170     }

   171 

   172     /**

   173      * {@inheritDoc}

   174      */

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

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

   177         addClassesSummary(classes, label, tableSummary, tableHeader,

   178                 packageSummaryContentTree, profileValue);

   179     }

   180 

   181     /**

   182      * {@inheritDoc}

   183      */

   184     public Content getSummaryHeader() {

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

   186         ul.addStyle(HtmlStyle.blockList);

   187         return ul;

   188     }

   189 

   190     /**

   191      * {@inheritDoc}

   192      */

   193     public void addPackageDescription(Content packageContentTree) {

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

   195             packageContentTree.addContent(getMarkerAnchor("package_description"));

   196             Content h2Content = new StringContent(

   197                     configuration.getText("doclet.Package_Description",

   198                     packageDoc.name()));

   199             packageContentTree.addContent(HtmlTree.HEADING(HtmlConstants.PACKAGE_HEADING,

   200                     true, h2Content));

   201             addInlineComment(packageDoc, packageContentTree);

   202         }

   203     }

   204 

   205     /**

   206      * {@inheritDoc}

   207      */

   208     public void addPackageTags(Content packageContentTree) {

   209         addTagsInfo(packageDoc, packageContentTree);

   210     }

   211 

   212     /**

   213      * {@inheritDoc}

   214      */

   215     public void addPackageFooter(Content contentTree) {

   216         addNavLinks(false, contentTree);

   217         addBottom(contentTree);

   218     }

   219 

   220     /**

   221      * {@inheritDoc}

   222      */

   223     public void printDocument(Content contentTree) throws IOException {

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

   225                 true, contentTree);

   226     }

   227 

   228     /**

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

   230      *

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

   232      */

   233     protected Content getNavLinkClassUse() {

   234         Content useLink = getHyperLink(DocPaths.PACKAGE_USE,

   235                 useLabel, "", "");

   236         Content li = HtmlTree.LI(useLink);

   237         return li;

   238     }

   239 

   240     /**

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

   242      *

   243      * @return a content tree for the previous link

   244      */

   245     public Content getNavLinkPrevious() {

   246         Content li;

   247         if (prev == null) {

   248             li = HtmlTree.LI(prevpackageLabel);

   249         } else {

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

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

   252                 prevpackageLabel, "", ""));

   253         }

   254         return li;

   255     }

   256 

   257     /**

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

   259      *

   260      * @return a content tree for the next link

   261      */

   262     public Content getNavLinkNext() {

   263         Content li;

   264         if (next == null) {

   265             li = HtmlTree.LI(nextpackageLabel);

   266         } else {

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

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

   269                 nextpackageLabel, "", ""));

   270         }

   271         return li;

   272     }

   273 

   274     /**

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

   276      * tree file.

   277      *

   278      * @return a content tree for the tree link

   279      */

   280     protected Content getNavLinkTree() {

   281         Content useLink = getHyperLink(DocPaths.PACKAGE_TREE,

   282                 treeLabel, "", "");

   283         Content li = HtmlTree.LI(useLink);

   284         return li;

   285     }

   286 

   287     /**

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

   289      *

   290      * @return a content tree for the package link

   291      */

   292     protected Content getNavLinkPackage() {

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

   294         return li;

   295     }

   296 }