package Torello.Browser;

import Torello.JavaDoc.Annotations.LinkJavaSource;
import Torello.JavaDoc.Annotations.IntoHTMLTable;
import static Torello.JavaDoc.Annotations.IntoHTMLTable.Background.BlueDither;
import static Torello.JavaDoc.Annotations.IntoHTMLTable.Background.GreenDither;

import Torello.Java.StrCSV;
import Torello.Java.StrIndent;

import javax.json.JsonObject;

/**
 * An abstract base class for builder-style objects that collect named assignments
 * before producing a final CDP-related object.
 * 
 * <BR /><BR />
 * This class provides the common assignment machinery used by both {@link TypeBuilder}
 * and {@link CommandBuilder}.  Each assignment is checked against an
 * {@link AbstractDescriptor}, which supplies the valid names and expected CDP type
 * information for the builder.
 * 
 * <BR /><BR /><DIV CLASS=JDHint>
 * 📌 Concrete subclasses decide what {@link #build()} produces.  A {@link TypeBuilder}
 * produces a CDP data object, while a {@link CommandBuilder} produces a
 * {@link Script} that may be invoked against the browser.
 * </DIV> 
 * 
 * @param <T> The type produced by this builder's {@link #build()} method.
 *
 * @see TypeBuilder
 * @see CommandBuilder
 * @see AbstractDescriptor
 */
