/*

 * Copyright (c) 2001, 2017, Oracle and/or its affiliates. All rights reserved.

 * 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.tool;

import java.io.IOException;

import java.util.ArrayList;

import java.util.Collection;

import java.util.Collections;

import java.util.EnumMap;

import java.util.EnumSet;

import java.util.HashMap;

import java.util.HashSet;

import java.util.LinkedHashMap;

import java.util.LinkedHashSet;

import java.util.List;

import java.util.Map;

import java.util.Set;

import javax.lang.model.element.Element;

import javax.lang.model.element.ElementKind;

import javax.lang.model.element.Modifier;

import javax.lang.model.element.ModuleElement;

import javax.lang.model.element.ModuleElement.ExportsDirective;

import javax.lang.model.element.ModuleElement.RequiresDirective;

import javax.lang.model.element.PackageElement;

import javax.lang.model.element.TypeElement;

import javax.lang.model.util.ElementFilter;

import javax.lang.model.util.SimpleElementVisitor9;

import javax.tools.JavaFileManager;

import javax.tools.JavaFileManager.Location;

import javax.tools.JavaFileObject;

import javax.tools.StandardLocation;

import com.sun.tools.javac.code.Kinds.Kind;

import com.sun.tools.javac.code.Source;

import com.sun.tools.javac.code.Source.Feature;

import com.sun.tools.javac.code.Symbol;

import com.sun.tools.javac.code.Symbol.ClassSymbol;

import com.sun.tools.javac.code.Symbol.CompletionFailure;

import com.sun.tools.javac.code.Symbol.ModuleSymbol;

import com.sun.tools.javac.code.Symbol.PackageSymbol;

import com.sun.tools.javac.code.Symtab;

import com.sun.tools.javac.comp.Modules;

import com.sun.tools.javac.main.JavaCompiler;

import com.sun.tools.javac.tree.JCTree.JCClassDecl;

import com.sun.tools.javac.tree.JCTree.JCCompilationUnit;

import com.sun.tools.javac.tree.JCTree.JCModuleDecl;

import com.sun.tools.javac.tree.TreeInfo;

import com.sun.tools.javac.util.Context;

import com.sun.tools.javac.util.ListBuffer;

import com.sun.tools.javac.util.Name;

import com.sun.tools.javac.util.Names;

import jdk.javadoc.doclet.DocletEnvironment;

import jdk.javadoc.doclet.DocletEnvironment.ModuleMode;

import static com.sun.tools.javac.code.Scope.LookupKind.NON_RECURSIVE;

import static javax.lang.model.util.Elements.Origin.*;

import static javax.tools.JavaFileObject.Kind.*;

import static jdk.javadoc.internal.tool.Main.Result.*;

import static jdk.javadoc.internal.tool.JavadocTool.isValidClassName;

/**

 * This class manages elements specified on the command line, and

 * produces "specified" and "included" data sets, needed by the

 * doclet environment, as well as querying an elements' visibility

 * or inclusion.

 *

 * A. Initialization phase: the class is initialized with the

 *    options table by the caller. Some program elements may not

 *    be specified via specific options, such as packages, classes,

 *    these are set with the use of setter methods, such setClassArgList

 *    and setClassDeclList.

 *

 * B. Scan and decode phase: this is performed by scanSpecifiedItems,

 *    to identify the modules specified on the command line, modules

 *    specified with qualified packages and qualified subpackages, the

 *    modules so identified are used to initialize the module system.

 *

 * C. Intermediate phase: before the final analysis can be done,

 *    intermediate methods can be used to get specified elements from

 *    the initialization phase, typically used to parse sources or packages

 *    specified on the command line.

 *

 * D. Analysis phase: the final analysis is performed to determine

 *    the packages that ought to be included, as follows:

 *

 *    1. computes the specified modules, by considering the option

 *       "expand-requires", this must be done exhaustively, as the package

 *       computation phase expects a completed module graph, in order to

 *       check the target of a qualified export is in the included set.

 *

 *    2. computes the packages that must be documented, by considering

 *       the option "show-packages", also if only exported packages are

 *       to be considered, then also check for qualified packages, and

 *       include only those packages whose target is in the included set.

 *

 *    3. compute the specified packages, as part of this, first compute

 *       the subpackages and exclude any packages, if required.

 *

 *    4. Finally, compute the types found by previous parsing steps,

 *       noting that, all enclosed types (nested types) must also be

 *       considered.

 *

 * E. Finally, this class provides methods to obtain the specified sets,

 *    which are frozen and cached in the analysis phase, the included

 *    sets, are computed lazily and cached for future use. An element

 *    can be checked if it should be documented, in which case, the

 *    element is checked against the included set and the result is

 *    cached, for performance reasons.

 *

 * Definitions:

 *    Fully included: an element is included and some or parts

 *    of it components are included implicitly, subject to a

 *    selection criteria of its enclosed children.

 *

 *    Included: if the item should be documented.

 *

 * Rules for processing:

 *

 * 1. A specified element, meaning an element given on the

 *    command-line, and exposed via specified elements collections.

 * 2. Expand-contents, an internal pseudo term, meaning

 *    it is part of the recursive expansion of specified

 *    elements, meaning, the modules are expanded first, then

 *    the packages contained in the expanded modules, and then

 *    the types contained within the packages, to produce the

 *    collections returned by the methods

 *    getInclude{Module|Package|Type}Elements(), this is a

 *    downward expansion.

 * 3. An included element, meaning it should be documented, and

 *    exposed via isIncluded, this enclosing element (module, package)

 *    is recursively included.

 */

