/*

 * Copyright 1999-2008 Sun Microsystems, Inc.  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.  Sun designates this

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

 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package com.sun.tools.doclets.internal.toolkit.util;

import com.sun.javadoc.*;

import com.sun.tools.doclets.internal.toolkit.*;

import java.util.*;

import java.io.*;

/**

 * Utilities Class for Doclets.

 *

 * This code is not part of an API.

 * It is implementation that is subject to change.

 * Do not use it as an API

 *

 * @author Atul M Dambalkar

 * @author Jamie Ho

 */

public class Util {

    /**

     * A mapping between characters and their

     * corresponding HTML escape character.

     */

    public static final String[][] HTML_ESCAPE_CHARS =

    {{"&", "&amp;"}, {"<", "&lt;"}, {">", "&gt;"}};

    /**

     * 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 ProgramElementDoc[] Array of eligible members for whom

     *                             documentation is getting generated.

     */

    public static ProgramElementDoc[] excludeDeprecatedMembers(

        ProgramElementDoc[] members) {

        return

            toProgramElementDocArray(excludeDeprecatedMembersAsList(members));

    }

    /**

     * 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 static List<ProgramElementDoc> excludeDeprecatedMembersAsList(

        ProgramElementDoc[] members) {

        List<ProgramElementDoc> list = new ArrayList<ProgramElementDoc>();

        for (int i = 0; i < members.length; i++) {

            if (members[i].tags("deprecated").length == 0) {

                list.add(members[i]);

            }

        }

        Collections.sort(list);

        return list;

    }

    /**

     * Return the list of ProgramElementDoc objects as Array.

     */

    public static ProgramElementDoc[] toProgramElementDocArray(List<ProgramElementDoc> list) {

        ProgramElementDoc[] pgmarr = new ProgramElementDoc[list.size()];

        for (int i = 0; i < list.size(); i++) {

            pgmarr[i] = list.get(i);

        }

        return pgmarr;

    }

    /**

     * Return true if a non-public member found in the given array.

     *

     * @param  members Array of members to look into.

     * @return boolean True if non-public member found, false otherwise.

     */

    public static boolean nonPublicMemberFound(ProgramElementDoc[] members) {

        for (int i = 0; i < members.length; i++) {

            if (!members[i].isPublic()) {

                return true;

            }

        }

        return false;

    }

    /**

     * Search for the given method in the given class.

     *

     * @param  cd        Class to search into.

     * @param  method    Method to be searched.

     * @return MethodDoc Method found, null otherwise.

     */

    public static MethodDoc findMethod(ClassDoc cd, MethodDoc method) {

        MethodDoc[] methods = cd.methods();

        for (int i = 0; i < methods.length; i++) {

            if (executableMembersEqual(method, methods[i])) {

                return methods[i];

            }

        }

        return null;

    }

    /**

     * @param member1 the first method to compare.

     * @param member2 the second method to compare.

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

     */

    public static boolean executableMembersEqual(ExecutableMemberDoc member1,

            ExecutableMemberDoc member2) {

        if (! (member1 instanceof MethodDoc && member2 instanceof MethodDoc))

            return false;

        MethodDoc method1 = (MethodDoc) member1;

        MethodDoc method2 = (MethodDoc) member2;

        if (method1.isStatic() && method2.isStatic()) {

            Parameter[] targetParams = method1.parameters();

            Parameter[] currentParams;

            if (method1.name().equals(method2.name()) &&

                   (currentParams = method2.parameters()).length ==

                targetParams.length) {

                int j;

                for (j = 0; j < targetParams.length; j++) {

                    if (! (targetParams[j].typeName().equals(

                              currentParams[j].typeName()) ||

                                   currentParams[j].type() instanceof TypeVariable ||

                                   targetParams[j].type() instanceof TypeVariable)) {

                        break;

                    }

                }

                if (j == targetParams.length) {

                    return true;

                }

            }

            return false;

        } else {

                return method1.overrides(method2) ||

                method2.overrides(method1) ||

                                member1 == member2;

        }

    }

    /**

     * According to the Java Language Specifications, all the outer classes

     * and static inner classes are core classes.

     */

