Class CommandNode

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<Entity>
    public class CommandNode
extends TCE
implements java.io.Serializable
    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 "commands" 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. CommandNode Specific JsonObject Property-Names
      Modifier and Type Field Description
      protected static ReadOnlySet<String> COMMAND_JSON_PROPERTIES_SET
      The list of additional JsonObject properties that the parser should expect when parsing CommandNode objects from the JSON CDP specification files.
       
      Instance Fields: List of PPR (Parameter) instances which Will Generate into Method-Parameters & Return-Values
      Modifier and Type Field Description
      ReadOnlyList<PPR> parameters
      A 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.
      ReadOnlyList<PPR> returns
      A 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.
       
      Instance Fields: Fundamental Details about this TypeNode
      Modifier and Type Field Description
      boolean hasReifiedRetInnerClass
      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.
      String redirect
      This field contains the raw String value of the "redirect" Json Property.

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

        which

    • Method Summary

       
      Getters: Returns the Value of a Private, non-Final, Field
      Modifier and Type Method Description
      Domain redirectDomain()
      This method retrieves the value of a private field which isn't assigned inside of the constructor, but rather during the Linking Phase, and is therefore not declared final.
       
      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

    • Field Detail

      • COMMAND_JSON_PROPERTIES_SET

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

      • redirect

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String redirect
        This field contains the raw String value of the "redirect" Json Property. This String will be linked during the Linking Phase of a Build, into an instance of Domain The domain to which this refence points, merely identifies a CDP domain (which is similar to a Java Package) in in which this Command (like a Java Method) is actually deferred. "Redirect Domains" are just ways for the CDP Spec to place commands (methods) that are identical into multiple domains (again, CDP Domains are highly similar to Java Packages - they group features and functionality in one location and give it a name).

        The Java-HTML CDP Implementation (the 'Browser' package and its two sub-packages), do not actually make any use of "Redirect Domains." Any redirection that occurs is actually handled on the other side of the Web-Sockets Wall, and takes place inside the browsers code, not the Java Implementation with which the browser is communicating.

        Instead, this Json Property is merely extracted and placed into this field for reference purposes only. It is not actually used (nor is its "linked version", namely the output of method redirectDomain()) used either!
        Code:
        Exact Field Declaration Expression:
         public final String redirect;

      • hasReifiedRetInnerClass

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean hasReifiedRetInnerClass
        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.

        A "Reified Return Class" is an instance of a CommandNode for which the Code Generator shall emit a static Java nested type as a static member of the ownerDomain class to represent the method's return values. In short, if a CommandNode's 'hasReifiedReturnClass' boolean has been assigned TRUE, then you should be able to count on finding a nested type whose name ends with $$RET. This class will be found in the Generated Java Class for the exact domain in which the original CommandNode resides.

        As an example, in the BrowserAPI, there is domain called CSS. The class for that domain, has a nested type / inner class named ​ CSS.getAnimatedStylesForNode$$RET. The inner class getAnimatedStylesForNode$$RET 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)    ➜    CSS (Domain)    ➜    getAnimatedStylesForNode (CommandNode)

        and check the value of its hasReifiedRetInnerClass flag, you would see instantly that it had been assigned TRUE. This flag relays to the Code Generator that it must generate a nested type in order to properly represent the return values of this particular command.

        What is important to know is that Java does not provide an easy way to return multiple values from a method invocation. Thusly, whenever a command which has multiple return- PPR's in its returns array the Code Generator will emit a dedicated Java Nested Class to represent & encapsulate those return values.
        Code:
        Exact Field Declaration Expression:
         public final boolean hasReifiedRetInnerClass;

      • parameters

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<PPR> parameters
        A 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.
        Code:
        Exact Field Declaration Expression:
         public final ReadOnlyList<PPR> parameters;

      • returns

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<PPR> returns
        A 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.
        Code:
        Exact Field Declaration Expression:
         public final ReadOnlyList<PPR> returns;

    • Method Detail

      • redirectDomain

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Domain redirectDomain()
        This method retrieves the value of a private field which isn't assigned inside of the constructor, but rather during the Linking Phase, and is therefore not declared final.

        Represents the resolved target of a browser-internal 'redirect'. In the CDP JSON specifications, some commands or types define a 'redirect' property, whose value is just the name of another domain. This indicates that the actual definition (implementation) has been moved or "aliased" from another domain. Programmers / Users of any Command which has a non-null "redirectDomain" value assigned should just be aware that the browser will be evaluating your instructions by a different Web Browser Domain.

        This is all handled internally by the Web-Browser, and there aren't any intermediate actions that a programmer needs to take based on a CDP Command which has a non-null Redirect Domain value assigned. This has just been placed here for reference and understanding purposes only1

        Example: a command may be listed in one domain with JSON Property:

        Java Script Object Notation (JSON):
        "redirect": "Target"


        This means that this CommandNode instance will be translated into a Java Method (by the Code Generator, during the Code Generation Phase) which is actually just a forwarder to the Target domain.

        Since a redirect target cannot be resolved at object construction time, this field is initialized to null and later linked to the appropriate Domain object instance during the "Linking Phase". This redirectDomain() method provides access to the private field once linking is complete.
        Code:
        Exact Method Body:
         return redirectDomain;

      • 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);