/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package jdk.javadoc.internal.doclets.formats.html;

import java.util.EnumSet;

import java.util.LinkedHashMap;

import java.util.List;

import java.util.Map;

import java.util.Set;

import java.util.SortedSet;

import java.util.TreeMap;

import java.util.TreeSet;

import javax.lang.model.element.Element;

import javax.lang.model.element.ModuleElement;

import javax.lang.model.element.PackageElement;

import javax.lang.model.element.TypeElement;

import javax.lang.model.util.ElementFilter;

import com.sun.source.doctree.DocTree;

import jdk.javadoc.doclet.DocletEnvironment.ModuleMode;

import jdk.javadoc.internal.doclets.formats.html.markup.HtmlAttr;

import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants;

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

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

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

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

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

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

import jdk.javadoc.internal.doclets.toolkit.ModuleSummaryWriter;

import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;

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

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

import jdk.javadoc.internal.doclets.toolkit.util.ModulePackageTypes;

/**

 * Class to generate file for each module contents in the right-hand frame. This will list all the

 * required modules, packages and service types for the module. A click on any of the links will update

 * the frame with the clicked element page.

 *

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

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

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

 *  deletion without notice.</b>

 *

 * @author Bhavesh Patel

 */

public class ModuleWriterImpl extends HtmlDocletWriter implements ModuleSummaryWriter {

    /**

     * The prev module name in the alpha-order list.

     */

    protected ModuleElement prevModule;

    /**

     * The next module name in the alpha-order list.

     */

    protected ModuleElement nextModule;

    /**

     * The module being documented.

     */

    protected ModuleElement mdle;

    /**

     * The module mode for this javadoc run. It can be set to "api" or "all".

     */

    private final ModuleMode moduleMode;

    /**

     * Map of module elements and modifiers required by this module.

     */

    private final Map<ModuleElement, Content> requires

            = new TreeMap<>(utils.makeModuleComparator());

    /**

     * Map of additional modules and modifiers, transitive closure, required by this module.

     */

    private final Map<ModuleElement, Content> additionalModules

            = new TreeMap<>(utils.makeModuleComparator());

    /**

     * Map of packages exported by this module and the modules it's been exported to.

     */

    private final Map<PackageElement, SortedSet<ModuleElement>> exportedPackages

            = new TreeMap<>(utils.makePackageComparator());

    /**

     * Map of opened packages by this module and the modules it's been opened to.

     */

    private final Map<PackageElement, SortedSet<ModuleElement>> openedPackages

            = new TreeMap<>(utils.makePackageComparator());

    /**

     * Set of concealed packages of this module.

     */

    private final SortedSet<PackageElement> concealedPackages = new TreeSet<>(utils.makePackageComparator());

    /**

     * Map of additional modules (transitive closure) and its exported packages.

     */

    private final Map<ModuleElement, SortedSet<PackageElement>> additionalPackages

            = new TreeMap<>(utils.makeModuleComparator());

    /**

     * Map of additional modules (transitive closure) and its open packages.

     */

    private final Map<ModuleElement, SortedSet<PackageElement>> additionalOpenPackages

            = new TreeMap<>(utils.makeModuleComparator());

    /**

     * Set of services used by the module.

     */

    private final SortedSet<TypeElement> uses

            = new TreeSet<>(utils.makeAllClassesComparator());

    /**

     * Map of services used by the module and specified using @uses javadoc tag, and description.

     */

    private final Map<TypeElement, Content> usesTrees

            = new TreeMap<>(utils.makeAllClassesComparator());

    /**

     * Map of services provided by this module, and set of its implementations.

     */

    private final Map<TypeElement, SortedSet<TypeElement>> provides

            = new TreeMap<>(utils.makeAllClassesComparator());

    /**

     * Map of services provided by the module and specified using @provides javadoc tag, and

     * description.

     */

    private final Map<TypeElement, Content> providesTrees

            = new TreeMap<>(utils.makeAllClassesComparator());

    private int packageTypesOr = 0;

    protected Set<ModulePackageTypes> modulePackageTypes = EnumSet.noneOf(ModulePackageTypes.class);

    protected Map<String, Integer> typeMap = new LinkedHashMap<>();

    /**

     * The HTML tree for main tag.

     */

    protected HtmlTree mainTree = HtmlTree.MAIN();

