1 /*
   2  * Copyright (c) 2013, 2018, 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.HtmlConstants;
  37 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
  38 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
  39 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
  40 import jdk.javadoc.internal.doclets.formats.html.markup.Links;
  41 import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
  42 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
  43 import jdk.javadoc.internal.doclets.toolkit.Content;
  44 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
  45 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
  46 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
  47 
  48 /**
  49  * Generate the module package index for the left-hand frame in the generated output.
  50  * A click on the package name in this frame will update the page in the bottom
  51  * left hand frame with the listing of contents of the clicked module package.
  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 Bhavesh Patel
  59  */
  60 public class ModulePackageIndexFrameWriter extends AbstractModuleIndexWriter {
  61 
  62     /**
  63      * Construct the ModulePackageIndexFrameWriter object.
  64      *
  65      * @param configuration the configuration object
  66      * @param filename Name of the package index file to be generated.
  67      */
  68     public ModulePackageIndexFrameWriter(HtmlConfiguration configuration, DocPath filename)  {
  69         super(configuration, filename);
  70     }
  71 
  72     /**
  73      * Generate the module package index file.
  74      * @throws DocFileIOException
  75      * @param configuration the configuration object
  76      * @param mdle the module being documented
  77      */
  78     public static void generate(HtmlConfiguration configuration, ModuleElement mdle) throws DocFileIOException {
  79         DocPath filename = configuration.docPaths.moduleFrame(mdle);
  80         ModulePackageIndexFrameWriter modpackgen = new ModulePackageIndexFrameWriter(configuration, filename);
  81         modpackgen.buildModulePackagesIndexFile("doclet.Window_Overview", false, mdle);
  82     }
  83 
  84     /**
  85      * {@inheritDoc}
  86      */
  87     protected void addModulePackagesList(Map<ModuleElement, Set<PackageElement>> modules, String text,
  88             String tableSummary, Content body, ModuleElement mdle) {
  89         Content profNameContent = new StringContent(mdle.getQualifiedName().toString());
  90         Content heading = HtmlTree.HEADING(HtmlConstants.PACKAGE_HEADING, true,
  91                 getTargetModuleLink("classFrame", profNameContent, mdle));
  92         heading.addContent(Contents.SPACE);
  93         heading.addContent(contents.packagesLabel);
  94         HtmlTree htmlTree = (configuration.allowTag(HtmlTag.MAIN))
  95                 ? HtmlTree.MAIN(HtmlStyle.indexContainer, heading)
  96                 : HtmlTree.DIV(HtmlStyle.indexContainer, heading);
  97         HtmlTree ul = new HtmlTree(HtmlTag.UL);
  98         ul.setTitle(contents.packagesLabel);
  99         List<PackageElement> packages = new ArrayList<>(modules.get(mdle));
 100         for (PackageElement pkg : packages) {
 101             if ((!(configuration.nodeprecated && utils.isDeprecated(pkg)))) {
 102                 ul.addContent(getPackage(pkg, mdle));
 103             }
 104         }
 105         htmlTree.addContent(ul);
 106         body.addContent(htmlTree);
 107     }
 108 
 109     /**
 110      * {@inheritDoc}
 111      */
 112     protected void addModulePackagesList(Set<ModuleElement> modules, String text,
 113             String tableSummary, Content body, ModuleElement mdle) {
 114         Content moduleNameContent = new StringContent(mdle.getQualifiedName().toString());
 115         Content heading = HtmlTree.HEADING(HtmlConstants.PACKAGE_HEADING, true,
 116                 getTargetModuleLink("classFrame", moduleNameContent, mdle));
 117         heading.addContent(Contents.SPACE);
 118         heading.addContent(contents.packagesLabel);
 119         HtmlTree htmlTree = (configuration.allowTag(HtmlTag.MAIN))
 120                 ? HtmlTree.MAIN(HtmlStyle.indexContainer, heading)
 121                 : HtmlTree.DIV(HtmlStyle.indexContainer, heading);
 122         HtmlTree ul = new HtmlTree(HtmlTag.UL);
 123         ul.setTitle(contents.packagesLabel);
 124         Set<PackageElement> modulePackages = configuration.modulePackages.get(mdle);
 125         for (PackageElement pkg: modulePackages) {
 126             if ((!(configuration.nodeprecated && utils.isDeprecated(pkg)))) {
 127                 ul.addContent(getPackage(pkg, mdle));
 128             }
 129         }
 130         htmlTree.addContent(ul);
 131         body.addContent(htmlTree);
 132     }
 133 
 134     /**
 135      * Returns each package name as a separate link.
 136      *
 137      * @param pkg PackageElement
 138      * @param mdle the module being documented
 139      * @return content for the package link
 140      */
 141     protected Content getPackage(PackageElement pkg, ModuleElement mdle) {
 142         Content packageLinkContent;
 143         Content pkgLabel;
 144         if (!pkg.isUnnamed()) {
 145             pkgLabel = getPackageLabel(utils.getPackageName(pkg));
 146             packageLinkContent = links.createLink(pathString(pkg,
 147                      DocPaths.PACKAGE_FRAME), pkgLabel, "",
 148                     "packageFrame");
 149         } else {
 150             pkgLabel = new StringContent("<unnamed package>");
 151             packageLinkContent = links.createLink(DocPaths.PACKAGE_FRAME,
 152                     pkgLabel, "", "packageFrame");
 153         }
 154         Content li = HtmlTree.LI(packageLinkContent);
 155         return li;
 156     }
 157 
 158     /**
 159      * {@inheritDoc}
 160      */
 161     protected void addNavigationBarHeader(Content body) {
 162         Content headerContent;
 163         if (configuration.packagesheader.length() > 0) {
 164             headerContent = new RawHtml(replaceDocRootDir(configuration.packagesheader));
 165         } else {
 166             headerContent = new RawHtml(replaceDocRootDir(configuration.header));
 167         }
 168         Content heading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, true,
 169                 HtmlStyle.bar, headerContent);
 170         body.addContent(heading);
 171     }
 172 
 173     /**
 174      * Do nothing as there is no overview information in this page.
 175      */
 176     protected void addOverviewHeader(Content body) {
 177     }
 178 
 179     /**
 180      * Do nothing as there is no modules list on this page.
 181      */
 182     protected void addModulesList(Content body) {
 183     }
 184 
 185     /**
 186      * Adds "All Classes" link for the top of the left-hand frame page to the
 187      * documentation tree.
 188      *
 189      * @param ul the Content object to which the all classes link should be added
 190      */
 191     protected void addAllClassesLink(Content ul) {
 192         Content linkContent = links.createLink(DocPaths.ALLCLASSES_FRAME,
 193                 contents.allClassesLabel, "", "packageFrame");
 194         Content li = HtmlTree.LI(linkContent);
 195         ul.addContent(li);
 196     }
 197 
 198     /**
 199      * Adds "All Packages" link for the top of the left-hand frame page to the
 200      * documentation tree.
 201      *
 202      * @param ul the Content object to which the all packages link should be added
 203      */
 204     protected void addAllPackagesLink(Content ul) {
 205         Content linkContent = links.createLink(DocPaths.OVERVIEW_FRAME,
 206                 contents.allPackagesLabel, "", "packageListFrame");
 207         Content li = HtmlTree.LI(linkContent);
 208         ul.addContent(li);
 209     }
 210 
 211     /**
 212      * Adds "All Modules" link for the top of the left-hand frame page to the
 213      * documentation tree.
 214      *
 215      * @param ul the Content object to which the all modules link should be added
 216      */
 217     protected void addAllModulesLink(Content ul) {
 218         Content linkContent = links.createLink(DocPaths.MODULE_OVERVIEW_FRAME,
 219                 contents.allModulesLabel, "", "packageListFrame");
 220         Content li = HtmlTree.LI(linkContent);
 221         ul.addContent(li);
 222     }
 223 
 224     /**
 225      * {@inheritDoc}
 226      */
 227     protected void addNavigationBarFooter(Content body) {
 228         Content p = HtmlTree.P(Contents.SPACE);
 229         body.addContent(p);
 230     }
 231 }