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 }