package Torello.JavaDoc;


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

import java.io.IOException;
import java.sql.CallableStatement;
import java.util.Optional;


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

import Torello.Java.*;

import static Torello.JavaDoc.PF.*;

import Torello.Java.Additional.Ret4;

import Torello.JDUInternal.DataClasses.MainLoopData.CallableSignature;


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

import com.sun.source.tree.MethodTree;


/**
 * <B STYLE='color:darkred;'>Reflection Class:</B>
 * 
 * Holds all information extracted from <CODE>'&#46;java'</CODE> Source-Files about
 * Constructor's identified in that file.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=JPB_GET_INST>
 * <EMBED CLASS='external-html' DATA-FILE-ID=JPB_CONSTRUCTOR>
 * <EMBED CLASS='external-html' DATA-FILE-ID=JPB_DIAGRAM>
 */
@JDHeaderBackgroundImg(EmbedTagFileID={"REFLECTION_EXTENSION"})
public class Constructor extends Callable
    implements java.io.Serializable, Comparable<Constructor>, Cloneable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    public static final long serialVersionUID = 1;


    // ********************************************************************************************
    // ********************************************************************************************
    // Reference-Hook: com.sun.source.tree
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SSTB_HOOK_FIELD>
     * 
     * If a user decides to make use of the native Sun/Oracle {@code MethodTree} instance that was
     * used to build this {@code Constructor} instance, it may be retrieved from this
     * {@code transient} field.
     * 
     * <BR /><BR /><B>NOTE:</B> The package {@code com.sun.source.tree} "reuses" or "overloads" the
     * {@code MethodTree} object such that it may represent either a Method, or a Constructor.
     * When a {@code MethodTree} instance is actually representing a constructor, the name that is
     * used for the instance will be {@code '<init>'}, rather than a method that abides by the 
     * standard Java naming conventions.
     */
    public final transient MethodTree methodTree;


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


    /**
     * <EMBED CLASS="defs" DATA-KIND=Constructor DATA-ENTITY=MethodTree>
     * <EMBED CLASS='external-html' DATA-FILE-ID=RC_DESCRIPTION>
     * @param mt <EMBED CLASS='external-html' DATA-FILE-ID=RC_PARAM_TREE>
     * @param util <EMBED CLASS='external-html' DATA-FILE-ID=RC_PARAM_UTIL>
     * @param constructorName The name of the type (which is also the name of the constructor) has
     * to be passed here, in order for this constructor to work.
     */
    public Constructor(MethodTree mt, TreeUtils util, String constructorName)
    {
        super(mt, constructorName, Entity.CONSTRUCTOR, util);

        // Only the 2 reference hooks are needed here
        this.methodTree = mt;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor: Used Internally by SignatureParse
    // ********************************************************************************************
    // ********************************************************************************************


    // Ensures that the Version with longer type-information strings is used.
    // Java Doc often uses longer type strings than is available from the source-code parse
    // Remember, JavaParser Symbol-Solver doesn't work well, and the Sun/Oracle Parser doesn't have
    // a linker at all.

    public Constructor(CallableSignature cSig, Constructor cFromSourceParser)
    {
        // Does the same thing as the loop statement below, but for the "parameterTypes"
        super(cSig, cFromSourceParser);

        this.methodTree = cFromSourceParser.methodTree;
    }

    // This is only used to construct a constructor for SYNTHETIC-CONSTRUCTORS.  At the present
    // moment, that means this is only used when there is a Zero-Argument Constructor that the user
    // did not actually type into his code, but rather is being auto-added by javac.

    public Constructor(CallableSignature cSig)
    {
        super(cSig, Entity.CONSTRUCTOR);

        this.methodTree = null;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // toString()
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Generates a string of this constructor, with most information included.
     * 
     * <BR /><BR /><B>NOTE:</B> This will not return every piece of information contained by this
     * class. For example, both the constructor body, and any possible JavaDoc Comments are not
     * included.  For a more enhanced {@code toString()} version, call the one that accepts flags.
     * 
     * @return A printable string of this field.
     * 
     * @see PF
     * @see #toString(int)
     * @see StrCSV#toCSV(String[], boolean, boolean, Integer)
     */
    public String toString()
    {
        return
            "Name:            [" + name + "]\n" +
            "Signature:       [" + StrPrint.abbrevEndRDSF(signature, MAX_STR_LEN, true) + "]\n" +
            "Modifiers:       [" + StrCSV.toCSV(modifiers, true, true, null) + "]\n" +
            printedParameterNamesTS() +
            printedParameterTypesTS() +
            printedExceptionsTS() +

            // This will **NEVER** be null - unless 'this' instance was built from an HTML File,
            // rather than a source-code file.  Instances like that are only used temporarily, and
            // are garbage collected instantly.  Do this check anyway (just in case).

            "Location:        " + ((this.location == null)
                ? "null" 
                : ('[' + this.location.quickSummary() + ']'));
    }

    /**
     * This class expects a flags that has been masked using the constant ({@code public, static,
     * final int}) fields of class {@link PF}.  Please view this class for more information about
     * the flags available for modifying the return-value of this {@code toString()} method.
     * 
     * @param flags These are the {@code toString} flags from class PF ("Print Flags").  View
     * available flags listed in class {@link PF}.
     * 
     * @return A printable {@code String} of this {@code Constructor}, with comment information
     * included as well.
     * 
     * @see #toString()
     * @see StrCSV#toCSV(String[], boolean, boolean, Integer)
     * @see PF
     */
    public String toString(int flags)
    {
        boolean color = (flags & UNIX_COLORS) > 0;

        return
            printedName("Constructor", 20, color) + 
            printedSignature(20, color) +
            printedModifiers(20) +
            printedParamNames() + 
            printedParamTypes(jowFlags(flags)) +
            printedExceptions() +
            printedLocation(20, color, (flags & BRIEF_LOCATION) > 0) +

            // The previous method does not add a '\n' end to the end of the returned string
            // These are both optional, they add a '\n' AT THE BEGINNING if one of them is included

            printedComments(20, color, (flags & JAVADOC_COMMENTS) > 0) +
            printedCallableBody(flags);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    //  CompareTo and Equals
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Java's {@code interface Comparable<T>} requirements.  This looks at the number of
     * parameters, and parameter types in making a sort-decision.
     * 
     * @param c Any other {@code Constructor} to be compared to {@code 'this' Constructor}
     * 
     * @return An integer that fulfils Java's {@code interface Comparable<Constructor> public
     * boolean compareTo(Constructor c)} method requirements.
     */
    public int compareTo(Constructor c)
    {
        if (this == c) return 0;

        int ret = this.numParameters() - c.numParameters();
        if (ret != 0) return ret;

        if (this.parameterTypesJOW != null)

            for (int i=0; i < this.parameterTypesJOW.size(); i++)
            {
                ret = this.parameterTypesJOW.get(i).compareTo(c.parameterTypesJOW.get(i));
                if (ret != 0) return ret;
            }

        return 0;
    }

    /**
     * This <I>should be called an "atypical version" of</I> the usual
     * {@code equals(Object other)} constructor.  This version of equals merely compares the name
     * and parameters-list of the constructor.  The presumption here is that the definition of a
     * 'constructor' only has meaning - <I>at all</I> - inside the context of a {@code class} or
     * {@code enumerated-type} where that constructor is defined. Since inside any {@code '.java'}
     * source-code file, there may only be one constructor with a given parameter-list, this shall
     * return {@code TRUE} whenever the constructor being compared has the same parameter types as
     * {@code 'this'} does.
     * 
     * @param other This may be any other constructor.  It is <I><B>strongly suggested</B></I> that
     * this be a constructor defined in the same {@code '.java'} source-code file as 'this'
     * constructor.
     * 
     * @return This method returns {@code TRUE} when 'this' instance of Constructor has the same
     * parameter-list as {@code 'other'}.
     */
    public boolean equals(Constructor other)
    {
        // If the number of parameters in the 'other' instance of Constructor differ from the
        // number of parameters in 'this' Constructor, then return FALSE immediately.  It cannot be
        // a match

        if (this.numParameters() != other.numParameters()) 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(other.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(other.parameterTypesJOW.get(i)))
                return false;

        // ALL TESTS PASSED
        return true;
    }
}