package Torello.Browser.JsonAST;

import javax.json.JsonValue;
import javax.json.JsonArray; // JavaDoc Comment needs this

/**
 * Enumerates the limited set of values that the Chrome DevTools Protocol may assign to the
 * {@code "type"} property of its schema definitions. While the protocol data itself is exchanged
 * as JSON over WebSockets, these values are automatically bound into their corresponding Java
 * types by this library, allowing end-users to work with ordinary Java objects rather than raw
 * JSON.
 */
public enum TypeProp
{
    /**
     * Denotes a protocol value that binds to a structured Java {@code Object}.  When a CDP
     * {@code Type} is declared to be {@code OBJECT}, a {@link JsonArray} whose property name is
     * {@link PropName#PROPERTIES 'properties'} will be included that lists the type's various
     * fields.
     */
    OBJECT(JsonValue.class),
    // This is usuallly a reference

    /**
     * Denotes a protocol value that binds to a sequential Java {@code List}-like array.
     * Whenever a CDP {@code Type} or an {@code Event} is declared as an array, there will be a
     * corresponding {@link PropName#ITEMS 'items'} property which declares the array's component 
     * type.  (What the array's contents are going to be).
     */
    ARRAY(),
    // This must be a "reference"

    /** Denotes a protocol value that binds to a Java {@code String}. */
    STRING(String.class, String.class, String[].class),

    /** Denotes a protocol value that binds to a Java {@code int}-based numeric type. */
    INTEGER(int.class, Integer.class, int[].class),

    /** Denotes a protocol value that binds to a Java {@code double}-based numeric type. */
    NUMBER(Number.class, Number.class, Number[].class),

    /** Denotes a protocol value that binds to a Java {@code boolean}. */
    BOOLEAN(boolean.class, Boolean.class, boolean[].class),

    /**
     * API values described as {@code "Any"} are returned to the user as raw {@code JsonObject}.
     * Whenever a {@link PPR} (property, parameter or return-value) is declared to be of type
     * "Any", the corresponding method-parameter, class-field or return-value shall be declared to
     * be of type {@link JsonValue}.
     * 
     * <BR /><BR />In such cases, the actual raw JSON returned by the browser is passed on to the
     * user.
     */
    ANY(JsonValue.class);


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructors
    // ********************************************************************************************
    // ********************************************************************************************


    // The various types used by the Type-Simplifier

    /**
     * The "Computed Type, as a String" that is used whenever a property, parameter or return-value
     * is <B STYLE='color:red;'><I>NOT</I></B> declared <B STYLE='color:red;'><I>OPTIONAL</I></B>.
     * 
     * <BR /><BR />Java's "Boxed Types" are used whenever the CDP API specifies that a 
     * method-parameter, class-field or return-value is "optional."  In Java-HTML, in such cases,
     * the the field, parameter or value is assigned null when Chrome or the Browser have elided
     * or "left off" the value of a parameter, field or return-value.
     */
    public final Class<?> primCTAS;

    /**
     * The "Computed Type as a String" which is required whenever the CDP API specifies that a 
     * method-parameter, class-field or return-value is "optional."  This allows a 'null' to be 
     * assigned to such a field, parameter or return-value when the browser has left such 
     * information off.
     */
    public final Class<?> boxedCTAS;

    /**
     * The "Computed Type as a String" when the CDP API has specified that an "array of" a 
     * certain type shall be used.  Note that array's are already 'nullable', and as such,
     * there is no need whatsoever to used a "Array of Boxed Types."
     * 
     * <BR /><BR />
     * It is the case that the Browser could "elide" (leave off) the entire array when returning a
     * value, or specifying an Event-Type's field-values.  In that case, the array would simply be
     * assigned 'null.'  There is no need to actually allow the individual array element's to
     * accept Boxed-Type 'null' values.
     */
    public final Class<?> arrayCTAS;

    private TypeProp()
    {
        this.primCTAS   = null;
        this.boxedCTAS  = null;
        this.arrayCTAS  = null;
    }

    private TypeProp(final Class<JsonValue> _elided)
    { this.primCTAS = this.boxedCTAS = this.arrayCTAS = JsonValue.class; }

    private TypeProp(
            final Class<?> primCTAS,
            final Class<?> boxedCTAS,
            final Class<?> arrayCTAS
        )
    {
        this.primCTAS   = primCTAS;
        this.boxedCTAS  = boxedCTAS;
        this.arrayCTAS  = arrayCTAS;
    }
}