/*

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

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.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 com.sun.tools.javac.util.DefinedBy;

import com.sun.tools.javac.util.DefinedBy.Api;

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

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

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 jdk.javadoc.internal.doclets.toolkit.Messages;

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 the given directory contents from the source package directory

     * to the generated documentation directory. For example for a package

     * java.lang this method find out the source location of the package using

     * {@link SourcePath} and if given directory is found in the source

     * directory structure, copy the entire directory, to the generated

     * documentation hierarchy.

     * @param pe

     */

    public void copyDocFiles(PackageElement pe) {

        copyDocFiles(DocPath.forPackage(pe).resolve(DocPaths.DOC_FILES));

    }

    public void copyDocFiles(DocPath dir) {

        try {

            boolean first = true;

            for (DocFile f : DocFile.list(configuration, StandardLocation.SOURCE_PATH, 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())) {

                            copyDocFiles(dir.resolve(srcfile.getName()));

                        }

                    }

                }

                first = false;

            }

        } catch (SecurityException | IOException exc) {

            throw new DocletAbortException(exc);

        }

    }

    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 @DefinedBy(Api.LANGUAGE_MODEL)

            public Boolean visitExecutable(ExecutableElement e, Void p) {

                return visit(e.getEnclosingElement());

            }

            @Override  @DefinedBy(Api.LANGUAGE_MODEL)

            public Boolean visitUnknown(Element e, Void p) {

                return false;

            }

            @Override @DefinedBy(Api.LANGUAGE_MODEL)

            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 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());

    }

    public SortedSet<VariableElement> serializableFields(TypeElement aclass) {

        return configuration.workArounds.getSerializableFields(this, aclass);

    }

    public SortedSet<ExecutableElement> serializationMethods(TypeElement aclass) {

        return configuration.workArounds.getSerializationMethods(this, aclass);

    }

    public boolean definesSerializableFields(TypeElement aclass) {

        return configuration.workArounds.definesSerializableFields(this, aclass);

    }

    public String modifiersToString(Element e, boolean trailingSpace) {

        SortedSet<Modifier> set = new TreeSet<>(e.getModifiers());

        set.remove(Modifier.NATIVE);

        set.remove(Modifier.STRICTFP);

        set.remove(Modifier.SYNCHRONIZED);

        return new ElementKindVisitor9<String, SortedSet<Modifier>>() {

            final StringBuilder sb = new StringBuilder();

            void addVisibilityModifier(Set<Modifier> modifiers) {

                if (modifiers.contains(PUBLIC)) {

                    sb.append("public").append(" ");

                } else if (modifiers.contains(PROTECTED)) {

                    sb.append("protected").append(" ");

                } else if (modifiers.contains(PRIVATE)) {

                    sb.append("private").append(" ");

                }

            }

            void addStatic(Set<Modifier> modifiers) {

                if (modifiers.contains(STATIC)) {

                    sb.append("static").append(" ");

                }

            }

            void addModifers(Set<Modifier> modifiers) {

                String s = set.stream().map(m -> m.toString()).collect(Collectors.joining(" "));

                sb.append(s);

                if (!s.isEmpty())

                    sb.append(" ");

            }

            String finalString(String s) {

                sb.append(s);

                if (trailingSpace) {

                    if (sb.lastIndexOf(" ") == sb.length() - 1) {

                        return sb.toString();

                    } else {

                        return sb.append(" ").toString();

                    }

                } else {

                    return sb.toString().trim();

                }