package Torello.JavaDoc;


// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// Standard-Java Imports
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

import java.io.IOException;
import java.util.List;
import java.util.function.Consumer;
import java.util.Optional;


// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// Java-HTML Imports
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

import Torello.Java.*;

import static Torello.JavaDoc.PF.*;
import static Torello.Java.C.*;

import Torello.Java.Additional.Ret4;
import Torello.Java.Function.IntTFunction;
import Torello.Java.ReadOnly.ROArrayListBuilder;
import Torello.Java.ReadOnly.ReadOnlyArrayList;
import Torello.Java.ReadOnly.ReadOnlyList;

import Torello.JDUInternal.DataClasses.MainLoopData.AnnotationsMirror;
import Torello.JDUInternal.DataClasses.MainLoopData.CallableSignature;


// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// The new Source-Code Parser: com.sun.source.*
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

import com.sun.source.tree.*;


/**
 * <B STYLE='color:darkred;'>Reflection Class:</B>
 * 
 * Common-Root Ancestor Class of both {@link Method} and {@link Constructor}.
 * 
 * <BR /><BR />
 * <EMBED CLASS='external-html' DATA-FILE-ID=JPB_CALLBL>
 * <EMBED CLASS='external-html' DATA-FILE-ID=JPB_DIAGRAM>
 */