    /**

     * The HTML tree for section tag.

     */

    protected HtmlTree sectionTree = HtmlTree.SECTION();

    /**

     * Constructor to construct ModuleWriter object and to generate "moduleName-summary.html" file.

     *

     * @param configuration the configuration of the doclet.

     * @param mdle        Module under consideration.

     * @param prevModule   Previous module in the sorted array.

     * @param nextModule   Next module in the sorted array.

     */

    public ModuleWriterImpl(ConfigurationImpl configuration,

            ModuleElement mdle, ModuleElement prevModule, ModuleElement nextModule) {

        super(configuration, DocPaths.moduleSummary(mdle));

        this.prevModule = prevModule;

        this.nextModule = nextModule;

        this.mdle = mdle;

        this.moduleMode = configuration.docEnv.getModuleMode();

        computeModulesData();

    }

    /**

     * Get the module header.

     *

     * @param heading the heading for the section

     */

    @Override

    public Content getModuleHeader(String heading) {

        HtmlTree bodyTree = getBody(true, getWindowTitle(mdle.getQualifiedName().toString()));

        HtmlTree htmlTree = (configuration.allowTag(HtmlTag.HEADER))

                ? HtmlTree.HEADER()

                : bodyTree;

        addTop(htmlTree);

        addNavLinks(true, htmlTree);

        if (configuration.allowTag(HtmlTag.HEADER)) {

            bodyTree.addContent(htmlTree);

        }

        HtmlTree div = new HtmlTree(HtmlTag.DIV);

        div.addStyle(HtmlStyle.header);

        Content annotationContent = new HtmlTree(HtmlTag.P);

        addAnnotationInfo(mdle, annotationContent);

        div.addContent(annotationContent);

        Content tHeading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, true,

                HtmlStyle.title, contents.moduleLabel);

        tHeading.addContent(Contents.SPACE);

        Content moduleHead = new RawHtml(heading);

        tHeading.addContent(moduleHead);

        div.addContent(tHeading);

        if (configuration.allowTag(HtmlTag.MAIN)) {

            mainTree.addContent(div);

        } else {

            bodyTree.addContent(div);

        }

