1 /*

     2  * Copyright (c) 2013, 2019, 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 jdk.javadoc.internal.doclets.formats.html;

    27 

    28 import java.util.ArrayList;

    29 import java.util.List;

    30 import java.util.Map;

    31 import java.util.Set;

    32 

    33 import javax.lang.model.element.ModuleElement;

    34 import javax.lang.model.element.PackageElement;

    35 

    36 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;

    37 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;

    38 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;

    39 import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;

    40 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;

    41 import jdk.javadoc.internal.doclets.toolkit.Content;

    42 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;

    43 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;

    44 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;

    45 

    46 /**

    47  * Generate the module package index for the left-hand frame in the generated output.

    48  * A click on the package name in this frame will update the page in the bottom

    49  * left hand frame with the listing of contents of the clicked module package.

    50  *

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

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

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

    54  *  deletion without notice.</b>

    55  *

    56  * @author Bhavesh Patel

    57  */

    58 public class ModulePackageIndexFrameWriter extends AbstractModuleIndexWriter {

    59     /**

    60      * The heading (h1 or h2) to use for the module packages list,

    61      * set by addNavigationBarHeader depending on whether or not there

    62      * is an additional initial heading.

    63      */

    64     private HtmlTag modulePackagesListHeading;

    65 

    66     /**

    67      * Construct the ModulePackageIndexFrameWriter object.

    68      *

    69      * @param configuration the configuration object

    70      * @param filename Name of the package index file to be generated.

    71      */

    72     public ModulePackageIndexFrameWriter(HtmlConfiguration configuration, DocPath filename)  {

    73         super(configuration, filename);

    74     }

    75 

    76     /**

    77      * Generate the module package index file.

    78      * @throws DocFileIOException

    79      * @param configuration the configuration object

    80      * @param mdle the module being documented

    81      */

    82     public static void generate(HtmlConfiguration configuration, ModuleElement mdle) throws DocFileIOException {

    83         DocPath filename = configuration.docPaths.moduleFrame(mdle);

    84         ModulePackageIndexFrameWriter modpackgen = new ModulePackageIndexFrameWriter(configuration, filename);

    85         modpackgen.buildModulePackagesIndexFile("doclet.Window_Overview",

    86                 getDescription("module package index", mdle) + " (frame)",

    87                 false,

    88                 mdle);

    89     }

    90 

    91     /**

    92      * {@inheritDoc}

    93      */

    94     protected void addModulePackagesList(Map<ModuleElement, Set<PackageElement>> modules, String text,

    95             String tableSummary, Content main, ModuleElement mdle) {

    96         Content profNameContent = new StringContent(mdle.getQualifiedName().toString());

    97         Content heading = HtmlTree.HEADING(modulePackagesListHeading, true,

    98                 getTargetModuleLink("classFrame", profNameContent, mdle));

    99         heading.add(Contents.SPACE);

   100         heading.add(contents.packagesLabel);

   101         HtmlTree htmlTree = HtmlTree.DIV(HtmlStyle.indexContainer, heading);

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

   103         ul.setTitle(contents.packagesLabel);

   104         List<PackageElement> packages = new ArrayList<>(modules.get(mdle));

   105         for (PackageElement pkg : packages) {

   106             if ((!(configuration.nodeprecated && utils.isDeprecated(pkg)))) {

   107                 ul.add(getPackage(pkg, mdle));

   108             }

   109         }

   110         htmlTree.add(ul);

   111         main.add(htmlTree);

   112     }

   113 

   114     /**

   115      * {@inheritDoc}

   116      */

   117     protected void addModulePackagesList(Set<ModuleElement> modules, String text,

   118             String tableSummary, Content body, ModuleElement mdle) {

   119         Content moduleNameContent = new StringContent(mdle.getQualifiedName().toString());

   120         Content heading = HtmlTree.HEADING(modulePackagesListHeading, true,

   121                 getTargetModuleLink("classFrame", moduleNameContent, mdle));

   122         heading.add(Contents.SPACE);

   123         heading.add(contents.packagesLabel);

   124         HtmlTree htmlTree = HtmlTree.MAIN(HtmlStyle.indexContainer, heading);

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

   126         ul.setTitle(contents.packagesLabel);

   127         Set<PackageElement> modulePackages = configuration.modulePackages.get(mdle);

   128         for (PackageElement pkg: modulePackages) {

   129             if ((!(configuration.nodeprecated && utils.isDeprecated(pkg)))) {

   130                 ul.add(getPackage(pkg, mdle));

   131             }

   132         }

   133         htmlTree.add(ul);

   134         body.add(htmlTree);

   135     }

   136 

   137     /**

   138      * Returns each package name as a separate link.

   139      *

   140      * @param pkg PackageElement

   141      * @param mdle the module being documented

   142      * @return content for the package link

   143      */

   144     protected Content getPackage(PackageElement pkg, ModuleElement mdle) {

   145         Content packageLinkContent;

   146         Content pkgLabel;

   147         if (!pkg.isUnnamed()) {

   148             pkgLabel = getPackageLabel(utils.getPackageName(pkg));

   149             packageLinkContent = links.createLink(pathString(pkg,

   150                      DocPaths.PACKAGE_FRAME), pkgLabel, "",

   151                     "packageFrame");

   152         } else {

   153             pkgLabel = new StringContent("<unnamed package>");

   154             packageLinkContent = links.createLink(DocPaths.PACKAGE_FRAME,

   155                     pkgLabel, "", "packageFrame");

   156         }

   157         Content li = HtmlTree.LI(packageLinkContent);

   158         return li;

   159     }

   160 

   161     /**

   162      * {@inheritDoc}

   163      */

   164     protected void addNavigationBarHeader(Content header) {

   165         String headerContent = !configuration.packagesheader.isEmpty() ? configuration.packagesheader

   166                 : configuration.header;

   167         if (!headerContent.isEmpty()) {

   168             Content heading = HtmlTree.HEADING(Headings.PAGE_TITLE_HEADING, true,

   169                     HtmlStyle.bar, new RawHtml(replaceDocRootDir(headerContent)));

   170             header.add(heading);

   171             modulePackagesListHeading = Headings.IndexFrames.PACKAGE_HEADING;

   172         } else {

   173             modulePackagesListHeading = Headings.PAGE_TITLE_HEADING;

   174         }

   175     }

   176 

   177     /**

   178      * Do nothing as there is no overview information in this page.

   179      */

   180     protected void addOverviewHeader(Content body) {

   181     }

   182 

   183     /**

   184      * Do nothing as there is no modules list on this page.

   185      */

   186     @Override

   187     protected void addModulesList(Content body) {

   188     }

   189 

   190     /**

   191      * Adds "All Classes" link for the top of the left-hand frame page to the

   192      * documentation tree.

   193      *

   194      * @param ul the Content object to which the all classes link should be added

   195      */

   196     protected void addAllClassesLink(Content ul) {

   197         DocPath allClassesFrame = configuration.useModuleDirectories

   198                 ? DocPaths.DOT_DOT.resolve(DocPaths.ALLCLASSES_FRAME)

   199                 : DocPaths.ALLCLASSES_FRAME;

   200         Content linkContent = links.createLink(allClassesFrame,

   201                 contents.allClassesLabel, "", "packageFrame");

   202         Content li = HtmlTree.LI(linkContent);

   203         ul.add(li);

   204     }

   205 

   206     /**

   207      * Adds "All Packages" link for the top of the left-hand frame page to the

   208      * documentation tree.

   209      *

   210      * @param ul the Content object to which the all packages link should be added

   211      */

   212     protected void addAllPackagesLink(Content ul) {

   213         DocPath overviewFrame = configuration.useModuleDirectories

   214                 ? DocPaths.DOT_DOT.resolve(DocPaths.OVERVIEW_FRAME)

   215                 : DocPaths.OVERVIEW_FRAME;

   216         Content linkContent = links.createLink(overviewFrame,

   217                 contents.allPackagesLabel, "", "packageListFrame");

   218         Content li = HtmlTree.LI(linkContent);

   219         ul.add(li);

   220     }

   221 

   222     /**

   223      * Adds "All Modules" link for the top of the left-hand frame page to the

   224      * documentation tree.

   225      *

   226      * @param ul the Content object to which the all modules link should be added

   227      */

   228     protected void addAllModulesLink(Content ul) {

   229         DocPath moduleOverviewFrame = configuration.useModuleDirectories

   230                 ? DocPaths.DOT_DOT.resolve(DocPaths.MODULE_OVERVIEW_FRAME)

   231                 : DocPaths.MODULE_OVERVIEW_FRAME;

   232         Content linkContent = links.createLink(moduleOverviewFrame,

   233                 contents.allModulesLabel, "", "packageListFrame");

   234         Content li = HtmlTree.LI(linkContent);

   235         ul.add(li);

   236     }

   237 

   238     /**

   239      * {@inheritDoc}

   240      */

   241     protected void addNavigationBarFooter(Content footer) {

   242         Content p = HtmlTree.P(Contents.SPACE);

   243         footer.add(p);

   244     }

   245 }