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.Collection;
  29 import java.util.Map;
  30 import java.util.Set;
  31 import java.util.SortedMap;
  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.Navigation;
  40 import jdk.javadoc.internal.doclets.formats.html.markup.Navigation.PageMode;
  41 import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
  42 import jdk.javadoc.internal.doclets.toolkit.Content;
  43 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
  44 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
  45 
  46 /**
  47  * Abstract class to generate the module overview files.
  48  *
  49  *  <p><b>This is NOT part of any supported API.
  50  *  If you write code that depends on this, you do so at your own risk.
  51  *  This code and its internal interfaces are subject to change or
  52  *  deletion without notice.</b>
  53  *
  54  * @author Bhavesh Patel
  55  */
  56 public abstract class AbstractModuleIndexWriter extends HtmlDocletWriter {
  57 
  58     /**
  59      * Modules to be documented.
  60      */
  61     protected SortedMap<ModuleElement, Set<PackageElement>> modules;
  62 
  63     protected Navigation navBar;
  64 
  65     /**
  66      * Constructor. Also initializes the modules variable.
  67      *
  68      * @param configuration  The current configuration
  69      * @param filename Name of the module index file to be generated.
  70      */
  71     public AbstractModuleIndexWriter(HtmlConfiguration configuration,
  72                                       DocPath filename) {
  73         super(configuration, filename);
  74         modules = configuration.modulePackages;
  75         this.navBar = new Navigation(null, configuration, fixedNavDiv, PageMode.OVERVIEW, path);
  76     }
  77 
  78     /**
  79      * Adds the navigation bar header to the documentation tree.
  80      *
  81      * @param header the document tree to which the navigation bar header will be added
  82      */
  83     protected abstract void addNavigationBarHeader(Content header);
  84 
  85     /**
  86      * Adds the navigation bar footer to the documentation tree.
  87      *
  88      * @param footer the document tree to which the navigation bar footer will be added
  89      */
  90     protected abstract void addNavigationBarFooter(Content footer);
  91 
  92     /**
  93      * Adds the overview header to the documentation tree.
  94      *
  95      * @param main the document tree to which the overview header will be added
  96      */
  97     protected abstract void addOverviewHeader(Content main);
  98 
  99     /**
 100      * Adds the modules list to the documentation tree.
 101      *
 102      * @param main the document tree to which the modules list will be added
 103      */
 104     protected abstract void addModulesList(Content main);
 105 
 106     /**
 107      * Adds the module packages list to the documentation tree.
 108      *
 109      * @param modules the set of modules
 110      * @param text caption for the table
 111      * @param tableSummary summary for the table
 112      * @param main the document tree to which the modules list will be added
 113      * @param mdle the module being documented
 114      */
 115     protected abstract void addModulePackagesList(Map<ModuleElement, Set<PackageElement>> modules, String text,
 116             String tableSummary, Content main, ModuleElement mdle);
 117 
 118     /**
 119      * Generate and prints the contents in the module index file.
 120      *
 121      * @param title the title of the window
 122      * @param description the content for the description META tag
 123      * @throws DocFileIOException if there is a problem building the module index file
 124      */
 125     protected void buildModuleIndexFile(String title, String description)
 126             throws DocFileIOException {
 127         String windowOverview = resources.getText(title);
 128         Content body = getBody(getWindowTitle(windowOverview));
 129         Content header = HtmlTree.HEADER();
 130         addNavigationBarHeader(header);
 131         Content main = HtmlTree.MAIN();
 132         addOverviewHeader(main);
 133         addIndex(header, main);
 134         addOverview(main);
 135         Content footer = HtmlTree.FOOTER();
 136         addNavigationBarFooter(footer);
 137         body.add(header);
 138         body.add(main);
 139         body.add(footer);
 140         printHtmlDocument(
 141                 configuration.metakeywords.getOverviewMetaKeywords(title, configuration.doctitle),
 142                 description,
 143                 body);
 144     }
 145 
 146     /**
 147      * Generate and prints the contents in the module packages index file.
 148      *
 149      * @param title the title of the window.
 150      * @param description the content for the description META tag
 151      * @param mdle the name of the module being documented
 152      * @throws DocFileIOException if there is an exception building the module packages index file
 153      */
 154     protected void buildModulePackagesIndexFile(String title, String description,
 155              ModuleElement mdle) throws DocFileIOException {
 156         String windowOverview = resources.getText(title);
 157         Content body = getBody(getWindowTitle(windowOverview));
 158         Content header = HtmlTree.HEADER();
 159         addNavigationBarHeader(header);
 160         Content main = HtmlTree.MAIN();
 161         addOverviewHeader(main);
 162         addModulePackagesIndex(header, main, mdle);
 163         addOverview(main);
 164         Content footer = HtmlTree.FOOTER();
 165         addNavigationBarFooter(footer);
 166         body.add(header);
 167         body.add(main);
 168         body.add(footer);
 169         printHtmlDocument(
 170                 configuration.metakeywords.getOverviewMetaKeywords(title, configuration.doctitle),
 171                 description,
 172                 body);
 173     }
 174 
 175     /**
 176      * Default to no overview, override to add overview.
 177      *
 178      * @param main the document tree to which the overview will be added
 179      */
 180     protected void addOverview(Content main) { }
 181 
 182     /**
 183      * Adds the module index to the documentation tree.
 184      *
 185      * @param header the document tree to which the navigational links will be added
 186      * @param main the document tree to which the modules list will be added
 187      */
 188     protected void addIndex(Content header, Content main) {
 189         addIndexContents(configuration.modules, "doclet.Module_Summary",
 190                 resources.getText("doclet.Member_Table_Summary",
 191                 resources.getText("doclet.Module_Summary"),
 192                 resources.getText("doclet.modules")), header, main);
 193     }
 194 
 195     /**
 196      * Adds the module packages index to the documentation tree.
 197      *
 198      * @param header the document tree to which the navigational links will be added
 199      * @param main the document tree to which the module packages list will be added
 200      * @param mdle the module being documented
 201      */
 202     protected void addModulePackagesIndex(Content header, Content main, ModuleElement mdle) {
 203         addModulePackagesIndexContents("doclet.Module_Summary",
 204                 resources.getText("doclet.Member_Table_Summary",
 205                 resources.getText("doclet.Module_Summary"),
 206                 resources.getText("doclet.modules")), header, main, mdle);
 207     }
 208 
 209     /**
 210      * Adds module index contents. Call appropriate methods from
 211      * the sub-classes. Adds it to the body HtmlTree
 212      *
 213      * @param modules the modules to be documented
 214      * @param text string which will be used as the heading
 215      * @param tableSummary summary for the table
 216      * @param header the document tree to which the navigational links will be added
 217      * @param main the document tree to which the modules list will be added
 218      */
 219     protected void addIndexContents(Collection<ModuleElement> modules, String text,
 220             String tableSummary, Content header, Content main) {
 221         addModulesList(main);
 222     }
 223 
 224     /**
 225      * Adds module packages index contents. Call appropriate methods from
 226      * the sub-classes. Adds it to the body HtmlTree
 227      *
 228      * @param text string which will be used as the heading
 229      * @param tableSummary summary for the table
 230      * @param header the document tree to which the navigational links will be added
 231      * @param main the document tree to which the module packages list will be added
 232      * @param mdle the module being documented
 233      */
 234     protected void addModulePackagesIndexContents(String text,
 235             String tableSummary, Content header, Content main, ModuleElement mdle) {
 236         addModulePackagesList(modules, text, tableSummary, main, mdle);
 237     }
 238 
 239     /**
 240      * Adds the doctitle to the documentation tree, if it is specified on the command line.
 241      *
 242      * @param body the document tree to which the title will be added
 243      */
 244     protected void addConfigurationTitle(Content body) {
 245         if (configuration.doctitle.length() > 0) {
 246             Content title = new RawHtml(configuration.doctitle);
 247             Content heading = HtmlTree.HEADING(Headings.PAGE_TITLE_HEADING,
 248                     HtmlStyle.title, title);
 249             Content div = HtmlTree.DIV(HtmlStyle.header, heading);
 250             body.add(div);
 251         }
 252     }
 253 }