Class TypeNode

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<Entity>, java.lang.Iterable<PPR>
    public class TypeNode
extends TCE
implements java.io.Serializable, java.lang.Iterable<PPR>
    The class class comprises the intended public facing API for the JsonAST-Package. It is easy to load the Abstract Syntax Tree's from disk by invoking the deserializeFromJAR() method inside of class SERIALIZED_AST. Remember that the entire package Torello.Browser.JsonAST is used primarily by a proprietary, and yet unreleased code generator, and is only made public for informational & reference purposes.

    Loading the the serialized trees from the '.jar' file, perhaps, may elucidate some of Google's Browser CDP API. The nodes themselves have quite a bit of read only data available.
    An Java Object used within AST to symbolize or encapsulate the data present in any of the JsonObject's found within a Domain's "types" array.

    The following two tree diagrams, with explanation, are repeated verbatim across all eight AST Node Classes.

    Object Inheritance for AST Nodes, and RunTime Tree Organization

    The Objects which are generated by the JSON Parser are converted into AST Node Object-Instances, all of which are listed here, below. An in depth study of the CDP Specification, a programmer must realize that there are actually three (possibly four) different trees functioning simultaneously. The Classes themselves have their own "Inheritance Tree." Then, additionally, by its very nature, the original JSON Spec Files are organized in a Tree Structure (as is all JSON, you may view these trees here: Browser API JSON and JavaScript API JSON

    Finally, and most importantly, at RunTime as Objects Instances, themselves, are created by the Parser; they are saved into the "Abstract Syntax Tree" (AST for short). These instances are placed into this AST, by saving them into ReadOnlyList's from the ReadOnly Collections Framework.

    Class Inheritance Tree:
    The diagram below shows the static class hierarchy: how the core JsonAST classes inherit from one another at the type level. 

    API
Domain

Entity
├─ TCE  (abstract)
│  ├─ TypeNode
│  ├─ CommandNode
│  └─ EventNode
└─ PPR



    Runtime Object Instance Tree:
    In contrast, this diagram shows the dynamic structure at runtime: how reified instances of those same classes are organized into an AST, with parent–child container relationships. 

    API
└─ Domain
   ├─ TypeNode
   │  └─ PPR       ➜ [P]roperties     ➜ Generate to Java Class Fields
   ├─ CommandNode
   │  ├─ PPR       ➜ [P]arameters     ➜ Generate to Java Method Parameters
   │  └─ PPR       ➜ [R]eturn-Values  ➜ Generate to Java Method Return Values
   └─ EventNode
      └─ PPR       ➜ [P]arameters     ➜ Generate to Java "Event Class" Fields



    The following six JsonObject properties are mapped to the following Entity subclasses:
    Json Object Type AST Node Java Conversion "Target"
    Type TypeNode Converted into Java Inner Classes / Nested Types of the Primary Domain Java-Classes
    Command CommandNode Converted into Java Methods within the Primary Domain Java-Classes
    Event EventNode Also Converted into Inner Classes / Nested Types of the Primary Domain Java-Classes
    Property PPR Converted into typical Java Fields within the Inner Types / Nested Classes.
    (See note †† below.)
    Parameter PPR For Commands, these are Converted by the Code Generator into Method Parameters. For Events, these are actually also just converted into Fields of the Nested Event Class too.
    (See note †† below.)
    Return Value PPR These are converted (for Commands), into Return-Values for the Methods. Using the "Multi-Return Tuples" RetN defined in the Java.Additional package, it is possible (and quite common, actually) to return multiple values from a single method invocation.
    (See note †† below.)

    †† Unlike TCE, Properties, Parameters, and Return-Values do not have their own dedicated AST nodes, because their content is always identical to that in base class PPR.
    See Also:
    Serialized Form


    • Field Summary

       
      Serializable ID
      Modifier and Type Field Description
      protected static long serialVersionUID
       
      Static Field: Internally Used String List. TypeNode Specific JsonObject Property-Names
      Modifier and Type Field Description
      protected static ReadOnlySet<String> TYPE_JSON_PROPERTIES_SET
      The list of additional JsonObject properties that the parser should expect when parsing TypeNode objects from the JSON CDP specification files.
       
      Instance Fields: List of PPR (Property) Instances which Will Generate into Class Fields
      Modifier and Type Field Description
      ReadOnlyList<PPR> properties
      Collection of PPR (Property) instances that will be materialized as Java class fields.
       
      Instance Fields: Fundamental Details about this TypeNode
      Modifier and Type Field Description
      byte CTAB
      CTAB: Computed Type as Byte: identical to CTAS; however the information is encoded as a 'byte' primitive as per the list of types exposed in class CDPTypes.
      String CTAS
      CTAS: Computed Type as String: is a field which summarizing this TypeNode’s resolved Java Type.
      boolean isReifiedInnerClass
      Flag indicating whether this TypeNode represents a reified inner class in the CDP model.

      • Fields inherited from class Torello.Browser.JsonAST.TCE

        which

    • Method Summary

       
      Methods: interface java.lang.Iterable
      Modifier and Type Method Description
      Iterator<PPR> iterator()
      Returns an Iterator that iterates the contents of the properties list.
       
      Methods: class java.lang.Object
      Modifier and Type Method Description
      String toString()
      Returns a String representation of 'this' instance.

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

    • Field Detail

      • serialVersionUID

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         protected static final long serialVersionUID = 1;

      • TYPE_JSON_PROPERTIES_SET

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected static final ReadOnlySet<java.lang.String> TYPE_JSON_PROPERTIES_SET
        The list of additional JsonObject properties that the parser should expect when parsing TypeNode objects from the JSON CDP specification files.
        Code:
        Exact Field Declaration Expression:
         protected static final ReadOnlySet<String> TYPE_JSON_PROPERTIES_SET =
         new ReadOnlyTreeSet<>(String::compareTo, "id", "properties");

      • properties

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<PPR> properties
        Collection of PPR (Property) instances that will be materialized as Java class fields.

        The CDP JSON Specification Files allocate a "properties" array for most JsonObject "type" elements in the specs. Each of the objects in the "properties" array are, themselves, constructed & instantiated into instances of class PPR.

        And each and every PPR will eventually be converted in a Java Field which is a member of the container "type" in which they were specified.
        Code:
        Exact Field Declaration Expression:
         public final ReadOnlyList<PPR> properties;

      • isReifiedInnerClass

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean isReifiedInnerClass
        Flag indicating whether this TypeNode represents a reified inner class in the CDP model.

        A "Reified Class" is an instance of a TypeNode for which the Code Generator shall emit a static Java nested type as a static member of the ownerDomain class. In short, if a TypeNode's 'isReifiedInnerClass' boolean has been assigned TRUE, then you should be able to count on finding a nested type in the Generated Java Class for the domain in which that TypeNode resides.

        As an example, in the BrowserAPI, the first domain which is listed is the Accessibility domain. Inside that domain, the first nested type / inner class listed is one named Accessibility.AXNode. The inner class AXNode is, indeed, a static nested inner class; and if you were to traverse or "search" the AST tree for the following nodes:

        BrowserAPI (API Node)    ➜    Accessibility (Domain)    ➜    AXNode (TypeNode)

        and check the value of its isReifiedInnerClass flag, you would see instantly that it had been assigned TRUE, precisely because the Code Generator intentionally generated that nested class to represent this particular TypeNode

        What is important to know is that within the CDP JSON Specifications, not all "types" have been declared or created equal. Any type which has at least one PPR property in its properties array will be reified into its own, dedicated, Java Nested Class.

        Any type which is just a basic renaming of a standard Java Primitive, or common Java Class such as java.lang.String will not have a Nested Class created for it. Instead such types are removed from the Java Class API, and the simple primitive or basic type is used in their place.
        Code:
        Exact Field Declaration Expression:
         public final boolean isReifiedInnerClass;

      • CTAS

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String CTAS
        CTAS: Computed Type as String: is a field which summarizing this TypeNode’s resolved Java Type.

        “CTAS” means “computed type-as-string.” it is the short, human-readable summary of this TypeNode's resolved shape after linking and normalization. it is used anywhere you want a quick glance string (summary tables, tooltips, headings), and it is stable across code-gen runs once the spec is unchanged.


        Calculating a CTAS:

        The generator derives CTAS from a small set of cases:

        Most Common Case - A Reified Object:

        The most likely scenario for a TypeNode is where its JSON definition contains a "type" property whose value is "object". Whenever the Json Property "type" : "object" is present, it is guaranteed (with the exception of two excepting cases) to have at least one PPR property in its properties list. This constitutes the majority of CDP specified 'types' (which are always specified in the relevant domain's "types" JSON array). Such TypeNode instance are always reified into actual domain-nested classes. Therefore their "Computed Type" is just:
        TypeNode.ownerDomain.name + "." + TypeNode.name


        Additional Cases:

        • case 2 — primitive: int, boolean.
          This is what it means for a type to be an Eliminated Type.

        • case 3 — number / string: optionality does not change the token; the CTAS is Number or String.
          This is another case in which the type is not reified into an actual class.

        • case 4 — arrays of primitives: always bracketed primitive, e.g., int[], boolean[] (optionality does not affect the array token).
          These types become "Eliminated Types".

        • case 5 — arrays of common java objects: String[] or Number[]. This is also what it means for a type to be an Eliminated Type.



        Four Special Cases:

        These two are actually rare, and ultimately happen only twice out of hundreds of defined Inner-Classes in the CDP specs. However, perhaps reading what is "uncommon" (below), will possibly contrast with the above explicit rules and ultimately provide some clarity about the above list. What follows is what (almost) never happens with a "Computed Type As String" (CTAS).

        "type": "array" Issue

        • ArrayOfStrings:

          in the DOMSnapshot domain, There is an 'Eliminated Type' called ArrayOfStrings whose "Computed Type", after resolution, ultimately yields:
          CTAS == "int[]".

          This type is eliminated because it is just an int[]-Array, without any actual fields. (Without Fields, this is just a renaming of the standard Java-Type int[]).

          In any case, there are quite a number of other types which are removed & eliminated by the Code Generator during generation. These types are left relegated with to a static final String contant in their owner domain's class. However, in this "Special Case" this TypeNode has been declared as an array of another type - which is impossible for TypeNode definitions.

          An array of references variant of TypeNode happens only twice within the CDP Json Specification Files, out of hundreds of such definitions.

        • TargetFilter:

          in the Target domain, (TargetFilter) has a JsonObject whose "type" property equals "array" and a second property, "items", that is itself a JsonObject. (Whenever the CDP JSON spec file uses an "items" property, it is guaranteed to be a JsonObject with exactly one property of its own)

          The array is declared as "items" : {"$ref": "FilterEntry"}, and it, therefore, yields a Computed-Type of:
          CTAS == "FilterEntry[]".

          In the CDP Specification Files, there are numerous "Array of Reference" Fields inside of TypeNode's, but what isn't common - and happens only once in 40K lines of JSON - is one Type being declared that is just an array of another Type in the specs.

          CDP defined type TargetFilter is actually not a "reified type", and is not converted by the Code Generator into an actual Nested Class of the Target Domain.



        "type": "object" Issue

        • Tracing.MemoryDumpConfig:

          in the Tracing domain, thre is another Eliminated Type called MemoryDumpConfig. In this type, even though the CDP specs declare it as an object, it does not actually have any declared fields in its properties list.
          This is an eliminated type, and has been assigned the following:
          CTAS = "JsonValue"

        • Network.Headers:

          in the Network domain, thre is another Eliminated Type called Headers. In this type, even though the CDP specs declare it as an object, it does not actually have any declared fields in its properties list.
          This is an eliminated type, and has been assigned the following:
          CTAS = "JsonValue"
        See Also:
        CTAB
        Code:
        Exact Field Declaration Expression:
         public final String CTAS;

    • Method Detail

      • toString

        🡅  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public java.lang.String toString()
        Returns a String representation of 'this' instance.
        Overrides:
        toString in class java.lang.Object
        Code:
        Exact Method Body:
         return StringTCE.get(this);