/*

 * Copyright (c) 1999, 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.doclets.toolkit.util;

import java.io.IOException;

import java.lang.annotation.Documented;

import java.lang.ref.SoftReference;

import java.text.CollationKey;

import java.text.Collator;

import java.util.*;

import java.util.AbstractMap.SimpleEntry;

import java.util.Map.Entry;

import java.util.stream.Collectors;

import javax.lang.model.SourceVersion;

import javax.lang.model.element.AnnotationMirror;

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

import javax.lang.model.element.TypeElement;

import javax.lang.model.element.TypeParameterElement;

import javax.lang.model.element.VariableElement;

import javax.lang.model.type.ArrayType;

import javax.lang.model.type.DeclaredType;

import javax.lang.model.type.ErrorType;

import javax.lang.model.type.ExecutableType;

import javax.lang.model.type.NoType;

import javax.lang.model.type.PrimitiveType;

import javax.lang.model.type.TypeMirror;

import javax.lang.model.util.ElementFilter;

import javax.lang.model.util.ElementKindVisitor9;

import javax.lang.model.util.Elements;

import javax.lang.model.util.SimpleElementVisitor9;

import javax.lang.model.util.SimpleTypeVisitor9;

import javax.lang.model.util.TypeKindVisitor9;

import javax.lang.model.util.Types;

import javax.tools.FileObject;

import javax.tools.JavaFileManager;

import javax.tools.JavaFileManager.Location;

import javax.tools.StandardLocation;

import com.sun.source.doctree.DocCommentTree;

import com.sun.source.doctree.DocTree;

import com.sun.source.doctree.DocTree.Kind;

import com.sun.source.doctree.ParamTree;

import com.sun.source.doctree.SerialFieldTree;

import com.sun.source.tree.CompilationUnitTree;

import com.sun.source.tree.LineMap;

import com.sun.source.util.DocSourcePositions;

import com.sun.source.util.DocTrees;

import com.sun.source.util.TreePath;

import jdk.javadoc.internal.doclets.toolkit.CommentUtils.DocCommentDuo;

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

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

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

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

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

import static javax.lang.model.element.ElementKind.*;

import static javax.lang.model.element.Modifier.*;

import static javax.lang.model.type.TypeKind.*;

import static com.sun.source.doctree.DocTree.Kind.*;

import static jdk.javadoc.internal.doclets.toolkit.builders.ConstantsSummaryBuilder.MAX_CONSTANT_VALUE_INDEX_LENGTH;

/**

 * Utilities Class for Doclets.

 *

 *  <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 Atul M Dambalkar

 * @author Jamie Ho

 */

public class Utils {

    public final Configuration configuration;

    public final Messages messages;

    public final DocTrees docTrees;

    public final Elements elementUtils;

    public final Types typeUtils;

    public Utils(Configuration c) {

        configuration = c;

        messages = configuration.getMessages();

        elementUtils = c.docEnv.getElementUtils();

        typeUtils = c.docEnv.getTypeUtils();

        docTrees = c.docEnv.getDocTrees();

    }

    // our own little symbol table

    private HashMap<String, TypeMirror> symtab = new HashMap<>();

    public TypeMirror getSymbol(String signature) {

        TypeMirror type = symtab.get(signature);

        if (type == null) {

            TypeElement typeElement = elementUtils.getTypeElement(signature);

            if (typeElement == null)

                return null;

            type = typeElement.asType();

            if (type == null)

                return null;

            symtab.put(signature, type);

        }

        return type;

    }

    public TypeMirror getObjectType() {

        return getSymbol("java.lang.Object");

    }

    public TypeMirror getExceptionType() {

        return getSymbol("java.lang.Exception");

    }

    public TypeMirror getErrorType() {

        return getSymbol("java.lang.Error");

    }

    public TypeMirror getSerializableType() {

        return getSymbol("java.io.Serializable");

    }

    public TypeMirror getExternalizableType() {

        return getSymbol("java.io.Externalizable");

    }

    public TypeMirror getIllegalArgumentExceptionType() {

        return getSymbol("java.lang.IllegalArgumentException");

    }

    public TypeMirror getNullPointerExceptionType() {

        return getSymbol("java.lang.NullPointerException");

    }

    public TypeMirror getDeprecatedType() {

        return getSymbol("java.lang.Deprecated");

    }

    public TypeMirror getFunctionalInterface() {

        return getSymbol("java.lang.FunctionalInterface");

    }

    /**

     * Return array of class members whose documentation is to be generated.

     * If the member is deprecated do not include such a member in the

     * returned array.

     *

     * @param  members    Array of members to choose from.

     * @return List       List of eligible members for whom

     *                    documentation is getting generated.

     */

    public List<Element> excludeDeprecatedMembers(List<? extends Element> members) {

        List<Element> excludeList = members.stream()

                .filter((member) -> (!isDeprecated(member)))

                .sorted(makeGeneralPurposeComparator())

                .collect(Collectors.<Element, List<Element>>toCollection(ArrayList::new));

        return excludeList;

    }