public class ElementsTable {

    private final ToolEnvironment toolEnv;

    private final Symtab syms;

    private final Names names;

    private final JavaFileManager fm;

    private final List<Location> locations;

    private final Modules modules;

    private final Map<ToolOption, Object> opts;

    private final Messager messager;

    private final JavaCompiler compiler;

    private final Map<String, Entry> entries = new LinkedHashMap<>();

    // specified elements

    private Set<ModuleElement> specifiedModuleElements = new LinkedHashSet<>();

    private Set<PackageElement> specifiedPackageElements = new LinkedHashSet<>();

    private Set<TypeElement> specifiedTypeElements =new LinkedHashSet<>();

    // included elements

    private Set<ModuleElement> includedModuleElements = null;

    private Set<PackageElement> includedPackageElements = null;

    private Set<TypeElement> includedTypeElements = null;

    // cmdline specifiers

    private Set<ModulePackage> cmdLinePackages = new LinkedHashSet<>();

    private Set<ModulePackage> excludePackages = new LinkedHashSet<>();

    private Set<ModulePackage> subPackages = new LinkedHashSet<>();

    private List<JCClassDecl> classDecList = Collections.emptyList();

    private List<String> classArgList = Collections.emptyList();

    private com.sun.tools.javac.util.List<JCCompilationUnit> classTreeList = null;

    private final Set<JavaFileObject.Kind> sourceKinds = EnumSet.of(JavaFileObject.Kind.SOURCE);

    private final ModifierFilter accessFilter;

    private final AccessKind expandRequires;

    final boolean xclasses;

    /**

     * Creates the table to manage included and excluded elements.

     *

     * @param context the context to locate commonly used objects

     * @param location the location used to locate source files

     */

    ElementsTable(Context context, Map<ToolOption, Object> opts) {

        this.toolEnv = ToolEnvironment.instance(context);

        this.syms = Symtab.instance(context);

        this.names = Names.instance(context);

        this.fm = toolEnv.fileManager;

        this.modules = Modules.instance(context);

        this.opts = opts;

        this.messager = Messager.instance0(context);

        this.compiler = JavaCompiler.instance(context);

        Source source = Source.instance(context);

        List<Location> locs = new ArrayList<>();

        if (modules.multiModuleMode) {

            locs.add(StandardLocation.MODULE_SOURCE_PATH);

        } else {

            if (toolEnv.fileManager.hasLocation(StandardLocation.SOURCE_PATH))

                locs.add(StandardLocation.SOURCE_PATH);

            else

                locs.add(StandardLocation.CLASS_PATH);

        }

        if (Feature.MODULES.allowedInSource(source) && toolEnv.fileManager.hasLocation(StandardLocation.PATCH_MODULE_PATH))

            locs.add(StandardLocation.PATCH_MODULE_PATH);

        this.locations = Collections.unmodifiableList(locs);

        getEntry("").excluded = false;

        accessFilter = new ModifierFilter(opts);

        xclasses = (boolean)opts.getOrDefault(ToolOption.XCLASSES, false);

        expandRequires = (AccessKind)opts.get(ToolOption.EXPAND_REQUIRES);

    }