public abstract class AbstractBuilder<T>
    implements java.io.Serializable, Cloneable
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1L;

    /**
     * The descriptor used by this builder.  It provides the names, expected types, and ordering
     * for each named assignment accepted by this builder.
     * 
     * <BR /><BR /><DIV CLASS=JDHint>
     * 👉 For {@link TypeBuilder}, these names correspond to fields in a CDP data type.  For
     * {@link CommandBuilder}, they correspond to input parameters for a CDP command.
     * </DIV>
     */
    public final AbstractDescriptor descriptor;

    // Chat-GPT says:
    // 
    // No. Do NOT initialize them manually. Java already guarantees this completely and absolutely.
    // I forget how this works all the time...
    // 
    // already produces:
    //      * every assignments[i] == null
    //      * every assigned[i] == false

    // The values being assigned to the builder
    final Object[] assignments;

    // Because 'null' is a legitimate value, this array is needed.
    final boolean[] assigned;


    // ********************************************************************************************
    // ********************************************************************************************
    // (PRIMARY PURPOSE of this class)
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convert 'this' Builder-Instance into an actual Object-Instance 
     * @return An instance of {@code T}
     */
    public abstract T build();


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructors & Static "Create a new Builder-Instance" Method
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Protected constructor used by the two {@code AbstractBuilder} subclasses.
     * @param descriptor The descriptor for the class or object which is ultimately being built
     * 
     * @see NestedDescriptor 
     * @see NestedHelper#descriptor()
     * @see CommandDescriptor
     */
    protected AbstractBuilder(final AbstractDescriptor descriptor)
    {
        this.descriptor     = descriptor;
        this.assignments    = new Object[descriptor.size];
        this.assigned       = new boolean[descriptor.size];
    }

    /**
     * Protected constructor used by the {@code 'clone()'} method, inside the two concrete 
     * subclasses of this type.
     * 
     * @param other Another instance of this class
     */
    protected AbstractBuilder(final AbstractBuilder<T> other)
    {
        this.descriptor     = other.descriptor;
        this.assignments    = other.assignments.clone();
        this.assigned       = other.assigned.clone();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // The Primary / General Purpose Accept-Method
    // ********************************************************************************************
    // ********************************************************************************************


    // The internally used 'accept()' method, invoked by all the other accept methods in this class
    private AbstractBuilder<T> accept(
            final String    name,
            final Object    value,
            final byte      providedType
        )
    {
        final int index = descriptor.names.indexOf(name);

        if (index < 0) throw new AssignmentNameException(name, this.descriptor);

        final byte expectedType = descriptor.types.get(index);

        if (providedType != expectedType) throw new TypeAssignmentException
            (providedType, expectedType, name, this.descriptor);

        if ((expectedType == CDPTypes.CDP_TYPE) || (expectedType == CDPTypes.CDP_TYPE_ARRAY_1D))
            descriptor.checkValueType(value, index);

        assignments[index]  = value;
        assigned[index]     = true;

        return this;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Accept-Methods: CDP Types 
    // ********************************************************************************************
    // ********************************************************************************************


    /** <EMBED CLASS=external-html DATA-PARAM=bt DATA-TYPE='BaseType<?>' DATA-FILE-ID=AB.IHT> */
    @IntoHTMLTable(
        title="Assign a CDP Class (extends BaseType<>) to a Builder Input",
        background=BlueDither
    )
    public AbstractBuilder<T> accept(final String name, final BaseType<?> bt)
    { return accept(name, bt, CDPTypes.CDP_TYPE); }

    /** <EMBED CLASS=external-html DATA-PARAM=btArr DATA-TYPE='BaseType[]' DATA-FILE-ID=AB.IHT> */
    @IntoHTMLTable(
        title="Assign an Array of BaseType<?> (any CDP Class) to a Builder Input",
        background=GreenDither
    )
    public AbstractBuilder<T> accept(final String name, final BaseType<?>[] btArr)
    { return accept(name, btArr, CDPTypes.CDP_TYPE_ARRAY_1D); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Accept-Methods: Standard Java Types
    // ********************************************************************************************
    // ********************************************************************************************


    /** <EMBED CLASS=external-html DATA-PARAM=i DATA-TYPE='int' DATA-FILE-ID=AB.IHT> */
    @IntoHTMLTable(
        title="Assign an 'int' Primitive to a Named Builder-Input",
        background=BlueDither
    )
    public AbstractBuilder<T> acceptInt(final String name, final int i)
    { return accept(name, i, CDPTypes.PRIMITIVE_INT); }

    /** <EMBED CLASS=external-html DATA-PARAM=i DATA-TYPE='Integer' DATA-FILE-ID=AB.IHT> */
    @IntoHTMLTable(
        title="Assign a java.lang.Integer to a Named Builder-Input",
        background=GreenDither
    )
    public AbstractBuilder<T> accept(final String name, final Integer i)
    { return accept(name, i, CDPTypes.BOXED_INTEGER); }

    /** <EMBED CLASS=external-html DATA-PARAM=b DATA-TYPE='boolean' DATA-FILE-ID=AB.IHT> */
    @IntoHTMLTable(
        title="Assign a 'boolean' primitive to a Named Builder-Input",
        background=BlueDither
    )
    public AbstractBuilder<T> acceptBool(final String name, final boolean b)
    { return accept(name, b, CDPTypes.PRIMITIVE_BOOLEAN); }

    /** <EMBED CLASS=external-html DATA-PARAM=b DATA-TYPE='Boolean' DATA-FILE-ID=AB.IHT> */
    @IntoHTMLTable(
        title="Assign a java.lang.Boolean to a Named Builder-Input",
        background=GreenDither
    )
    public AbstractBuilder<T> accept(final String name, final Boolean b)
    { return accept(name, b, CDPTypes.BOXED_BOOLEAN); }

    /** <EMBED CLASS=external-html DATA-PARAM=s DATA-TYPE='String' DATA-FILE-ID=AB.IHT> */
    @IntoHTMLTable(
        title="Assign a String to a Named Builder-Input",
        background=BlueDither
    )
    public AbstractBuilder<T> accept(final String name, final String s)
    { return accept(name, s, CDPTypes.STRING); }

    /** <EMBED CLASS=external-html DATA-PARAM=n DATA-TYPE='Number' DATA-FILE-ID=AB.IHT> */
    @IntoHTMLTable(
        title="Assign a java.lang.Number to a Named Builder-Input",
        background=GreenDither
    )
    public AbstractBuilder<T> acceptNumber(final String name, final Number n)
    { return accept(name, n, CDPTypes.NUMBER); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Accept-Methods: One Dimensional Array Types
    // ********************************************************************************************
    // ********************************************************************************************


    /** <EMBED CLASS=external-html DATA-PARAM=arr1D DATA-TYPE='int[]' DATA-FILE-ID=AB.IHT> */
    @IntoHTMLTable(
        title="Assign an int[]-Array to a Named Builder-Input",
        background=BlueDither
    )
    public AbstractBuilder<T> accept(final String name, final int[] arr1D)
    { return accept(name, arr1D, CDPTypes.INT_ARRAY_1D); }

    /** <EMBED CLASS=external-html DATA-PARAM=arr1D DATA-TYPE='boolean[]' DATA-FILE-ID=AB.IHT> */
    @IntoHTMLTable(
        title="Assign a boolean[]-Array to a Named Builder-Input",
        background=GreenDither
    )
    public AbstractBuilder<T> accept(final String name, final boolean[] arr1D)
    { return accept(name, arr1D, CDPTypes.BOOLEAN_ARRAY_1D); }

    /** <EMBED CLASS=external-html DATA-PARAM=arr1D DATA-TYPE='String[]' DATA-FILE-ID=AB.IHT> */
    @IntoHTMLTable(
        title="Assign a String[]-Array to a Named Builder-Input",
        background=BlueDither
    )
    public AbstractBuilder<T> accept(final String name, final String[] arr1D)
    { return accept(name, arr1D, CDPTypes.STRING_ARRAY_1D); }

    /** <EMBED CLASS=external-html DATA-PARAM=arr1D DATA-TYPE='Number[]' DATA-FILE-ID=AB.IHT> */
    @IntoHTMLTable(
        title="Assign a Number[]-Array to a Named Builder-Input",
        background=GreenDither
    )
    public AbstractBuilder<T> accept(final String name, final Number[] arr1D)
    { return accept(name, arr1D, CDPTypes.NUMBER_ARRAY_1D); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Accept-Methods: Two Dimensional Array Types
    // ********************************************************************************************
    // ********************************************************************************************


    /** <EMBED CLASS=external-html DATA-PARAM=arr2D DATA-TYPE='int[][]' DATA-FILE-ID=AB.IHT> */
    @IntoHTMLTable(
        title="Assign a Two Dimensional int[][]-Array to a Named Builder-Input",
        background=BlueDither
    )
    public AbstractBuilder<T> accept(final String name, final int[][] arr2D)
    { return accept(name, arr2D, CDPTypes.INT_ARRAY_2D); }

    /** <EMBED CLASS=external-html DATA-PARAM=arr2D DATA-TYPE='boolean[][]' DATA-FILE-ID=AB.IHT> */
    @IntoHTMLTable(
        title="Assign a Two Dimensional boolean[][]-Array to a Named Builder-Input",
        background=GreenDither
    )
    public AbstractBuilder<T> accept(final String name, final boolean[][] arr2D)
    { return accept(name, arr2D, CDPTypes.BOOLEAN_ARRAY_2D); }

    /** <EMBED CLASS=external-html DATA-PARAM=arr2D DATA-TYPE='String[][]' DATA-FILE-ID=AB.IHT> */
    @IntoHTMLTable(
        title="Assign a Two Dimensional String[][]-Array to a Named Builder-Input",
        background=BlueDither
    )
    public AbstractBuilder<T> accept(final String name, final String[][] arr2D)
    { return accept(name, arr2D, CDPTypes.STRING_ARRAY_2D); }

    /** <EMBED CLASS=external-html DATA-PARAM=arr2D DATA-TYPE='Number[][]' DATA-FILE-ID=AB.IHT> */
    @IntoHTMLTable(
        title="Assign a Two Dimensional java.lang.Number[][]-Array to a Named Builder-Input",
        background=GreenDither
    )
    public AbstractBuilder<T> accept(final String name, final Number[][] arr2D)
    { return accept(name, arr2D, CDPTypes.NUMBER_ARRAY_2D); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Unknown, Raw JSON
    // ********************************************************************************************
    // ********************************************************************************************


    /** <EMBED CLASS=external-html DATA-PARAM=jo DATA-TYPE='JsonObject' DATA-FILE-ID=AB.IHT> */
    @IntoHTMLTable(
        title="Assign a Raw JsonObject to a Named Builder-Input",
        background=BlueDither
    )
    public AbstractBuilder<T> accept(final String name, final JsonObject jo)
    { return accept(name, jo, CDPTypes.RAW_JSON_VALUE); }


    // ********************************************************************************************
    // ********************************************************************************************
    // MISC
    // ********************************************************************************************
    // ********************************************************************************************



    /**
     * Explicitly assigns {@code null} to a Named Builder-Input.
     * 
     * <BR /><BR /><DIV CLASS=JDHint>
     * 🤷 If there is ever a need to ensure that an object property found in a {@link JsonObject}
     * that is being transmitted over a web socket (and towards a browser) has an actual
     * {@link javax.json.JsonValue#NULL Json-Null} intentionally assigned to it, then invoking this
     * method should be utilized.
     * 
     * 🧠 This method guarantees that the internal {@code isPresent} boolean list is assigned 
     * {@code TRUE}, despite the fact that its value is still null.
     * </DIV>
     * 
     * @param name The name of the Builder-Input to which {@code null} shall be assigned.
     * @return {@code 'this'} instance for invocation chaining
     * 
     * @throws AssignmentNameException if {@code 'name'} is not listed by this builder's
     * descriptor.
     * 
     * @see NestedDescriptor#names
     */
    public AbstractBuilder<T> acceptNull(final String name)
    {
        final int index = this.descriptor.names.indexOf(name);

        if (index < 0) throw new AssignmentNameException(name, this.descriptor);

        assignments[index]  = null;
        assigned[index]     = true;

        return this;
    }

    /**
     * Clears any value which may or may not have been assigned to a Named Builder-Input.
     * 
     * @param name The name of the Builder-Input that the programmer would like cleared.
     * @return {@code 'this'} instance for invocation chaining
     * 
     * @throws AssignmentNameException if {@code 'name'} is not listed by this builder's descriptor.
     * 
     * @see AbstractDescriptor#names
     */
    public AbstractBuilder<T> clear(final String name)
    {
        final int index = this.descriptor.names.indexOf(name);

        if (index < 0) throw new AssignmentNameException(name, this.descriptor);

        assignments[index]  = null;
        assigned[index]     = false;

        return this;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.lang.Object
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Generate an insightful String representation of {@code 'this'} instance
     * <EMBED CLASS='external-html' DATA-JDHC=JDHint DATA-FILE-ID=AbstractFinalMethod>
     * @return A Java {@code String}
     */
    @Override
    public final String toString()
    { return CDPToString.toString(this); }

    /**
     * Check whether {@code 'this'} instance is equal to input parameter {@code 'o'}
     * 
     * <EMBED CLASS='external-html' DATA-JDHC=JDHint DATA-FILE-ID=AbstractFinalMethod>
     * 
     * @param o Any Java Object.  Only another builder instance of the exact same runtime class,
     * with the same descriptor and current assignment values, will return {@code TRUE}.
     * 
     * @return {@code TRUE} if and only if {@code 'this'} is equal to {@code 'o'}.
     */
    @Override
    public final boolean equals(final Object o)
    {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;

        final AbstractBuilder<?> that = (AbstractBuilder<?>) o;

        return
                this.descriptor.equals(that.descriptor)
            &&  java.util.Arrays.equals(this.assignments, that.assignments)
            &&  java.util.Arrays.equals(this.assigned, that.assigned);
    }

    
    /**
     * Generate a hashcode integer which may be used for placing this object into a hashtable
     * data structure.
     * 
     * <EMBED CLASS='external-html' DATA-JDHC=JDHint DATA-FILE-ID=AbstractFinalMethod>
     * 
     * @return A (hopefully unique) integer value
     */
    @Override
    public final int hashCode()
    {
        int result = this.descriptor.hashCode();
        result = 31 * result + java.util.Arrays.hashCode(this.assignments);
        return result;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.lang.Cloneable
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Clone the current instance
     * 
     * @return An identical copy of {@code 'this'}.
     * 
     * <BR /><BR /><DIV CLASS=JDHintAlt>
     * 🔍 The concept known as a "Deep Clone" means that the internals of a type are also
     * copied to the new instance.  What is returned by this method is a "Partial Deep Clone" of
     * {@code 'this'} instance.
     * 
     * <BR /><BR />
     * 🧠 Since the internal {@code 'descriptor'} instance is a read only, singleton instance,
     * cloning it wouldn't have any real significance.  Thus, the internal {@code 'descriptor'}
     * isn't cloned into the new instance; its reference is merely copied instead.
     * 
     * <BR /><BR />
     * 🎯 However, the two internal value-assignment arrays are cloned, resulting in a separate
     * instance which has its own, independent assignments.
     * </DIV>
     */
    @Override
    public abstract AbstractBuilder<T> clone();

}