    /**

     * Search for the given method in the given class.

     *

     * @param  te        Class to search into.

     * @param  method    Method to be searched.

     * @return ExecutableElement Method found, null otherwise.

     */

    public ExecutableElement findMethod(TypeElement te, ExecutableElement method) {

        for (Element m : getMethods(te)) {

            if (executableMembersEqual(method, (ExecutableElement)m)) {

                return (ExecutableElement)m;

            }

        }

        return null;

    }

    /**

     * Test whether a class is a subclass of another class.

     *

     * @param t1 the candidate superclass.

     * @param t2 the target

     * @return true if t1 is a superclass of t2.

     */

    public boolean isSubclassOf(TypeElement t1, TypeElement t2) {

        return typeUtils.isSubtype(t1.asType(), t2.asType());

    }

    /**

     * @param e1 the first method to compare.

     * @param e2 the second method to compare.

     * @return true if member1 overrides/hides or is overriden/hidden by member2.

     */

    public boolean executableMembersEqual(ExecutableElement e1, ExecutableElement e2) {

        // TODO: investigate if Elements.hides(..) will work here.

        if (isStatic(e1) && isStatic(e2)) {

            List<? extends VariableElement> parameters1 = e1.getParameters();

            List<? extends VariableElement> parameters2 = e2.getParameters();

            if (e1.getSimpleName().equals(e2.getSimpleName()) &&

                    parameters1.size() == parameters2.size()) {

                int j;

                for (j = 0 ; j < parameters1.size(); j++) {

                    VariableElement v1 = parameters1.get(j);

                    VariableElement v2 = parameters2.get(j);

                    String t1 = getTypeName(v1.asType(), true);

                    String t2 = getTypeName(v2.asType(), true);

                    if (!(t1.equals(t2) ||

                            isTypeVariable(v1.asType()) || isTypeVariable(v2.asType()))) {

                        break;

                    }

                }

                if (j == parameters1.size()) {

                return true;

                }

            }

            return false;

        } else {

            return elementUtils.overrides(e1, e2, getEnclosingTypeElement(e1)) ||

                    elementUtils.overrides(e2, e1, getEnclosingTypeElement(e2)) ||

                    e1.equals(e2);

        }

    }

    /**

     * According to

     * <cite>The Java&trade; Language Specification</cite>,

     * all the outer classes and static inner classes are core classes.

     */

    public boolean isCoreClass(TypeElement e) {

        return getEnclosingTypeElement(e) == null || isStatic(e);

    }

    public boolean matches(Element e1, Element e2) {

        if (isExecutableElement(e1) && isExecutableElement(e1)) {

            return executableMembersEqual((ExecutableElement)e1, (ExecutableElement)e2);

        } else {

            return e1.getSimpleName().equals(e2.getSimpleName());

        }

    }

    /**

     * Copy doc-files directory and its contents from the source

     * package directory to the generated documentation directory.

     * For example, given a package java.lang, this method will copy

     * the doc-files directory, found in the package directory to the

     * generated documentation hierarchy.

     *

     * @param pe the package containing the doc files to be copied

     * @throws DocFileIOException if there is a problem while copying

     *         the documentation files

     */

    public void copyDocFiles(PackageElement pe) throws DocFileIOException {

        Location sourceLoc = getLocationForPackage(pe);

        copyDirectory(sourceLoc, DocPath.forPackage(pe).resolve(DocPaths.DOC_FILES));

    }

    /**

     * Copy the given directory contents from the source package directory

     * to the generated documentation directory. For example, given a package

     * java.lang, this method will copy the entire directory, to the generated

     * documentation hierarchy.

     *

     * @param pe the package containing the directory to be copied

     * @param dir the directory to be copied

     * @throws DocFileIOException if there is a problem while copying

     *         the documentation files

     */

    public void copyDirectory(PackageElement pe, DocPath dir) throws DocFileIOException {

        copyDirectory(getLocationForPackage(pe), dir);

    }

    /**

     * Copy the given directory and its contents from the source

     * module directory to the generated documentation directory.

     * For example, given a package java.lang, this method will

     * copy the entire directory, to the generated documentation

     * hierarchy.

     *

     * @param mdle the module containing the directory to be copied

     * @param dir the directory to be copied

     * @throws DocFileIOException if there is a problem while copying

     *         the documentation files

     */

    public void copyDirectory(ModuleElement mdle, DocPath dir) throws DocFileIOException  {

        copyDirectory(getLocationForModule(mdle), dir);

    }

    /**

     * Copy files from a doc path location to the output.

     *

     * @param locn the location from which to read files

     * @param dir the directory to be copied

     * @throws DocFileIOException if there is a problem

     *         copying the files

     */