    /**

     * Returns the module documentation level mode.

     * @return the module documentation level mode

     */

    public ModuleMode getModuleMode() {

        switch(accessFilter.getAccessValue(ElementKind.MODULE)) {

            case PACKAGE: case PRIVATE:

                return DocletEnvironment.ModuleMode.ALL;

            default:

                return DocletEnvironment.ModuleMode.API;

        }

    }

    private Set<Element> specifiedElements = null;

    /**

     * Returns a set of elements specified on the

     * command line, including any inner classes.

     *

     * @return the set of elements specified on the command line

     */

    public Set<? extends Element> getSpecifiedElements() {

        if (specifiedElements == null) {

            Set<Element> result = new LinkedHashSet<>();

            result.addAll(specifiedModuleElements);

            result.addAll(specifiedPackageElements);

            result.addAll(specifiedTypeElements);

            specifiedElements = Collections.unmodifiableSet(result);

        }

        return specifiedElements;

    }

    private Set<Element> includedElements = null;

    /**

     * Returns a set of elements included elements. The inclusion is as

     * follows:

     * A module is fully included,

     *   - is specified on the command line --module

     *   - is derived from the module graph, that is, by expanding the

     *     requires directive, based on --expand-requires

     *

     * A module is included if an enclosed package or type is

     * specified on the command line.

     *

     * A package is fully included,

     *  - is specified on the command line

     *  - is derived from expanding -subpackages

     *  - can be documented in a fully included module based on --show-packages

     *

     * A package is included, if an enclosed package or a type is specified on

     * the command line.

     *

     * Included type elements (including those within specified or included packages)

     * to be documented.

     *

     * A type is fully included if

     *  - is specified on the command line with -sourcepath

     *  - is visible with --show-types filter

     * A nested type is fully included if

     *  - is visible with --show-types filter

     *  - is enclosed in a fully included type

     * @return the set of elements specified on the command line

     */

    public Set<? extends Element> getIncludedElements() {

        if (includedElements == null) {

            Set<Element> result = new LinkedHashSet<>();

            result.addAll(includedModuleElements);

            result.addAll(includedPackageElements);

            result.addAll(includedTypeElements);

            includedElements = Collections.unmodifiableSet(result);

        }

        return includedElements;

    }

    private IncludedVisitor includedVisitor = null;

    /**

     * Returns true if the given element is included for consideration.

     * This method accumulates elements in the cache as enclosed elements of

     * fully included elements are tested.

     * A member (constructor, method, field) is included if

     *  - it is visible in a fully included type (--show-members)

     *

     * @param e the element in question

     *

     * @see getIncludedModuleElements

     * @see getIncludedPackageElements

     * @see getIncludedTypeElements

     *

     * @return true if included

     */

    public boolean isIncluded(Element e) {

        if (e == null) {

            return false;

        }

        if (includedVisitor == null) {

            includedVisitor = new IncludedVisitor();

        }

        return includedVisitor.visit(e);

    }

    /**

     * Performs the final computation and freezes the collections.

     * This is a terminal operation, thus no further modifications

     * are allowed to the specified data sets.

     *

     * @throws ToolException if an error occurs

     */

    void analyze() throws ToolException {

        // compute the specified element, by expanding module dependencies

        computeSpecifiedModules();

        // compute all specified packages and subpackages

        computeSpecifiedPackages();

        // compute the specified types

        computeSpecifiedTypes();

        // compute the packages belonging to all the specified modules

        Set<PackageElement> expandedModulePackages = computeModulePackages();

        initializeIncludedSets(expandedModulePackages);

    }

    ElementsTable classTrees(com.sun.tools.javac.util.List<JCCompilationUnit> classTrees) {

        this.classTreeList = classTrees;

        return this;

    }

    /*

     * This method sanity checks the following cases:

     * a. a source-path containing a single module and many modules specified with --module

     * b. no modules on source-path

     * c. mismatched source-path and many modules specified with --module

     */

    void sanityCheckSourcePathModules(List<String> moduleNames) throws ToolException {

        if (!haveSourceLocationWithModule)

            return;

        if (moduleNames.size() > 1) {

            String text = messager.getText("main.cannot_use_sourcepath_for_modules",

                    String.join(", ", moduleNames));

            throw new ToolException(CMDERR, text);

        }

        String foundModule = getModuleName(StandardLocation.SOURCE_PATH);

        if (foundModule == null) {

            String text = messager.getText("main.module_not_found_on_sourcepath", moduleNames.get(0));

            throw new ToolException(CMDERR, text);

        }

        if (!moduleNames.get(0).equals(foundModule)) {

            String text = messager.getText("main.sourcepath_does_not_contain_module", moduleNames.get(0));

            throw new ToolException(CMDERR, text);

        }

    }

