Package Torello.Browser.JsonAST

Class Entity

java.lang.Object

Torello.Browser.JsonAST.Entity

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<Entity>

Direct Known Subclasses:

PPR, TCE

public abstract class Entity
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable<Entity>

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.

Root ancestor for all CDP JSON entities parsed from the protocol specs (browser_protocol.json and js_protocol.json).

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.

Class Responsibilities:
Chat-GPT is ever-infatuated with producing and generating lists of bullet points. After many conversations about class 'Entity', I asked it to come up with a "Top Comment" Java Doc HTML File for this class. It gave me one of its renowned bullet point lists, and I have tweaked them and beat them up into shape. You shall now read that list, below. (I sometimes just cannot think of what to say, but feel I ought to type at least a little blurb!)

• Normalize a raw JsonObject into strongly-typed, immutable, Java Class. It is important to note that immutable data is, by definition, Thread Safe Data. All fields in this class are declared final, and all collection types are Object Instances derived from the ReadOnly Java-HTML '.jar' library.
  
  
• Expose the JSON "type" property as an instance of the TypeProp enum. The constants of this enum have been produced to mirror the complete list of possible values allowed by CDP for the JsonObject "type" property.
  
  
• Publish the canonical property-name set as a ReadOnlyList of PropName constants. This list is derived from by invoking the method JsonObject.keySet(), and then mapping the String's returned to their corresponding PropName constants.
  
  This is acheived easily using the method PropName.valueOf. PropName is an exhaustive enumeration of all valid JsonObject Property Names that are consistent with, and may be used by the CDP specs.
  
  
• Carry other common metadata (domain, name, description, since, experimental, deprecated, etc.).
  
  
• Enforce invariants (like assert statements) during construction; the constructor takes steps to guarantee that the instances are validated. There are assertion throws which (hopefully) demonstrate what is expected of the properties that are read from the JsonObject
  
  
• Reference linking (e.g., $ref resolution and cross-domain/type references) happens in later linking phases; this class supplies the validated base state.

See Also:

TCE, PPR, PropName, TypeProp, Serialized Form

Hi-Lited Source-Code:

• View Here: Torello/Browser/JsonAST/Entity.java
• Open New Browser-Tab: Torello/Browser/JsonAST/Entity.java

File Size: 11,399 Bytes Line Count: 283 '\n' Characters Found

Field Summary

Serializable ID
Modifier and Type	Field	Description
protected static long	serialVersionUID
Core Identity: Fundamental Details of this Abstract Entity
Modifier and Type	Field	Description
String	description	Human-readable description of the CDP entity as specified in the protocol, by Google.
int	id	Monotonic ID for this CDP entity used by equals and hashCode.
String	name	Canonical CDP name for this entity.
Domain	ownerDomain	CDP domain that owns this entity (for example, 'Network' or 'DOM').
Type Data: Metadata for Sub-Class Instances Declared as Types
Modifier and Type	Field	Description
TypeProp	arrItemsTypeProp	Additional type, used when the typeProp equals TypeProp.ARRAY.
TypeProp	typeProp	The JsonObject "type" Property for this item as a strict enum.
Lifecycle Flags: Markers Assigned by the Google API Definition File
Modifier and Type	Field	Description
boolean	deprecated	True if this CDP item is marked deprecated.
boolean	experimental	True if this CDP item is marked experimental.
boolean	optional	True if this CDP item is optional.
Enumerated Types: Metadata for Sub-Class Instances Declared, Specifically, as String 'enums'
Modifier and Type	Field	Description
ReadOnlyList<String>	enumVals	Allowed enumeration String values for this CDP item.
String	enumValsStr	Comma-separated rendering of enumVals, used to facilitate printing summaries.
Json Parse Info: All Concrete Subclasses of 'Entity' are Parsed JsonObjects from a JsonArray
Modifier and Type	Field	Description
int	index	Every Entity instance is parsed from a JsonArray; this is the array index.
ReadOnlyList<PropName>	propNames	List of all JsonObject property keys for this CDP item, as parsed from the JsonObjet from which this Entity instance was extracted.
WhichEntity	whichEntity	There are only two concrete subclasses of Entity: PPR and .

