/*

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

import java.io.*;

import java.util.*;

import com.sun.javadoc.*;

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

/**

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

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

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

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

            return;

        }

        try {

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

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

                    }

                        && ! configuration.shouldExcludeDocFileDir(

                          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,

        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.

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

                overwrite, false);

    }

    /**

     * Copy a file from a source directory to a 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 error message

     * @param file The name of the file to copy

     * @param source The source directory

     * @param destination The destination directory where the file needs to be copied

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

     *                  destination directory will be overwritten if

     *                  it already exists.

     * @param replaceNewLine true if the newline needs to be replaced with platform-

     *                  specific newline.

     */

    public static void copyFile(Configuration configuration, String file, String source,

            String destination, boolean overwrite, boolean replaceNewLine) {

        try {

            InputStream in = Configuration.class.getResourceAsStream(

            OutputStream out = new FileOutputStream(destfile);

            try {

                if (!replaceNewLine) {

                    byte[] buf = new byte[2048];

                    int n;

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

                } else {

                    BufferedReader reader = new BufferedReader(new InputStreamReader(in));

                    BufferedWriter writer;

                    if (configuration.docencoding == null) {

                        writer = new BufferedWriter(new OutputStreamWriter(out));

                    } else {

                        writer = new BufferedWriter(new OutputStreamWriter(out,

                            configuration.docencoding));

                    }

                    try {

                        String line;

                        while ((line = reader.readLine()) != null) {

                            writer.write(line);

                            writer.write(DocletConstants.NL);

                        }

                    } finally {

                        reader.close();

                        writer.close();

                    }

                }

            } finally {

                in.close();

                out.close();

            }

        } catch (IOException ie) {

            ie.printStackTrace(System.err);

            throw new DocletAbortException();

        }

    }

    /**

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

     * @param configuration The Configuration for the current Doclet.

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

     */

    }

    /**

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