    public static boolean isCoreClass(ClassDoc cd) {

        return cd.containingClass() == null || cd.isStatic();

    }

    public static boolean matches(ProgramElementDoc doc1,

            ProgramElementDoc doc2) {

        if (doc1 instanceof ExecutableMemberDoc &&

            doc2 instanceof ExecutableMemberDoc) {

            ExecutableMemberDoc ed1 = (ExecutableMemberDoc)doc1;

            ExecutableMemberDoc ed2 = (ExecutableMemberDoc)doc2;

            return executableMembersEqual(ed1, ed2);

        } else {

            return doc1.name().equals(doc2.name());

        }

    }

    /**

     * Copy source file to destination file.

     *

     * @throws SecurityException

     * @throws IOException

     */

    public static void copyFile(File destfile, File srcfile)

        throws IOException {

        byte[] bytearr = new byte[512];

        int len = 0;

        FileInputStream input = new FileInputStream(srcfile);

        File destDir = destfile.getParentFile();

        destDir.mkdirs();

        FileOutputStream output = new FileOutputStream(destfile);

        try {

            while ((len = input.read(bytearr)) != -1) {

                output.write(bytearr, 0, len);

            }

        } catch (FileNotFoundException exc) {

        } catch (SecurityException exc) {

        } finally {

            input.close();

            output.close();

        }

    }

    /**

     * 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 configuration The configuration of the current doclet.

     * @param path The relative path to the directory to be copied.

     * @param dir The original directory name to copy from.

     * @param overwrite Overwrite files if true.

     */