    private String getModuleName(Location location) throws ToolException {

        try {

            JavaFileObject jfo = fm.getJavaFileForInput(location,

                    "module-info", JavaFileObject.Kind.SOURCE);

            if (jfo != null) {

                JCCompilationUnit jcu = compiler.parse(jfo);

                JCModuleDecl module = TreeInfo.getModule(jcu);

                if (module != null) {

                    return module.getName().toString();

                }

            }

        } catch (IOException ioe) {

            String text = messager.getText("main.file.manager.list", location);

            throw new ToolException(SYSERR, text, ioe);

        }

        return null;

    }

    @SuppressWarnings("unchecked")

    ElementsTable scanSpecifiedItems() throws ToolException {

        // scan modules specified on the command line

        List<String> moduleNames = (List<String>) opts.computeIfAbsent(ToolOption.MODULE,

                s -> Collections.EMPTY_LIST);

        List<String> mlist = new ArrayList<>();

        for (String m : moduleNames) {

            List<Location> moduleLocations = getModuleLocation(locations, m);

            if (moduleLocations.isEmpty()) {

                String text = messager.getText("main.module_not_found", m);

                throw new ToolException(CMDERR, text);

            }

            if (moduleLocations.contains(StandardLocation.SOURCE_PATH)) {

                sanityCheckSourcePathModules(moduleNames);

            }

            mlist.add(m);

            ModuleSymbol msym = syms.enterModule(names.fromString(m));

            specifiedModuleElements.add((ModuleElement) msym);

        }

        // scan for modules with qualified packages

        cmdLinePackages.stream()

                .filter((mpkg) -> (mpkg.hasModule()))

                .forEachOrdered((mpkg) -> {

                    mlist.add(mpkg.moduleName);

        });

        // scan for modules with qualified subpackages

        ((List<String>)opts.computeIfAbsent(ToolOption.SUBPACKAGES, v -> Collections.EMPTY_LIST))

            .stream()

            .map(ModulePackage::new)

            .forEachOrdered((mpkg) -> {

                subPackages.add(mpkg);

                if (mpkg.hasModule()) {

                    mlist.add(mpkg.moduleName);

                }

            });

        // all the modules specified on the command line have been scraped

        // init the module systems

        modules.addExtraAddModules(mlist.toArray(new String[mlist.size()]));

        modules.initModules(this.classTreeList);

        return this;

    }

    /**

     * Returns the includes table after setting a class names specified on the command line.

     *

     * @param classList

     * @return the include table

     */

    ElementsTable setClassArgList(List<String> classList) {

        classArgList = classList;

        return this;

    }

    /**

     * Returns the includes table after setting the parsed class names.

     *

     * @param classesDecList

     * @return the include table

     */

    ElementsTable setClassDeclList(List<JCClassDecl> classesDecList) {

        this.classDecList = classesDecList;

        return this;

    }

    /**

     * Returns an includes table after setting the specified package

     * names.

     * @param packageNames packages on the command line

     * @return the includes table after setting the specified package

     * names

     */

    ElementsTable packages(Collection<String> packageNames) {

        packageNames.stream()

            .map(ModulePackage::new)

            .forEachOrdered((mpkg) -> cmdLinePackages.add(mpkg));

        return this;

    }

    /**

     * Returns the aggregate set of included packages and specified

     * sub packages.

     *

     * @return the aggregate set of included packages and specified

     * sub packages

     */

    Iterable<ModulePackage> getPackagesToParse() throws IOException {

        List<ModulePackage> result = new ArrayList<>();

        result.addAll(cmdLinePackages);

        result.addAll(subPackages);

        return result;

    }

    @SuppressWarnings("unchecked")

    private void computeSubpackages() throws ToolException {

        ((List<String>) opts.computeIfAbsent(ToolOption.EXCLUDE, v -> Collections.EMPTY_LIST))

                .stream()

                .map(ModulePackage::new)

                .forEachOrdered((mpkg) -> excludePackages.add(mpkg));

        excludePackages.forEach((p) -> {

            getEntry(p).excluded = true;