1 /*
   2  * Copyright (c) 1998, 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.*;
  29 
  30 import javax.lang.model.element.PackageElement;
  31 
  32 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
  33 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
  34 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
  35 import jdk.javadoc.internal.doclets.formats.html.markup.Navigation;
  36 import jdk.javadoc.internal.doclets.formats.html.markup.Navigation.PageMode;
  37 import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
  38 import jdk.javadoc.internal.doclets.toolkit.Content;
  39 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
  40 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
  41 
  42 /**
  43  * Abstract class to generate the overview files. This will be sub-classed to
  44  * generate overview-summary.html.
  45  *
  46  *  <p><b>This is NOT part of any supported API.
  47  *  If you write code that depends on this, you do so at your own risk.
  48  *  This code and its internal interfaces are subject to change or
  49  *  deletion without notice.</b>
  50  *
  51  * @author Atul M Dambalkar
  52  * @author Bhavesh Patel (Modified)
  53  */
  54 public abstract class AbstractPackageIndexWriter extends HtmlDocletWriter {
  55 
  56     /**
  57      * A Set of Packages to be documented.
  58      */
  59     protected SortedSet<PackageElement> packages;
  60 
  61     protected Navigation navBar;
  62 
  63     /**
  64      * Constructor. Also initializes the packages variable.
  65      *
  66      * @param configuration  The current configuration
  67      * @param filename Name of the package index file to be generated.
  68      */
  69     public AbstractPackageIndexWriter(HtmlConfiguration configuration,
  70                                       DocPath filename) {
  71         super(configuration, filename);
  72         packages = configuration.packages;
  73         this.navBar = new Navigation(null, configuration, fixedNavDiv, PageMode.OVERVIEW, path);
  74     }
  75 
  76     /**
  77      * Adds the navigation bar header to the documentation tree.
  78      *
  79      * @param header the document tree to which the navigation bar header will be added
  80      */
  81     protected abstract void addNavigationBarHeader(Content header);
  82 
  83     /**
  84      * Adds the navigation bar footer to the documentation tree.
  85      *
  86      * @param body the document tree to which the navigation bar footer will be added
  87      */
  88     protected abstract void addNavigationBarFooter(Content body);
  89 
  90     /**
  91      * Adds the overview header to the documentation tree.
  92      *
  93      * @param footer the document tree to which the overview header will be added
  94      */
  95     protected abstract void addOverviewHeader(Content footer);
  96 
  97     /**
  98      * Adds the packages list to the documentation tree.
  99      *
 100      * @param main the document tree to which the packages list will be added
 101      */
 102     protected abstract void addPackagesList(Content main);
 103 
 104     /**
 105      * Generate and prints the contents in the package index file.
 106      *
 107      * @param title the title of the window
 108      * @param description the content for the description META tag
 109      * @throws DocFileIOException if there is a problem building the package index file
 110      */
 111     protected void buildPackageIndexFile(String title, String description)
 112             throws DocFileIOException {
 113         String windowOverview = resources.getText(title);
 114         Content body = getBody(getWindowTitle(windowOverview));
 115         Content header = HtmlTree.HEADER();
 116         addNavigationBarHeader(header);
 117         Content main = HtmlTree.MAIN();
 118         addOverviewHeader(main);
 119         addIndex(header, main);
 120         addOverview(main);
 121         Content footer = HtmlTree.FOOTER();
 122         addNavigationBarFooter(footer);
 123         body.add(header);
 124         body.add(main);
 125         body.add(footer);
 126         printHtmlDocument(
 127                 configuration.metakeywords.getOverviewMetaKeywords(title, configuration.doctitle),
 128                 description, body);
 129     }
 130 
 131     /**
 132      * Default to no overview, override to add overview.
 133      *
 134      * @param main the document tree to which the overview will be added
 135      */
 136     protected void addOverview(Content main) { }
 137 
 138     /**
 139      * Adds the package index to the documentation tree.
 140      *
 141      * @param header the document tree to which the navigation links will be added
 142      * @param main the document tree to which the packages list will be added
 143      */
 144     protected void addIndex(Content header, Content main) {
 145         addIndexContents(header, main);
 146     }
 147 
 148     /**
 149      * Adds package index contents. Call appropriate methods from
 150      * the sub-classes. Adds it to the body HtmlTree
 151      *
 152      * @param header the document tree to which navigation links will be added
 153      * @param main the document tree to which the packages list will be added
 154      */
 155     protected void addIndexContents(Content header, Content main) {
 156         if (!packages.isEmpty()) {
 157             HtmlTree htmlTree = HtmlTree.NAV();
 158             htmlTree.setStyle(HtmlStyle.indexNav);
 159             HtmlTree ul = new HtmlTree(HtmlTag.UL);
 160             addAllClassesLink(ul);
 161             if (configuration.showModules  && configuration.modules.size() > 1) {
 162                 addAllModulesLink(ul);
 163             }
 164             htmlTree.add(ul);
 165             header.add(htmlTree);
 166             addPackagesList(main);
 167         }
 168     }
 169 
 170     /**
 171      * Adds the doctitle to the documentation tree, if it is specified on the command line.
 172      *
 173      * @param body the document tree to which the title will be added
 174      */
 175     protected void addConfigurationTitle(Content body) {
 176         if (configuration.doctitle.length() > 0) {
 177             Content title = new RawHtml(configuration.doctitle);
 178             Content heading = HtmlTree.HEADING(Headings.PAGE_TITLE_HEADING,
 179                     HtmlStyle.title, title);
 180             Content div = HtmlTree.DIV(HtmlStyle.header, heading);
 181             body.add(div);
 182         }
 183     }
 184 
 185     /**
 186      * Do nothing. This will be overridden.
 187      *
 188      * @param div the document tree to which the all classes link will be added
 189      */
 190     protected void addAllClassesLink(Content div) {
 191     }
 192 
 193     /**
 194      * Do nothing. This will be overridden.
 195      *
 196      * @param div the document tree to which the all modules link will be added
 197      */
 198     protected void addAllModulesLink(Content div) {
 199     }
 200 }