package Torello.Browser.JsonAST;

import Torello.JavaDoc.Annotations.LinkJavaSource;
import Torello.JavaDoc.Annotations.JDHeaderBackgroundImg;

import Torello.Java.ReadOnly.ReadOnlyList;
import Torello.Java.ReadOnly.ReadOnlySet;
import Torello.Java.ReadOnly.ReadOnlyTreeSet;
import Torello.JSON.ReadJSON;

import javax.json.JsonObject;

import java.util.Objects;

// Class TCE is used to parse JSON Object Arrays of three varieties.  The first, 'types' define
// Java-Script Object-Classes that are returned from Java Script functions, and passed as
// parameters to Java-Script functions.  The second kind of 'TCE' (the letter 'C' in 'TCE' are
// 'commands'.  These specify the Java-Script functions themselves.  The 'E' in this acronym means
// 'events'.  The events describe the parameters that are passed to Java Script Event Handlers.
// 
/**
 * An Java Object used within AST to symbolize or encapsulate the data present in any of the 
 * {@link JsonObject JsonObject's} found within a {@link Domain Domain's} {@code "commands"} array.
 * <EMBED CLASS='external-html' DATA-FILE-ID=AST_TREES>
 */
@JDHeaderBackgroundImg(EmbedTagFileID="AST_NODES_JDHBI")
public class CommandNode extends TCE implements java.io.Serializable
{
    // ********************************************************************************************
    // ********************************************************************************************
    // STATIC FINAL FIELDS
    // ********************************************************************************************
    // ********************************************************************************************


    // Required by the Serializable interface
    protected static final long serialVersionUID = 1;

    /**
     * The list of additional {@link JsonObject} properties that the parser should expect when
     * parsing {@code CommandNode} objects from the JSON CDP specification files.
     */
    protected static final ReadOnlySet<String> COMMAND_JSON_PROPERTIES_SET =
        new ReadOnlyTreeSet<>(String::compareTo, "name", "parameters", "returns", "redirect");


    // ********************************************************************************************
    // ********************************************************************************************
    // Constant & Final Instance-Fields (Set by the Constructor)
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This field contains the raw {@code String} value of the {@code "redirect"} Json Property.  
     * <EMBED CLASS='external-html' DATA-FILE-ID=CommandNode.redirect>
     */
    public final String redirect;

    /**
     * Flag which indicates whether the CDP Command represented by this node returns multiple 
     * values, which therefore necessitates a dedicated inner type to represesnt those return
     * values.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=CommandNode.hasReifiedRetInnerClass>
     */
    public final boolean hasReifiedRetInnerClass;

    /**
     * A {@link PPR} list which, during the Code Generator Phase, is translated into the input
     * parameters for the Java Method which ultimately materializes and implements this CDP
     * Command.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=CommandNode.parameters>
     */
    public final ReadOnlyList<PPR> parameters;

    /**
     * A {@link PPR} list which, during the Code Generator Phase, is translated into the output
     * return values of the Java Method which ultimately materializes and implements this CDP
     * Command.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=CommandNode.returns>
     */
    public final ReadOnlyList<PPR> returns;


    // ********************************************************************************************
    // ********************************************************************************************
    // Non-Final Instance-Fields: These are initialized **LATE**, by the Linker
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This method retrieves the value of a {@code private} field which isn't assigned inside of 
     * the constructor, but rather during the Linking Phase, and is therefore not declared 
     * {@code final}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=CommandNode.redirectDomain>
     */
    public Domain redirectDomain() { return redirectDomain; }
    private Domain redirectDomain = null;

    // API-Invisible, Packge-Private Method: The Linker uses this, and sets the "Redirect Domain"
    void setRedirectDomain(final Domain redirectDomain)
    { this.redirectDomain = redirectDomain; }


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor
    // ********************************************************************************************
    // ********************************************************************************************


    // Constructs a class that represents a Java-Script 'type', 'command' or 'event'
    CommandNode(
            // The domain to which this 'type', 'command' or 'event' belongs
            final Domain ownerDomain,

            // The JSON Object representation of this 'TCE'
            final JsonObject jo,

            // The JSON Array index from which this JSON Object was retrieved.
            final int index
        )
    {
        super(
            ownerDomain,
            jo,
            WhichTCE.Command,
            COMMAND_JSON_PROPERTIES_SET,
            index
        );

        // getString(JsonObject jo, String propertyName, boolean isOptional, boolean throwOnNull)
        this.redirect = ReadJSON.getString(jo, "redirect", true, true);

        this.parameters = Helper$GetPPRLists.get(this, jo, WhichPPR.Parameter);
        this.returns    = Helper$GetPPRLists.get(this, jo, WhichPPR.Return);

        // This is the decision: multiple return values necessitates a dedicated inner class
        this.hasReifiedRetInnerClass = (this.returns != null) && (this.returns.size() > 1);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // CommandNode → **MAY NOT** have a "type" JsonProperty ==> 100% pass / TRUE / invariant
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        if (this.typeProp != null)
            verifyThrow("CommandNode TCE illegally declares a \"type\" Json property.");

        // This check is IDENTICAL to (a subset of) the previous check.  Just here to remind you
        if (this.arrItemsTypeProp != null)
            verifyThrow("This has an array field, but it is a CommandNode TCE");

        if (this.enumVals != null)
            verifyThrow("CommandNode TCE illegally declares an \"enum\" Json property.");
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // to string
    // ********************************************************************************************
    // ********************************************************************************************


    /** Returns a {@code String} representation of {@code 'this'} instance. */
    @LinkJavaSource(handle="StringTCE")
    public String toString()
    { return StringTCE.get(this); }
}