@JDHeaderBackgroundImg
public abstract class Callable extends Declaration implements java.io.Serializable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    public static final long serialVersionUID = 1;

    // COMPLETELY UN-USED RIGHT NOW, EXPERIMENTAL-ONLY
    public final String autoFindID;

    @Override
    String codeHiLiteString()
    { return (this.body == null) ? null : StrIndent.chompCallableBraces(this.body); }


    // ********************************************************************************************
    // ********************************************************************************************
    // protected final String[] parameterNames;
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * The names of all parameters to this {@code Method} or {@code Constructor}.
     *  
     * <BR /><BR /><B CLASS=JDDescLabel>Parallel List:</B>
     * 
     * <BR />This list must be considered a parallel list to the other parameter-related list:
     * {@link #parameterTypes}, {@link #parameterTypesJOW} and {@link #parameterAnnotations}
     */
    public final ReadOnlyList<String> parameterNames;

    /**
     * This contains the types of the parameters, stored as {@code String's}.  The contents of
     * these {@code String's} do include: <I>package-name, containing classes (if
     * inner-classes), and generic-parameter expressions (if generic-types).</I>  These names are
     * as fully-qualified as the AST Parser allows.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>JOW Alternative:</B>
     * 
     * <BR />The {@code ReadOnlyList} {@link #parameterTypesJOW} reduces these types (as
     * {@code String's}) to a single-word.  If a {@link Method} or a {@link Constructor} that
     * accepts a paremeter such as {@code java.util.Iterable<Integer>}, and it seems
     * <I>'difficult to work with'</I> - the entry in {@link #parameterTypesJOW} at the
     * same array-location would contain, simply, the Java {@code String 'Iterable'}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Parallel List:</B>
     * 
     * <BR />This list must be considered a parallel list to the other parameter-related list:
     * {@link #parameterNames}, {@link #parameterTypesJOW} and {@link #parameterAnnotations}
     */
    public final ReadOnlyList<String> parameterTypes;

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JPB_JOW_TITLE>
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Parallel List:</B>
     * 
     * <BR />This list must be considered a parallel list to the other parameter-related list:
     * {@link #parameterNames}, {@link #parameterTypes} and {@link #parameterAnnotations}
     */
    public final ReadOnlyList<String> parameterTypesJOW;

    /**
     * Any parameters that are annotated will have the <I>exact text-{@code String} of the
     * annotations that were used in the source-code for that parameter</I> stored in this
     * two-dimensional {@code String[][]} array.
     * 
     * <BR /><BR />This list will retrieve and contain the actual character data that may be found
     * in the source-code file for an element in a {@code com.sun.source} 'AST' (Abstract Syntax
     * Tree).  The list of annotations on a parameter (if any) will each be saved as a
     * {@code java.lang.String}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Null Warning:</B>
     * 
     * <BR />Unlike the other lists in class {@code Callable}, when there are no parameters for 
     * a {@code Callabe}, or when there are parameters, but none of them have been annotated,
     * <I>for the purposes of efficiency and better memory management, this field will simply be
     * assigned null</I>.
     * 
     * <BR /><BR />In almost all cases (particularly in the Java HTML Library), this
     * two-dimensional list, itself, really will be null - <I>since parameter annotations are
     * quite uncommon</I>.  Perhaps, some users make use of them from time to time.
     *  
     * <BR /><BR /><B CLASS=JDDescLabel>Parallel List:</B>
     * 
     * <BR />This list must be considered a parallel list to the other parameter-related list:
     * {@link #parameterNames}, {@link #parameterTypes} and {@link #parameterTypesJOW}
     */
    public final ReadOnlyList<ReadOnlyList<String>> parameterAnnotations;

    /**
     * The names of all {@code Exception, Error} and {@code Throwable} that may be thrown by this
     * {@code Constructor} or {@code Method}.
     * 
     * <BR /><BR /><B STYLE='color: red;'>NOTE:</B> Only exceptions which are included in the
     * actual {@link Declaration#signature}, inside the original {@code '.java'} source-file for
     * this {@code Callable} will be listed in this array.
     */
    public final ReadOnlyList<String> exceptions;


    // ********************************************************************************************
    // ********************************************************************************************
    // Quick Parameter Helper Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Retrieves the number of parameters utilized by the {@link Method} or {@link Constructor}
     * ({@code Callable})
     * 
     * @return The size of all three of the parameter {@link ReadOnlyList}'s'
     */
    public int numParameters()
    { return parameterNames.size(); }

    /**
     * This will retrieve the type of the parameter (as a {@code String}) that has the name
     * {@code 'parameterName'}.  This method will simply return null, gracefully, if this
     * {@link Method} or {@link Constructor} does not have a parameter with that name.  This method
     * will not throw an exception in such cases.
     * 
     * @param parameterName The name of the parameter whose type you are requesting.
     * 
     * @return The fully-qualified type of the parameter, as a {@code String} having the name
     * {@code 'parameterName'}, or null if no such type exists.
     * 
     * @see #parameterTypes
     * @see #parameterNames
     */
    public String getParameterType(String parameterName)
    {
        for (int i=0; i < parameterNames.size(); i++)
            if (parameterNames.get(i).equals(parameterName))
                return parameterTypes.get(i);

        return null;
    }

    /** 
     * This will retrieve the type of the parameter (as a {@code String}) that has the name
     * {@code 'parameterName'}.  This method will simply return null, gracefully, if this
     * {@link Method} or {@link Constructor} does not have a parameter with that name.  This
     * method will not throw an exception in such cases.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=JPB_C_JOW_NOTE>
     * 
     * @param parameterName The name of the parameter whose type you are requesting.
     * 
     * @return The type of the parameter, as a <B>one-word {@code String}</B> having the name
     * {@code 'parameterName'}.
     * 
     * @see #parameterTypesJOW
     * @see #parameterTypes
     * @see #parameterNames
     */
    public String getParameterTypeJOW(String parameterName)
    {
        if (parameterNames != null)
            for (int i=0; i < parameterNames.size(); i++)
                if (parameterNames.get(i).equals(parameterName))
                    return parameterTypesJOW.get(i);

        return null;
    }

    /**
     * This will retrieve the annotations-list that may (or may not) adorn the parameter which uses
     * the name {@code 'parameterName'}.
     * 
     * <BR /><BR />This method will simply return null, gracefully, if this {@link Method} or
     * {@link Constructor} does not have a parameter with that name.  This method will not throw
     * an exception in such cases.
     * 
     * <BR /><BR /><B>NOTE:</B>This method will also return null even if a parameter having the
     * provided name is found, but that parameter wasn't annotated with anything.  If a null is
     * returned, distinguishing between the case where {@code 'parameterName'} just wasn't found,
     * and the case where that parameter wasn't annotated - isn't possible here.
     * 
     * @param parameterName The name of the parameter whose annotation-list you are requesting.
     * 
     * @return The type of the parameter having the name {@code 'parameterName'}.
     * 
     * @see #parameterAnnotations
     * @see #parameterNames
     */
    public ReadOnlyList<String> getParameterAnnotations(String parameterName)
    {
        if (parameterAnnotations == null) return null;

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

            if (parameterNames.get(i).equals(parameterName))
                return parameterAnnotations.get(i);
                    // In the line above, if a parameter isnt annotated, that location in the 
                    // array will have a 'null'

        return null;
    }

    /**
     * This will look at each parmeter's annotation array to see if there are any parameters in
     * this {@code Callable's} invocation parameter-list that were annotated with anything.
     * 
     * @return {@code TRUE} if there are any parameters that were annotated with something, and
     * false if <B><I>every parameter</I></B> in the parameter-list had a 'null' {@code String}
     * array of parameter-annotations.
     * 
     * <BR /><BR />If this instance of {@code Callable} is one which does not accept any
     * parameters, this methhod will return {@code FALSE} immediately.
     * 
     * <BR /><BR /><B STYLE='color:red;'>NOTE:</B> The internal {@code 'parameterAnnotations'}
     * field for class {@code Callable} is implemented as a two-dimensional {@code String}-array.
     * There may be any number of parameters that are passed to a {@link Method} or
     * {@code Constructor}, and each of those parameters may have any number of annotations that
     * were attached to them.
     * 
     * <BR /><BR /><B>SANITY-CHECK</B> Likely {@code 99.99%} of the parameters in the Java HTML
     * library do not have any parameter's that are annotated.
     * 
     * @see #parameterAnnotations
     */
    public boolean hasAnnotatedParameters()
    { return parameterAnnotations != null; }

    /**
     * Reports how many of the parameters in the internal list of parameters that had annotations
     * attached to them.
     * 
     * <BR /><BR /><B>SANITY-CHECK</B> Likely {@code 99.99%} of the parameters in the Java HTML
     * library do not have any parameter's that are annotated.
     * 
     * @return This will count how many parameters which are used by this {@code Callable}
     * (either {@link Method} or {@link Field}) that have annotations that were attached to
     * the parameter.
     * 
     * @see #parameterAnnotations
     */
    public int numAnnotatedParameters()
    {
        int count = 0;

        if (parameterAnnotations == null) return 0;

        // NOTE: each parameter has an "Annotation List" stored in a 2-D array.  This is why
        //       this for-loop is using 'String[]', rather than 'String' ...
        //       A parameter may be annotated with zero annotations, one, or many annotations.

        for (ReadOnlyList<String> paList : parameterAnnotations)
            if (paList.size() > 0) count++;

        return count;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor - com.sun.source.tree 
    // ********************************************************************************************
    // ********************************************************************************************


    // package-private: Only used by subclasses.
    Callable(
            MethodTree  methodOrConstructor,
            String      methodOrConstructorName,
            Entity      entity,
            TreeUtils   util
        )
    {
        super(
            util,                               // Big Ret4 thing
            methodOrConstructor,                // com.sun.source.Tree.MethodTree instance
            methodOrConstructor.getModifiers(), // Annotation **AND** public, static, final
            methodOrConstructorName,            // Method-Name or "<init>"
            entity,                             // Entity.METHOD or Entity.CONSTRUCTOR
            methodOrConstructor.getBody()
        );


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Callable Parameters
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        List<? extends VariableTree> pList = methodOrConstructor.getParameters();

        if ((pList == null) || (pList.size() == 0))
        {
            this.parameterNames         =  EMPTY_READONLY_LIST;
            this.parameterTypes         =  EMPTY_READONLY_LIST;
            this.parameterTypesJOW      =  EMPTY_READONLY_LIST;
            this.parameterAnnotations   =  null;
        }

        else 
        {
            int SIZE = pList.size();
            boolean atLeastOneAnnotatedParameter = false;

            // For efficiency, use the ROAL-Builder, because otherwise (using ReadOnlyArrayList
            // constructor), the Iterator would have to be run 4 separate times.

            ROArrayListBuilder<String> bParameterNames      = new ROArrayListBuilder<>(SIZE);
            ROArrayListBuilder<String> bParameterTypes      = new ROArrayListBuilder<>(SIZE);
            ROArrayListBuilder<String> bParameterTypesJOW   = new ROArrayListBuilder<>(SIZE);
    
            ROArrayListBuilder<ReadOnlyList<String>> bParameterAnnotations =
                new ROArrayListBuilder<>();

            for (VariableTree vt : pList)
            {
                bParameterNames.add(vt.getName().toString());

                String type = vt.getType().toString();
    
                bParameterTypes.add(type);
                bParameterTypesJOW.add(StrSource.typeToJavaIdentifier(type));

                // NOTE: You **WILL TRY** again...  It cannot be done - a Var-Args Parameter is auto
                // converted into an Array by com.sun.souce.tree.  There isn't a way to know that it
                // was a Var-Args.  (Other than by parsing the JavaDocHTMLFile)
                //
                // System.out.println("    " + this.parameterTypes[i] + "  ==>  " +
                //      this.parameterTypesJOW[i]);

                // List<? extends AnnotationTree> annotList = ...
                @SuppressWarnings("unchecked")
                List<AnnotationTree> annotList = 
                    (List<AnnotationTree>) vt.getModifiers().getAnnotations();

                if ((annotList == null) || (annotList.size() == 0))
                    bParameterAnnotations.add(null);
                else
                {
                    atLeastOneAnnotatedParameter = true;

                    bParameterAnnotations.add(
                        new ReadOnlyArrayList<String>(
                            annotList,
                            (AnnotationTree at) -> at.toString().trim(),
                            annotList.size()
                        ));
                }
            }

            this.parameterNames     =  bParameterNames.build();
            this.parameterTypes     =  bParameterTypes.build();
            this.parameterTypesJOW  =  bParameterTypesJOW.build();

            this.parameterAnnotations = atLeastOneAnnotatedParameter
                ? bParameterAnnotations.build()
                : null;
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Throws Clauses Declared by this Callable
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        @SuppressWarnings("unchecked")
        // List<? extends ExpressionTree> tl = ...
        List<ExpressionTree> tl = (List<ExpressionTree>) methodOrConstructor.getThrows();

        if ((tl == null) || (tl.size() == 0))
            this.exceptions = EMPTY_READONLY_LIST;

        else this.exceptions = new ReadOnlyArrayList<String>
            (tl, (ExpressionTree et) -> et.toString().trim(), tl.size());


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // FINISHED
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // Currently Unused / Experimental
        // this.autoFindID = AnnotationsMirror.processAutoFindID(annotations, signature);

        this.autoFindID = "";
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Package-Private Constructor: Used Internally by 'JDUInternal.ParseHTML.SignatureParse'
    // ********************************************************************************************
    // ********************************************************************************************


    // Ensures that the Version with longer type-information strings is used.
    // Java Doc often uses longer type strings
    //
    // This cannot be public because this "Merge" expects that both of these constructors are
    // identical - with the only noted difference being one was from JavaDoc and one was from the
    // source-code.  The array-lengths need to be equal or else IndexOutOfBoundsException will
    // start throwing.  Plus, this is not useful outside of the upgrade application.
    //
    // This "merging" of two instances of Callable is **ONLY NEEDED** for Methods and Constructors,
    // **AND NOT** for Fields, Enum-Constants or Annotation-Elements.

    Callable(CallableSignature cSig, Callable cFromSourceParser)
    {
        // Calls the super 'clone' constructor for Declaration
        // Java Parser has much more information for everything, except the "Parameter Types"
        // JP elects to leave off the "Package Information" for types - while Java Doc includes
        // it (**unless** it can provide an <A HREF=...> for the type, then it leaves it off too!)

        super(cFromSourceParser);

        this.parameterNames         = cFromSourceParser.parameterNames;
        this.parameterTypesJOW      = cFromSourceParser.parameterTypesJOW;
        this.exceptions             = cFromSourceParser.exceptions;
        this.parameterAnnotations   = cFromSourceParser.parameterAnnotations;

        // Currently Unused / Experimental
        this.autoFindID = cFromSourceParser.autoFindID;

        if (cFromSourceParser.parameterTypes.size() == 0)
            this.parameterTypes = EMPTY_READONLY_LIST;

        else
        {
            ROArrayListBuilder<String> roalb =
                new ROArrayListBuilder<>(cFromSourceParser.parameterTypes.size());

            // Java Doc always produces "java.lang.String", while JP just gives "String"
            // REMEMBER: JP is lazy when it comes to "Package Information" for types.
            //           Java-Doc includes it often - BUT NOT ALWAYS.  (See above comment)
            // Remember, though, the rest of the JavaParser fields are filled out, Java Doc
            // leaves out all the other information that JP retrieves.

            for (int i=0; i < cFromSourceParser.parameterTypes.size(); i++)

                roalb.add(
                    (cSig.parameterTypes.get(i).length() >
                        cFromSourceParser.parameterTypes.get(i).length())

                        ? cSig.parameterTypes.get(i)
                        : cFromSourceParser.parameterTypes.get(i)
                );

            this.parameterTypes = roalb.build();
        }
    }

    Callable(CallableSignature cSig, Entity entity)
    {
        super(cSig.name, entity, cSig.signature);

        this.parameterNames         = cSig.parameterNames;
        this.parameterTypes         = cSig.parameterTypes;
        this.parameterTypesJOW      = cSig.parameterTypesJOW;
        this.exceptions             = null;
        this.autoFindID             = null;
        this.parameterAnnotations   = null;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // NEW HELPER
    // ********************************************************************************************
    // ********************************************************************************************


    boolean nearlyEqualsCallableSig(CallableSignature cSig)
    {
        // This works for Methods and Constructors.  This method used to be in the actual 'Method'
        // and 'Constructor' sub-class due to this one-line optimization.  (This is an un-necessary
        // check for Constructors, but not for methods).

        if (this.numParameters() != cSig.parameterNames.size()) return false;

        // If there are no parameters (for either of them), then return true immediately
        if (this.numParameters() == 0) return true;

        // If any of the parameter-names are different, break immediately and return false;
        for (int i=0; i < this.parameterNames.size(); i++)
            if (! this.parameterNames.get(i).equals(cSig.parameterNames.get(i)))
                return false;

        // If the parameter-types listed by the javadoc '.html' file differ from parameter-types
        // listed in the original '.java' source-code file, then break immediately.
        //
        // NOTE: The "package-information" for the FULL CLASS OR INTERFACE NAME is not always
        // available.

        for (int i=0; i < this.parameterTypes.size(); i++)
            if (! this.parameterTypesJOW.get(i).equals(cSig.parameterTypesJOW.get(i)))
                return false;

        // ALL TESTS PASSED
        return true;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // HELPERS - toString(int flags)
    // ********************************************************************************************
    // ********************************************************************************************


    String printedParamNames()
    {
        return
            "Parameter Names:    " +
            "[" + 
                ((parameterNames != null)
                    ? StrCSV.toCSV(parameterNames, true, true, null) : "") +
            "]\n";
    }

    String printedParamTypes(Torello.Java.Additional.Ret2<Boolean, Boolean> jow)
    {
        boolean b = parameterTypesJOW == null;

        if (jow.b /*onlyJOW*/) return
            "Simple Param-Types: " +
            "[" + 
                (b ? "" : StrCSV.toCSV(parameterTypesJOW, true, true, null)) +
            "]\n";

        else if (jow.a /*addJOW*/) return
            "Parameter Types:    " +
            "[" + 
                (b ? "" : StrCSV.toCSV(parameterTypes, true, true, null)) +
            "]\n" +
            "Simple Param-Types: " +
            "[" +
                (b ? "" : StrCSV.toCSV(parameterTypesJOW, true, true, null)) +
            "]\n";

        else return
            "Parameter Types:    " +
            "[" +
                (b ? "" : StrCSV.toCSV(parameterTypes, true, true, null)) +
            "]\n";
    }

    String printedExceptions()
    {
        return
            "Exceptions:         " +
            "[" +
                ((exceptions == null) ? "" : StrCSV.toCSV(exceptions, true, true, null)) +
            "]\n";
    }

    String printedCallableBody(int flags)
    {
        boolean methodBody      = (flags & BODY) > 0;
        boolean shortMethodBody = (flags & BODY_SHORT) > 0;

        // "shortMethodBody" has a higher FLAG-PRECEDENCE
        if (methodBody && shortMethodBody) methodBody = false;

        if ((! methodBody) && (! shortMethodBody)) return "";

        String bodyStr = (this.body != null) ? codeHiLiteString() : "Not Defined";

        // "Synthetic Methods" do not have a body.  Interface Methods also do not have one, either
        // If this was built from the JavaDoc Signature, it will *ALSO* have no body...

        if (shortMethodBody) bodyStr = StrPrint.abbrevEndRDSF(bodyStr, MAX_STR_LEN, true);

        if (    shortMethodBody
            ||  ((bodyStr.indexOf('\n') == -1) && (bodyStr.length() <= MAX_STR_LEN))
        )
            return "\nCallable Body:      [" + bodyStr + " ]";
        else if (methodBody)
            return "\nCallable Body:      [\n" + bodyStr + "\n]";
        else
            return "";   
    }

    /**
     * Dummy Method.  Overriden by Concrete Sub-Classes.
     * @see Method#toString()
     * @see Constructor#toString()
     */
    public String toString()
    { return "Callable is Abstract, all Concrete Sub-Classes Override this method."; }

    /**
     * Dummy Method.  Overriden by Concrete Sub-Classes.
     * @see Method#toString(int)
     * @see Constructor#toString(int)
     */
    public String toString(int flags)
    { return "Callable is Abstract, all Concrete Sub-Classes Override this method."; }


    // ********************************************************************************************
    // ********************************************************************************************
    // HELPERS - toString() - NO FLAGS
    // ********************************************************************************************
    // ********************************************************************************************


    String printedParameterNamesTS()
    {
        return
            "Parameter Names: [" + 
                    ((parameterNames == null)
                        ? ""
                        : StrCSV.toCSV(parameterNames, true, true, null)
                    ) + "]\n";
    }

    String printedParameterTypesTS()
    {
        return
            "Parameter Types: [" +
                    ((parameterTypesJOW == null)
                        ? ""
                        : StrCSV.toCSV(parameterTypesJOW, true, true, null)
                    ) + "]\n";
    }

    String printedExceptionsTS()
    {
        return
            "Exceptions:      [" +
                ((exceptions == null)
                    ? ""
                    : StrCSV.toCSV(exceptions, true, true, null)
                 ) + "]\n";
    }
}