Package Torello.Browser.JsonAST

The contents of this package were largely written several years ago, when the Browser API was first developed. They remained in a Package-Private, "Public-API Invisible" state until August of 2025. Being part of a public facing API forces massive clean-ups, organization sweeps, renaming and code "anit-uglifying". Have you ever seen those Java-Script Generators called "uglify"? Horrible, if you ask me...

The primary impetus for putting this into the Public & Documented Part of the Java-HTML Library is just to continue to abide by the spirit of "Open Source" Code. Quite a bit of the Java-Doc Tool remains a Private-Internal Mystery, and this is largely due to the fact that the code is simply just not finished.

The Browser Chrome Dev-Tools Protocol Port to Java is coming to an end soon. Allowing Java-HTML users to see what it does seems important. The reality is that all this gigantic thing does is parse two '.json' Files which are regularly generated by Google Corporation (and unceremoniously dumped onto a public Git-Hub repository).

Once the Google-Generated Files 'browser_protocol.json' and 'js_protocol.json' have been parsed into an Abstract Syntax Tree (AST), that Syntax Tree is traveresed by another, internally maintained, Browser-Package to generate all of the '.java' Files which are provided in the packages Torello.Browser.BrowserAPI Torello.Browser.JavaScriptAPI

If you wish to "play around" and experiment with actual nodes of the classes in the JsonAST Package, then simply invoke this classes SERIALIZED_AST.deserializeFromJAR() method, and you will have a genuine AST with which you may experiment.

Object-Class Inheritance Tree:
This image portrays the Java Class Inheritance of these objects / classes.




Runtime Instance Container Tree:
This image portrays these objects / classes as containers that hold instances / references of each other.

Load Serialized AST from Disk
Java Entity	Description
SERIALIZED_AST	This class is the primary User-Interaction API class
Abstract Syntax Tree (AST) Nodes
Java Entity	Description
API	Contains a ReadOnlyList that has each domain defined in the API
Domain	Maintains all relevant data and references for a single CDP Domain; you may view the complete list of domains by reveiwing the top level classes in either the Torello.Browser.BrowserAPI and Torello.Browser.JavaScriptAPI packages
TypeNode	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
CommandNode	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
EventNode	An Java Object used within AST to symbolize or encapsulate the data present in any of the JsonObject's found within a Domain's "events" array
TCE	Class TCE serves as the common denominator for three inheriting, child classes: TypeNode, CommandNode & EventNode
PPR	Contains the data needed to represent a property, parameter or return value
Entity	Root ancestor for all CDP JSON entities parsed from the protocol specs (browser_protocol.json and js_protocol.json)
Enums
Java Entity	Description
PropName	Enumerates the JSON property names that may appear within their JSON protocol definitions
TypeProp	Enumerates the limited set of values that the Chrome DevTools Protocol may assign to the "type" property of its schema definitions
WhichEntity	This 'enum' is used to identify of which inheriting sub-class 'this' instance is
WhichPPR	Each insance of PPR that is created has an instance of this enum as a constant final field
WhichTCE	This 'enum' is used to identify of what kind of TCE instance 'this' is
Internal Use & Reference Only: Write Data Files to Disk
Java Entity	Description
AST_BUILD	AST Build Driver
InfoData
ExtraData	This is a "Cute Little Tree Walk" or "Tree Traversal" class that simply iterates every single node inside of an AST, and fills the InfoData with the relevant facts that are needed to buid an InfoData object
Internal Use & Reference Only: Constructor Helpers
Java Entity	Description
Helper$CheckKeys	There are two implementation methods of the "Check Keys" feature in this class
Helper$Enum	This checks for a Json Propety having the name "enum"
Helper$GetPPRLists	Invokes the PPR constructor on every instance of a JsonArray
Helper$GetTCELists	Extracts the complete list of TypeNode, CommandNode and EventNode from the JsonObject of a Domain definition
Helper$Misc	Contains three helper functions, which help construct the nodes of an AST Tree
Helper$Name	Extracts the Json Property "name" from the input JsonObject
Helper$TypeProps	Extracts the Json Property "type" from the JsonObject which defines an Entity instance, and converts that String into an instance of TypeProp
Internal Use & Reference Only: Linker
Java Entity	Description
Linker	After parsing both API Spec-Files, each and every Json Property namem "ref$" needs to have it's String converted into a genuine TCE instance; this process is called 'Linking' and it is identical to the linkng that the Java Compiler javac performs when converting variables & fields inside source files into class files
PPR_CTAS	This class generates the "Computed Type as String" for a PPR instance
Helper$FindDomain	This method is used to convert a CDP "domain" (which essentially the same as a Java "Package"), that is represented as a String, and convert it into a reference to one of the Domain object references
Helper$FindTypeNode	Converts a single type reference as a String into a genuine TypeNode instance
Internal Use & Reference Only: HTML Quick Summary
Java Entity	Description
WriteBothHTMLFiles	Iterates both trees - the "Browser Protocol" and the "Java Script Protocol"
HTML$API	Generates the top level HTML page for the "Browser" and the "Java Script" API's
HTML$Domain	Generates the HTML for the elements of the "domains" array
HTML$TypeNode	Generates the HTML for the elements of the "types" array, which is a sub-property of a "domain" object
HTML$CommandNode	Generates the HTML for the elements of the "commands" array, which is a sub-property of a "domain" object
HTML$EventNode	Generates the HTML for the elements of the "events" array, which is a sub-property of a "domain" object
HTML$TCE	Generates HTML that is consistent for all three inheriting sub-types: TypeNode, CommandNode & EventNode
HTML$PPR	Generates HTML for all Properties, Parameters and Return-Values, which are all stored in the AST as PPR nodes
Errors
Java Entity	Description
ASTError	General purpose exception, used in place of Java's Assert Statement
LinkingStateError	This error is used in place of the common 'UnreachableError'