/*

 * Copyright (c) 2001, 2016, 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.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.ExecutableElement;

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.element.VariableElement;

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.Flags;

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

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.MethodSymbol;

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

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

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

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

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

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

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

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 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

 * 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 Location location;

    private final Modules modules;

    private final Map<ToolOption, Object> opts;

    private final Messager messager;

    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.location = modules.multiModuleMode

                ? StandardLocation.MODULE_SOURCE_PATH

                : toolEnv.fileManager.hasLocation(StandardLocation.SOURCE_PATH)

                    ? StandardLocation.SOURCE_PATH

                    : StandardLocation.CLASS_PATH;

        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;

        }

    }

    /**

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

     *

     * 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

     */

    }

    private IncludedVisitor includedVisitor = null;

    /**

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

    }

    @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) {

            Location moduleLoc = getModuleLocation(location, m);

            if (moduleLoc == null) {

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

                throw new ToolException(CMDERR, text);

            } else {

                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((packageName) -> new ModulePackage(packageName))

            .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((packageName) -> new ModulePackage(packageName))

            .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((packageName) -> new ModulePackage(packageName))

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

        excludePackages.forEach((p) -> {

            getEntry(p).excluded = true;

        });

        for (ModulePackage modpkg : subPackages) {

            Location packageLocn = getLocation(modpkg);

            Iterable<JavaFileObject> list = null;

            try {

                list = fm.list(packageLocn, modpkg.packageName, sourceKinds, true);

            } catch (IOException ioe) {

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

                throw new ToolException(SYSERR, text, ioe);

            }

            for (JavaFileObject fo : list) {

                String binaryName = fm.inferBinaryName(packageLocn, fo);

                String pn = getPackageName(binaryName);

                String simpleName = getSimpleName(binaryName);

                Entry e = getEntry(pn);

                if (!e.isExcluded() && isValidClassName(simpleName)) {

                    ModuleSymbol msym = (modpkg.hasModule())

                            ? syms.getModule(names.fromString(modpkg.moduleName))

                            : findModuleOfPackageName(modpkg.packageName);

                    if (msym != null && !msym.isUnnamed()) {

                        syms.enterPackage(msym, names.fromString(pn));

                        ModulePackage npkg = new ModulePackage(msym.toString(), pn);

                        cmdLinePackages.add(npkg);

                    } else {

                        cmdLinePackages.add(e.modpkg);

                    }

                    e.files = (e.files == null

                            ? com.sun.tools.javac.util.List.of(fo)

                            : e.files.prepend(fo));

                }

            }

        }

    }

    /**

     * Returns the "requires" modules for the target module.

     * @param mdle the target module element

     * @param isPublic true gets all the public requires, otherwise

     *                 gets all the non-public requires

     *

     * @return a set of modules

     */

    private Set<ModuleElement> getModuleRequires(ModuleElement mdle, boolean isPublic) {

        Set<ModuleElement> result = new HashSet<>();

        for (RequiresDirective rd : ElementFilter.requiresIn(mdle.getDirectives())) {

            if (isPublic && rd.isPublic()) {

                result.add(rd.getDependency());

            }

            if (!isPublic && !rd.isPublic()) {

                result.add(rd.getDependency());

            }

        }

        return result;

    }

    private void computeSpecifiedModules() {

        if (expandRequires == null) { // no expansion requested

            specifiedModuleElements = Collections.unmodifiableSet(specifiedModuleElements);

            return;

        }

        final boolean expandAll = expandRequires.equals(AccessKind.PRIVATE)

                || expandRequires.equals(AccessKind.PACKAGE);

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

        ListBuffer<ModuleElement> queue = new ListBuffer<>();

        // expand each specified module

            result.add(mdle); // a specified module is included