Method Summary

Methods: interface java.lang.Comparable
Modifier and Type	Method	Description
int	compareTo(Entity other)	Uses several pieces of information for generating a comparison value.
Methods: class java.lang.Object
Modifier and Type	Method	Description
boolean	equals(Object other)	Checks that this id is equal to other.id.
int	hashCode()	Returns the id as a hash value.
Error Printing Information Method
Modifier and Type	Method	Description
String	exceptionLocationSummary()	Helper method, used to print this node's vital information.

Methods inherited from class java.lang.Object

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

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;

id

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final int id

Monotonic ID for this CDP entity used by equals and hashCode. Each entity instance is assigned a unique, monotonically increasing identifier at construction time.

This provides a stable reference point for identity‑based comparisons, hashing, and debugging output.

It is not derived from the CDP specification but is introduced by the JsonAST layer for internal consistency.

Code:

Exact Field Declaration Expression:

 public final int id = IDManager.nextID();

ownerDomain

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final Domain ownerDomain

CDP domain that owns this entity (for example, 'Network' or 'DOM'). The Chrome DevTools Protocol groups commands, types, and events into named domains such as DOM, Network, or Runtime.

This field records the owning domain of the entity, enabling domain‑level lookups and proper organization during code generation.

It is assigned during the linking phase of parsing.

Code:

Exact Field Declaration Expression:

 public final Domain ownerDomain;

name

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final java.lang.String name

Canonical CDP name for this entity. The name is taken directly from the protocol specification and uniquely identifies the entity within its domain.

Names are stable across Chromium releases and serve as the key for mapping JSON protocol definitions to generated Java classes.

The 'name' Field is extracted from the CDP specs by extracting the JSON 'name' Property from the JsonObject. However, there is an exception in that, for TypeNode instannces, this field (field 'name') is extracted from the JsonObject Property named 'id'

Code:

Exact Field Declaration Expression:

 public final String name;

description

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final java.lang.String description

Human-readable description of the CDP entity as specified in the protocol, by Google. Protocol authors often include a short prose description of a command, type, or event.

This text is stored here, verbatim, from the specification. This is an "English-Text" blurb,

While not always exhaustive, it helps end users and tools alike in understanding the intent and role of the concrete sub-class instance. The CDP protocol definition files do not always include a 'description' JsonObject property.

Code:

Exact Field Declaration Expression:

 public final String description;

whichEntity

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final WhichEntity whichEntity

There are only two concrete subclasses of Entity: PPR and . Entities in the protocol fall into two categories:

• Types, Commands and Events, all three of which inherit base class TCE
• Properties, Parameters and Return Values all three of which have data that is contained by the class PPR, and therefore do not need their own inheriting subclass.

This enum distinguishes between these two Concrete Subclass Types, and saves that difference is field 'which'. This allows the downstream Code Generator to more easily differentiate between subclasses without using 'instanceof'

Code:

Exact Field Declaration Expression:

 public final WhichEntity whichEntity;

propNames

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final ReadOnlyList<PropName> propNames

List of all JsonObject property keys for this CDP item, as parsed from the JsonObjet from which this Entity instance was extracted. Holds the canonical list of JSON property identifiers for this entity.

This field is a ReadOnlyList<PropName> of enum constants. Each constant comes from the exhaustive enum PropName, which enumerates all possible JsonObject property names for any concrete Entity subclass.

The list is generated by taking the keys of the underlying JsonObject (via the java.util.Map.keySet() method) and mapping each String-Key to its matching PropName using the enumss static lookup method.

Code:

Exact Field Declaration Expression:

 public final ReadOnlyList<PropName> propNames;

typeProp

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final TypeProp typeProp

The JsonObject "type" Property for this item as a strict enum.

The JsonObject which defines this Entity will often have a "type"-Property defined. There is a very limited number of values which may be assigned to this property, and all possibilities for this property have been assigned constant value-names with the enum TypeProp.

This property resolves this into a normalized TypeProp enum in order to ensure consistent handling of type semantics during code generation.

Code:

Exact Field Declaration Expression:

 public final TypeProp typeProp;

arrItemsTypeProp

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final TypeProp arrItemsTypeProp

