package Torello.Browser.JsonAST;

import Torello.JSON.ReadJSON;

import Torello.Java.Additional.Ret2;

import javax.json.JsonObject;

/**
 * Extracts the Json Property {@code "type"} from the {@link JsonObject} which defines an
 * {@link Entity} instance, and converts that {@code String} into an instance of {@link TypeProp}.
 * This class also extracts, if present, the {@code "type"} property from within an {@code "items"}
 * {@code JsonObject}.  These (the second) {@code "type"} are used <B STYLE='color:red;'><I>if and
 * only if</B></I> the first {@code "type"} has a value of {@link TypeProp#ARRAY "array"}, and 
 * subsequently requires a definition for the Array's Base-Component Class.
 * 
 * <BR /><BR />The only values which are ever assigned to the Json {@code "type"} property will 
 * directly correspond to one of the enum constants listed inside the {@link TypeProp} enum.  
 * It is of utmost important to remember, that if a {@link PPR} has a "Type" that is actually one 
 * of the specified types from the spec files (rather than something simple like {@code 'integer'} 
 * or {@code 'string'}), that {@code PPR} will not even use the Json {@code "type"} property.  
 * 
 * <BR /><BR />Instead, the {@code "$ref"} property will contain a "Reference as a String" (which 
 * will later require linkinig) that gives the name of the class / type of which the {@code PPR}
 * is a reference.
 */
@Torello.JavaDoc.Annotations.StaticFunctional
@Torello.JavaDoc.Annotations.JDHeaderBackgroundImg(EmbedTagFileID="CONSTRUCTOR_JDHBI")
public class Helper$TypeProps 
{
    private Helper$TypeProps() { }

    private static final Ret2<TypeProp, TypeProp> EMPTY_RET2 = new Ret2<>(null, null);

    static Ret2<TypeProp, TypeProp> get(final JsonObject jo)
    {
        // getString(JsonObject jo, String propertyName, boolean isOptional, boolean throwOnNull)
        final String typePropStr = ReadJSON.getString(jo, "type", true, true);


        // If there is no "type" Json-Property, then there is a zero 0% chance that there is going
        // to be an "items" Json-Property.  As such, if 'typePropStr' is null, return 2 nulls
        // immediately.

        if (typePropStr == null) return EMPTY_RET2;

        // Conver the "type" String into an insance of the TypeProp enum....
        final TypeProp typeProp = TypeProp.valueOf(typePropStr.toUpperCase());


        // Similar to before, but ...  Here, if there did happen to be a "type" Json Property, 
        // unless that "type" equaled the String "array", then there (again) is a zero 0% chance 
        // that there is going to be an "items" Json-Property.  If it was something other than 
        // "array", return the first TypeProp enum instance immediately, and null for the items 
        // TypeProp instance.

        if (typeProp != TypeProp.ARRAY) return new Ret2<>(typeProp, null);


        // Here, if this line of code is reached, then the "items" Json Property is not goingt to 
        // be optional.  This ReadJSON invocation will throw an exception if the "items" property
        // isn't available inside the input JsonObject / 'jo' instance.
        // 
        // getJsonObject(JsonObject, String propertyName, boolean isOptional, boolean throwOnNull)

        final JsonObject arrItemsProp = ReadJSON.getJsonObject(jo, "items", false, true);


        // Lastly, now that we have the "items" Json Property, which is actually another / inner
        // JsonObject, we need to extract the contents of this JsonObject.  This inner JO, which is
        // being called "arrItemsProp" may have exactly one of two different Json Properties
        // itself.  They are:
        // 
        //      1) "type": "some-type"
        //      2) "$ref": "some-TypeNode-Name"
        // 
        // If the caller of this method is a constructor for a PPR, then this "items" Json-Object
        // could just as easily be a "$ref" array, as it could be a "type" array.  If the caller of
        // this method is a TypeNode, it would only be possible for this "items" Json-Object to be 
        // a 'jo' that contains a "type" property, itself.  TypeNode TCE's may not be declared as 
        // array's of references.  Only PPR's may have array's of references.
        // 
        // In such cases, if the "items" 'jo' isn't an object that has a "type" Json-Property, then
        // by definition it must have a "$ref" Json-Property instead.  This is where an 'Entity' is
        // being declared as an array of some other declared type.  If this were Java instead of 
        // JSON, it would be like declaring an array of some Java-Class, rather than a primitive 
        // array such as 'int[]' or 'boolean[]'
        // 
        // If the Entity is an array of "$ref", then we need to just return null in place of the 
        // 2nd TypeProp Parameter.  This is going to be done intentionally.  What this actually 
        // means is that if an "Entity" - which is the Root Object Inheritance Class for all AST
        // Nodes - is declared as an "array", but the "component class" (Java calls the class about
        // which an array is declared as the "component" class) is an actual object rather than a 
        // primitive, then that component class is going to be extracted and computed by another
        // constructor, elswhere in this package's source code.
        // 
        // This is because there is only, single, kind of AST Node that is permitted to declare 
        // array's of references - PPR Nodes.  If a TCE is declared as an "array", it must be a 
        // "simple array" - using one of types that are listed in the "TypeProp" enum.
        // 
        // *** NOTE: The TypeProp 'enum' is **NEARLY** but not identical to Java-Primitives.
        // 
        // 1) First, Java Class 'java.lang.String' is one of the types listed in TypeProp - which
        //    is not a Java-Primitive, but it is treated like a "Simple Type" - not a
        //    Reference-Type in this package.  In the JsonAST Package "Reference Types" are types
        //    which point to ANOTHER DECLARED TYPE FROM THIS VERY JSON-AST TREE!  
        // 
        //    For Example: In the "JavaScript API", inside the "RunTime Domain", there is a type 
        //    called "RunTime.RemoteObject" - **THAT** would be a "$ref" type.
        //    A PPR whose "type" was "RunTime.RemoteObject[]" would be a reference array
        //    While a PPR whose Type was "String[]" would be treated like a simple array
        // 
        // 2) Second, class "Number" does not directly map to a Java Primitive.  It is unknown
        //    whether a browser which is connected over the Web-Sockets will switch back and forth
        //    between "integer" and "float" types.  However, if the specifications JSON File 
        //    declares a PPR to be a "number" rather than an "integer", such a declaration is 
        //    treated as if the browser may return either an integer or a real number.
        // 
        //    As such, the Java Boxed-Type "Number" is used, which allows for both class
        //    'java.lang.Integer' and also 'java.lang.Double'.  The Java-HTML 'ReadJSON' package'
        //    ReadJSON class is good about figuring out which of the two to return.
        // 
        // 
        // getString(JsonObject jo, String propertyName, boolean isOptional, boolean throwOnNull)
        // PAY CLOSE ATTENTION: 'isOption' ==> TRUE  (won't throw if this Json-Property is missing)

        final String arrType  = ReadJSON.getString(arrItemsProp, "type", true, true);


        // If It was missing, just leave it off.  The PPR Construtor will look for a "$ref"
        // Property instead.  It will even throw there if there also happens to not be a "$ref"
        // property inside the "items" Json Object either!

        if (arrType == null) return new Ret2<>(typeProp, null);

        // It wasn't null, so there was a "type" property inside the "items" Json Object.
        final TypeProp arrTypeProp = TypeProp.valueOf(arrType.toUpperCase());

        return new Ret2<>(typeProp, arrTypeProp);
    }

}