        return bodyTree;

    }

    /**

     * Get the content header.

     */

    @Override

    public Content getContentHeader() {

        HtmlTree div = new HtmlTree(HtmlTag.DIV);

        div.addStyle(HtmlStyle.contentContainer);

        return div;

    }

    /**

     * Get the summary section header.

     */

    @Override

    public Content getSummaryHeader() {

        HtmlTree li = new HtmlTree(HtmlTag.LI);

        li.addStyle(HtmlStyle.blockList);

        return li;

    }

    /**

     * Get the summary tree.

     *

     * @param summaryContentTree the content tree to be added to the summary tree.

     */

    @Override

    public Content getSummaryTree(Content summaryContentTree) {

        HtmlTree ul = HtmlTree.UL(HtmlStyle.blockList, summaryContentTree);

        return ul;

    }

    /**

     * Compute the modules data that will be displayed in various tables on the module summary page.

     */

    public void computeModulesData() {

        CommentHelper ch = utils.getCommentHelper(mdle);

        // Get module dependencies using the module's transitive closure.

        Map<ModuleElement, String> dependentModules = utils.getDependentModules(mdle);

        // Add all dependent modules to additional modules set. We will remove the modules,

        // listed using the requires directive, from this set to come up with the table of additional

        // required modules.

        dependentModules.forEach((module, mod) -> {

            if (shouldDocument(module)) {

                additionalModules.put(module, new StringContent(mod));

            }

        });

        (ElementFilter.requiresIn(mdle.getDirectives())).forEach((directive) -> {

            ModuleElement m = directive.getDependency();

            if (shouldDocument(m)) {

                if (moduleMode == ModuleMode.ALL || directive.isTransitive()) {

                    requires.put(m, new StringContent(utils.getModifiers(directive)));

            } else {

                // For api mode, just keep the public requires in dependentModules for display of

                    // additional packages in the "Packages" section.

                    dependentModules.remove(m);

            }

                additionalModules.remove(m);

        }

        });

        // Get all packages for the module and put it in the concealed packages set.

            if (shouldDocument(pkg)) {

                concealedPackages.add(pkg);

            }

        });

        // Get all exported packages for the module using the exports directive for the module.

        (ElementFilter.exportsIn(mdle.getDirectives())).forEach((directive) -> {

            PackageElement p = directive.getPackage();

            if (shouldDocument(p)) {

                SortedSet<ModuleElement> mdleList = new TreeSet<>(utils.makeModuleComparator());

                List<? extends ModuleElement> targetMdles = directive.getTargetModules();

                if (targetMdles != null) {

                    mdleList.addAll(targetMdles);

                }

                // Qualified exports should not be displayed in the api mode. So if mdleList is empty,

                // its exported to all modules and hence can be added.

                if (moduleMode == ModuleMode.ALL || mdleList.isEmpty()) {

                    exportedPackages.put(p, mdleList);

                }

                concealedPackages.remove(p);

            }

        });

        // Get all opened packages for the module using the opens directive for the module.

        (ElementFilter.opensIn(mdle.getDirectives())).forEach((directive) -> {

            PackageElement p = directive.getPackage();

            if (shouldDocument(p)) {

                SortedSet<ModuleElement> mdleList = new TreeSet<>(utils.makeModuleComparator());

                List<? extends ModuleElement> targetMdles = directive.getTargetModules();

                if (targetMdles != null) {

                    mdleList.addAll(targetMdles);

                }

                // Qualified opens should not be displayed in the api mode. So if mdleList is empty,

                // it's opened to all modules and hence can be added.

                if (moduleMode == ModuleMode.ALL || mdleList.isEmpty()) {

                    openedPackages.put(p, mdleList);

                }

                concealedPackages.remove(p);

            }

        });

        // Remove all the exported and opened packages so we have just the concealed packages now.

        concealedPackages.removeAll(exportedPackages.keySet());

        concealedPackages.removeAll(openedPackages.keySet());

        // Get all the exported and opened packages, for the transitive closure of the module, to be displayed in

        // the additional packages tables.

        dependentModules.forEach((module, mod) -> {

            SortedSet<PackageElement> pkgList = new TreeSet<>(utils.makePackageComparator());

            (ElementFilter.exportsIn(module.getDirectives())).forEach((directive) -> {

                PackageElement pkg = directive.getPackage();

                if (shouldDocument(pkg)) {

                    pkgList.add(pkg);

                }

            });

            // If none of the transitive modules have exported packages to be displayed, we should not be

            // displaying the table and so it should not be added to the map.

            if (!pkgList.isEmpty()) {

                additionalPackages.put(module, pkgList);

            }

            SortedSet<PackageElement> openPkgList = new TreeSet<>(utils.makePackageComparator());

            (ElementFilter.opensIn(module.getDirectives())).forEach((directive) -> {

                PackageElement pkg = directive.getPackage();

                if (shouldDocument(pkg)) {

                    openPkgList.add(pkg);

                }

            });

            // If none of the transitive modules have opened packages to be displayed, we should not be

            // displaying the table and so it should not be added to the map.

            if (!openPkgList.isEmpty()) {

                additionalOpenPackages.put(module, openPkgList);

            }

        });

        // Get all the services listed as uses directive.

        (ElementFilter.usesIn(mdle.getDirectives())).forEach((directive) -> {

            TypeElement u = directive.getService();

            if (shouldDocument(u)) {

                uses.add(u);

            }

        });

        // Get all the services and implementations listed as provides directive.

        (ElementFilter.providesIn(mdle.getDirectives())).forEach((directive) -> {

            TypeElement u = directive.getService();

            if (shouldDocument(u)) {

                List<? extends TypeElement> implList = directive.getImplementations();

                SortedSet<TypeElement> implSet = new TreeSet<>(utils.makeAllClassesComparator());

                implSet.addAll(implList);

                provides.put(u, implSet);

            }

        });

        // Generate the map of all services listed using @provides, and the description.

        (utils.getBlockTags(mdle, DocTree.Kind.PROVIDES)).forEach((tree) -> {

            TypeElement t = ch.getServiceType(configuration, tree);

            if (t != null) {

                providesTrees.put(t, commentTagsToContent(tree, mdle, ch.getDescription(configuration, tree), false));

            }

        });

        // Generate the map of all services listed using @uses, and the description.

        (utils.getBlockTags(mdle, DocTree.Kind.USES)).forEach((tree) -> {

            TypeElement t = ch.getServiceType(configuration, tree);

            if (t != null) {

                usesTrees.put(t, commentTagsToContent(tree, mdle, ch.getDescription(configuration, tree), false));

            }

        });

    }

    /**

     * Returns true if the element should be documented on the module summary page.

     *

     * @param element the element to be checked

     * @return true if the element should be documented

     */

    public boolean shouldDocument(Element element) {

        return (moduleMode == ModuleMode.ALL || utils.isIncluded(element));

    }

    /**

     * Returns true if there are elements to be displayed.

     *

     * @param section set of elements

     * @return true if there are elements to be displayed

     */

    public boolean display(SortedSet<? extends Element> section) {

        return section != null && !section.isEmpty();

    }

    /**

     * Returns true if there are elements to be displayed.

     *

     * @param section map of elements.

     * @return true if there are elements to be displayed

     */

    public boolean display(Map<? extends Element, ?> section) {

        return section != null && !section.isEmpty();

    }

    /**

     * Add the summary header.

     *

     * @param startMarker the marker comment

     * @param markerAnchor the marker anchor for the section

     * @param heading the heading for the section

     * @param htmltree the content tree to which the information is added

     */

    public void addSummaryHeader(Content startMarker, SectionName markerAnchor, Content heading, Content htmltree) {

        htmltree.addContent(startMarker);

        htmltree.addContent(getMarkerAnchor(markerAnchor));

        htmltree.addContent(HtmlTree.HEADING(HtmlTag.H3, heading));

    }

    /**

     * Get table header.

     *

     * @param text the table caption

     * @param tableSummary the summary for the table

     * @param tableStyle the table style

     * @param tableHeader the table header

     * @return a content object

     */

    public Content getTableHeader(String text, String tableSummary, HtmlStyle tableStyle,

            List<String> tableHeader) {

        return getTableHeader(getTableCaption(new RawHtml(text)), tableSummary, tableStyle, tableHeader);

    }

    /**

     * Get table header.

     *

     * @param caption the table caption

     * @param tableSummary the summary for the table

     * @param tableStyle the table style

     * @param tableHeader the table header

     * @return a content object

     */

    public Content getTableHeader(Content caption, String tableSummary, HtmlStyle tableStyle,

            List<String> tableHeader) {

        Content table = (configuration.isOutputHtml5())

                ? HtmlTree.TABLE(tableStyle, caption)

                : HtmlTree.TABLE(tableStyle, tableSummary, caption);

        table.addContent(getSummaryTableHeader(tableHeader, "col"));

        return table;

    }

    /**

     * {@inheritDoc}

     */

    public void addModulesSummary(Content summaryContentTree) {

        if (display(requires) || display(additionalModules)) {

            HtmlTree li = new HtmlTree(HtmlTag.LI);

            li.addStyle(HtmlStyle.blockList);

            addSummaryHeader(HtmlConstants.START_OF_MODULES_SUMMARY, SectionName.MODULES,

                    contents.navModules, li);

            if (display(requires)) {

            String text = configuration.getText("doclet.Requires_Summary");

            String tableSummary = configuration.getText("doclet.Member_Table_Summary",

                    configuration.getText("doclet.Requires_Summary"),

                    configuration.getText("doclet.modules"));

                Content table = getTableHeader(text, tableSummary, HtmlStyle.requiresSummary, requiresTableHeader);

                Content tbody = new HtmlTree(HtmlTag.TBODY);

                addModulesList(requires, tbody);

                table.addContent(tbody);

                li.addContent(table);

            }

            // Display additional modules table in both "api" and "all" mode.

            if (display(additionalModules)) {

                String amrText = configuration.getText("doclet.Additional_Modules_Required_Summary");

                String amrTableSummary = configuration.getText("doclet.Member_Table_Summary",

                        configuration.getText("doclet.Additional_Modules_Required_Summary"),

                        configuration.getText("doclet.modules"));

                Content amrTable = getTableHeader(amrText, amrTableSummary, HtmlStyle.requiresSummary, requiresTableHeader);

                Content amrTbody = new HtmlTree(HtmlTag.TBODY);

                addModulesList(additionalModules, amrTbody);

                amrTable.addContent(amrTbody);