Additional type, used when the typeProp equals TypeProp.ARRAY. When the entity is declared as an array type, this field captures the type of its items.

It is null for non‑array types.

Separating this detail simplifies later code generation and makes array semantics explicit in the AST.

Code:

Exact Field Declaration Expression:

 public final TypeProp arrItemsTypeProp;

optional

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final boolean optional

True if this CDP item is optional. Protocol entities may be marked as optional, meaning they may be omitted from payloads.

This flag records that designation so that generated Java code can apply appropriate nullability or default‑handling strategies at runtime.

Code:

Exact Field Declaration Expression:

 public final boolean optional;

experimental

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final boolean experimental

True if this CDP item is marked experimental. Some parts of the CDP are designated as experimental, signaling potential changes or instability across Chromium versions.

This flag allows tooling to mark such features and optionally warn users when generating bindings or documentation when intending to use these features.

Code:

Exact Field Declaration Expression:

 public final boolean experimental;

deprecated

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final boolean deprecated

True if this CDP item is marked deprecated. Deprecated entities are retained in the specification for backward compatibility but are discouraged for new use.

This flag allows tooling and documentation to highlight deprecated items clearly while still supporting legacy references.

Code:

Exact Field Declaration Expression:

 public final boolean deprecated;

enumVals

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final ReadOnlyList<java.lang.String> enumVals

Allowed enumeration String values for this CDP item. If the protocol restricts a property or type to one of several string constants, those literal values are collected here.

This enables generated code to represent enums safely and allows validation of incoming protocol messages.

Code:

Exact Field Declaration Expression:

 public final ReadOnlyList<String> enumVals;

enumValsStr

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final java.lang.String enumValsStr

Comma-separated rendering of enumVals, used to facilitate printing summaries. For display, logging, and error messages, the list of allowed enum values is also rendered as a single, comma‑separated String.

This avoids repeated conversions and improves readability in diagnostic output.

Code:

Exact Field Declaration Expression:

 public final String enumValsStr;

index

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final int index

Every Entity instance is parsed from a JsonArray; this is the array index. During parsing, entities are read into ordered lists per domain.

This index records the entity’s original position in its JSON array, preserving stable ordering for error reporting, serialization, and regeneration of protocol structures.

Code:

Exact Field Declaration Expression:

 public final int index;

Method Detail

exceptionLocationSummary

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final java.lang.String exceptionLocationSummary()

Helper method, used to print this node's vital information.

Code:

Exact Method Body:

 return
     "Node-Name:       [" + this.name + "]\n" +
     "Owner-Domain:    [" + this.ownerDomain.name + "]\n" +
     "WhichEntity:     [" + this.whichEntity + "]\n" +
     "Class-Name:      [" + this.getClass().getSimpleName() + "]\n" +
     "JsonArray Index: [" + this.index + "]\n";

compareTo

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final int compareTo(Entity other)

Uses several pieces of information for generating a comparison value.

Specified by:

compareTo in interface java.lang.Comparable<Entity>

Code:

Exact Method Body:

 if (this == other) return 0;
 if (other == null) return 1;

 if (this.ownerDomain.ownerAPI != other.ownerDomain.ownerAPI)
     return this.ownerDomain.ownerAPI.name.compareTo
         (other.ownerDomain.ownerAPI.name);

 if (this.ownerDomain != other.ownerDomain)
     return this.ownerDomain.name.compareTo(other.ownerDomain.name);

 if (this.whichEntity != other.whichEntity)
     return this.whichEntity.compareTo(other.whichEntity);

 int c = this.name.compareTo(other.name);

 return (c != 0)
     ? c
     : Integer.compare(this.hashCode(), other.hashCode());

hashCode

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final int hashCode()

Returns the id as a hash value.

Overrides:

hashCode in class java.lang.Object

Code:

Exact Method Body:

 return id;

equals

🡅 ⇈ ⮫ 🗕 🗗 🗖

public final boolean equals(java.lang.Object other)

Checks that this id is equal to other.id.

Overrides:

equals in class java.lang.Object

Code:

Exact Method Body:

 if (other == null)              return false;
 if (!(other instanceof Entity)) return false;
 return this.id == ((Entity) other).id;