    public void copyDirectory(Location locn, DocPath dir)  throws DocFileIOException {

        boolean first = true;

        for (DocFile f : DocFile.list(configuration, locn, dir)) {

            if (!f.isDirectory()) {

                continue;

            }

            DocFile srcdir = f;

            DocFile destdir = DocFile.createFileForOutput(configuration, dir);

            if (srcdir.isSameFile(destdir)) {

                continue;

            }

            for (DocFile srcfile: srcdir.list()) {

                DocFile destfile = destdir.resolve(srcfile.getName());

                if (srcfile.isFile()) {

                    if (destfile.exists() && !first) {

                        messages.warning("doclet.Copy_Overwrite_warning",

                                srcfile.getPath(), destdir.getPath());

                    } else {

                        messages.notice("doclet.Copying_File_0_To_Dir_1",

                                srcfile.getPath(), destdir.getPath());

                        destfile.copyFile(srcfile);

                    }

                } else if (srcfile.isDirectory()) {

                    if (configuration.copydocfilesubdirs

                            && !configuration.shouldExcludeDocFileDir(srcfile.getName())) {

                        copyDirectory(locn, dir.resolve(srcfile.getName()));

                    }

                }

            }

            first = false;

        }

    }

    protected Location getLocationForPackage(PackageElement pd) {

        return getLocationForModule(configuration.docEnv.getElementUtils().getModuleOf(pd));

    }

    protected Location getLocationForModule(ModuleElement mdle) {

        Location loc = configuration.workArounds.getLocationForModule(mdle);

        if (loc != null)

            return loc;

        JavaFileManager fm = configuration.docEnv.getJavaFileManager();

        return fm.hasLocation(StandardLocation.SOURCE_PATH)

                ? StandardLocation.SOURCE_PATH

                : StandardLocation.CLASS_PATH;

    }

    public boolean isAnnotated(TypeMirror e) {

        return !e.getAnnotationMirrors().isEmpty();

    }

    public boolean isAnnotated(Element e) {

        return !e.getAnnotationMirrors().isEmpty();

    }

    public boolean isAnnotationType(Element e) {

        return new SimpleElementVisitor9<Boolean, Void>() {

            @Override

            public Boolean visitExecutable(ExecutableElement e, Void p) {

                return visit(e.getEnclosingElement());

            }

            @Override

            public Boolean visitUnknown(Element e, Void p) {

                return false;

            }

            @Override

            protected Boolean defaultAction(Element e, Void p) {

                return e.getKind() == ANNOTATION_TYPE;

            }

        }.visit(e);

    }

    /**

     * An Enum implementation is almost identical, thus this method returns if

     * this element represents a CLASS or an ENUM

     * @param e element

     * @return true if class or enum

     */

    public boolean isClass(Element e) {

        return e.getKind().isClass();

    }

    public boolean isConstructor(Element e) {

         return e.getKind() == CONSTRUCTOR;

    }

    public boolean isEnum(Element e) {

        return e.getKind() == ENUM;

    }

    boolean isEnumConstant(Element e) {

        return e.getKind() == ENUM_CONSTANT;

    }

    public boolean isField(Element e) {

        return e.getKind() == FIELD;

    }

    public boolean isInterface(Element e) {

        return e.getKind() == INTERFACE;

    }

    public boolean isMethod(Element e) {

        return e.getKind() == METHOD;

    }

    public boolean isModule(Element e) {

        return e.getKind() == ElementKind.MODULE;

    }

    public boolean isPackage(Element e) {

        return e.getKind() == ElementKind.PACKAGE;

    }

    public boolean isAbstract(Element e) {

        return e.getModifiers().contains(Modifier.ABSTRACT);

    }

    public boolean isDefault(Element e) {

        return e.getModifiers().contains(Modifier.DEFAULT);

    }

    public boolean isPackagePrivate(Element e) {

        return !(isPublic(e) || isPrivate(e) || isProtected(e));

    }

    public boolean isPrivate(Element e) {

        return e.getModifiers().contains(Modifier.PRIVATE);

    }

    public boolean isProtected(Element e) {

        return e.getModifiers().contains(Modifier.PROTECTED);

    }

    public boolean isPublic(Element e) {

        return e.getModifiers().contains(Modifier.PUBLIC);

    }

    public boolean isProperty(String name) {

        return configuration.javafx && name.endsWith("Property");

    }

    public String getPropertyName(String name) {

        return isProperty(name)

                ? name.substring(0, name.length() - "Property".length())

                : name;

    }

    public String getPropertyLabel(String name) {

        return name.substring(0, name.lastIndexOf("Property"));

    }

    public boolean isOverviewElement(Element e) {

        return e.getKind() == ElementKind.OTHER;

    }

    public boolean isStatic(Element e) {

        return e.getModifiers().contains(Modifier.STATIC);

    }

    public boolean isSerializable(TypeElement e) {

        return typeUtils.isSubtype(e.asType(), getSerializableType());

    }

    public boolean isExternalizable(TypeElement e) {

        return typeUtils.isSubtype(e.asType(), getExternalizableType());