    public static void copyDocFiles(Configuration configuration,

            String path, String dir, boolean overwrite) {

        if (checkCopyDocFilesErrors(configuration, path, dir)) {

            return;

        }

        String destname = configuration.docFileDestDirName;

        File srcdir = new File(path + dir);

        if (destname.length() > 0 && !destname.endsWith(

               DirectoryManager.URL_FILE_SEPERATOR)) {

            destname += DirectoryManager.URL_FILE_SEPERATOR;

        }

        String dest = destname + dir;

        try {

            File destdir = new File(dest);

            DirectoryManager.createDirectory(configuration, dest);

            String[] files = srcdir.list();

            for (int i = 0; i < files.length; i++) {

                File srcfile = new File(srcdir, files[i]);

                File destfile = new File(destdir, files[i]);

                if (srcfile.isFile()) {

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

                        configuration.message.warning((SourcePosition) null,

                                "doclet.Copy_Overwrite_warning",

                                srcfile.toString(), destdir.toString());

                    } else {

                        configuration.message.notice(

                            "doclet.Copying_File_0_To_Dir_1",

                            srcfile.toString(), destdir.toString());

                        Util.copyFile(destfile, srcfile);

                    }

                } else if(srcfile.isDirectory()) {

                    if(configuration.copydocfilesubdirs

                        && ! configuration.shouldExcludeDocFileDir(

                          srcfile.getName())){

                        copyDocFiles(configuration, path, dir +

                                    DirectoryManager.URL_FILE_SEPERATOR + srcfile.getName(),

                                overwrite);

                    }

                }

            }

        } catch (SecurityException exc) {

            throw new DocletAbortException();

        } catch (IOException exc) {

            throw new DocletAbortException();

        }

    }

    /**

     * Given the parameters for copying doc-files, check for errors.

     *

     * @param configuration The configuration of the current doclet.

     * @param path The relative path to the directory to be copied.

     * @param dirName The original directory name to copy from.

     */

    private static boolean checkCopyDocFilesErrors (Configuration configuration,

            String path, String dirName) {

        if ((configuration.sourcepath == null || configuration.sourcepath.length() == 0) &&

               (configuration.destDirName == null || configuration.destDirName.length() == 0)) {

            //The destination path and source path are definitely equal.

            return true;

        }

        File sourcePath, destPath = new File(configuration.destDirName);

        StringTokenizer pathTokens = new StringTokenizer(

            configuration.sourcepath == null ? "" : configuration.sourcepath,

            File.pathSeparator);

        //Check if the destination path is equal to the source path.  If yes,

        //do not copy doc-file directories.

        while(pathTokens.hasMoreTokens()){

            sourcePath = new File(pathTokens.nextToken());

            if(destPath.equals(sourcePath)){

                return true;

            }

        }

        //Make sure the doc-file being copied exists.

        File srcdir = new File(path + dirName);

        if (! srcdir.exists()) {

            return true;

        }

        return false;

    }

    /**

     * Copy a file in the resources directory to the destination

     * directory (if it is not there already).  If

     * <code>overwrite</code> is true and the destination file

     * already exists, overwrite it.

     *

     * @param configuration  Holds the destination directory and error message

     * @param resourcefile   The name of the resource file to copy

     * @param overwrite      A flag to indicate whether the file in the

     *                       destination directory will be overwritten if

     *                       it already exists.

     */

    public static void copyResourceFile(Configuration configuration,

            String resourcefile,

            boolean overwrite) {

        String destdir = configuration.destDirName;

        String destresourcesdir = destdir + "resources";

        DirectoryManager.createDirectory(configuration, destresourcesdir);

        File destfile = new File(destresourcesdir, resourcefile);

        if(destfile.exists() && (! overwrite)) return;

        try {

            InputStream in = Configuration.class.getResourceAsStream(

                "resources/" + resourcefile);

            if(in==null) return;

            OutputStream out = new FileOutputStream(destfile);

            byte[] buf = new byte[2048];

            int n;

            while((n = in.read(buf))>0) out.write(buf,0,n);

            in.close();

            out.close();

        } catch(Throwable t) {}

    }

    /**

     * Given a PackageDoc, return the source path for that package.

     * @param configuration The Configuration for the current Doclet.

     * @param pkgDoc The package to seach the path for.

     * @return A string representing the path to the given package.

     */

    public static String getPackageSourcePath(Configuration configuration,

            PackageDoc pkgDoc){

        try{

            String pkgPath = DirectoryManager.getDirectoryPath(pkgDoc);

            String completePath = new SourcePath(configuration.sourcepath).

                getDirectory(pkgPath) + DirectoryManager.URL_FILE_SEPERATOR;

            //Make sure that both paths are using the same seperators.

            completePath = Util.replaceText(completePath, File.separator,

                    DirectoryManager.URL_FILE_SEPERATOR);

            pkgPath = Util.replaceText(pkgPath, File.separator,

                    DirectoryManager.URL_FILE_SEPERATOR);

            return completePath.substring(0, completePath.indexOf(pkgPath));

        } catch (Exception e){

            return "";

        }

    }

    /**

     * We want the list of types in alphabetical order.  However, types are not

     * comparable.  We need a comparator for now.

     */

    private static class TypeComparator implements Comparator<Type> {

        public int compare(Type type1, Type type2) {

            return type1.qualifiedTypeName().toLowerCase().compareTo(

                type2.qualifiedTypeName().toLowerCase());

        }

    }

    /**

     * For the class return all implemented interfaces including the

     * superinterfaces of the implementing interfaces, also iterate over for

     * all the superclasses. For interface return all the extended interfaces

     * as well as superinterfaces for those extended interfaces.

     *

     * @param  type       type whose implemented or

     *                    super interfaces are sought.

     * @param  configuration the current configuration of the doclet.

     * @param  sort if true, return list of interfaces sorted alphabetically.

     * @return List of all the required interfaces.

     */

    public static List<Type> getAllInterfaces(Type type,

            Configuration configuration, boolean sort) {

        Map<ClassDoc,Type> results = sort ? new TreeMap<ClassDoc,Type>() : new LinkedHashMap<ClassDoc,Type>();

        Type[] interfaceTypes = null;

        Type superType = null;

        if (type instanceof ParameterizedType) {

            interfaceTypes = ((ParameterizedType) type).interfaceTypes();

            superType = ((ParameterizedType) type).superclassType();

        } else if (type instanceof ClassDoc) {

            interfaceTypes = ((ClassDoc) type).interfaceTypes();

            superType = ((ClassDoc) type).superclassType();

        } else {

            interfaceTypes = type.asClassDoc().interfaceTypes();

            superType = type.asClassDoc().superclassType();

        }

        for (int i = 0; i < interfaceTypes.length; i++) {

            Type interfaceType = interfaceTypes[i];

            ClassDoc interfaceClassDoc = interfaceType.asClassDoc();

            if (! (interfaceClassDoc.isPublic() ||

                (configuration == null ||

                isLinkable(interfaceClassDoc, configuration)))) {

                continue;

            }

            results.put(interfaceClassDoc, interfaceType);

            List<Type> superInterfaces = getAllInterfaces(interfaceType, configuration, sort);

            for (Iterator<Type> iter = superInterfaces.iterator(); iter.hasNext(); ) {

                Type t = iter.next();

                results.put(t.asClassDoc(), t);

            }

        }

        if (superType == null)

            return new ArrayList<Type>(results.values());

        //Try walking the tree.

        addAllInterfaceTypes(results,

            superType,

            superType instanceof ClassDoc ?

                ((ClassDoc) superType).interfaceTypes() :

                ((ParameterizedType) superType).interfaceTypes(),

            false, configuration);

        List<Type> resultsList = new ArrayList<Type>(results.values());

        if (sort) {

                Collections.sort(resultsList, new TypeComparator());

        }

        return resultsList;

    }

    public static List<Type> getAllInterfaces(Type type, Configuration configuration) {

        return getAllInterfaces(type, configuration, true);

    }

    private static void findAllInterfaceTypes(Map<ClassDoc,Type> results, ClassDoc c, boolean raw,

            Configuration configuration) {

        Type superType = c.superclassType();

        if (superType == null)

            return;

        addAllInterfaceTypes(results, superType,

                superType instanceof ClassDoc ?

                ((ClassDoc) superType).interfaceTypes() :

                ((ParameterizedType) superType).interfaceTypes(),

                raw, configuration);

    }

    private static void findAllInterfaceTypes(Map<ClassDoc,Type> results, ParameterizedType p,

            Configuration configuration) {

        Type superType = p.superclassType();

        if (superType == null)

            return;

        addAllInterfaceTypes(results, superType,

                superType instanceof ClassDoc ?

                ((ClassDoc) superType).interfaceTypes() :

                ((ParameterizedType) superType).interfaceTypes(),

                false, configuration);

    }

    private static void addAllInterfaceTypes(Map<ClassDoc,Type> results, Type type,

            Type[] interfaceTypes, boolean raw,

            Configuration configuration) {

        for (int i = 0; i < interfaceTypes.length; i++) {

            Type interfaceType = interfaceTypes[i];

            ClassDoc interfaceClassDoc = interfaceType.asClassDoc();

            if (! (interfaceClassDoc.isPublic() ||

                (configuration != null &&

                isLinkable(interfaceClassDoc, configuration)))) {

                continue;

            }

            if (raw)

                interfaceType = interfaceType.asClassDoc();

            results.put(interfaceClassDoc, interfaceType);

            List<Type> superInterfaces = getAllInterfaces(interfaceType, configuration);

            for (Iterator<Type> iter = superInterfaces.iterator(); iter.hasNext(); ) {

                Type superInterface = iter.next();

                results.put(superInterface.asClassDoc(), superInterface);

            }

        }

        if (type instanceof ParameterizedType)

            findAllInterfaceTypes(results, (ParameterizedType) type, configuration);

        else if (((ClassDoc) type).typeParameters().length == 0)

            findAllInterfaceTypes(results, (ClassDoc) type, raw, configuration);

        else

            findAllInterfaceTypes(results, (ClassDoc) type, true, configuration);

    }

    public static <T extends ProgramElementDoc> List<T> asList(T[] members) {

        List<T> list = new ArrayList<T>();

        for (int i = 0; i < members.length; i++) {

            list.add(members[i]);

        }

        return list;

    }

    /**

     * Enclose in quotes, used for paths and filenames that contains spaces

     */

    public static String quote(String filepath) {

        return ("\"" + filepath + "\"");

    }

    /**

     * Given a package, return it's name.

     * @param packageDoc the package to check.

     * @return the name of the given package.

     */

    public static String getPackageName(PackageDoc packageDoc) {

        return packageDoc == null || packageDoc.name().length() == 0 ?

            DocletConstants.DEFAULT_PACKAGE_NAME : packageDoc.name();

    }

    /**

     * Given a package, return it's file name without the extension.

     * @param packageDoc the package to check.