Class PPR

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<Entity>
    public class PPR
extends Entity
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.
    Contains the data needed to represent a property, parameter or return value.

    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. PPR Node-Specific JsonObject Property-Names
      Modifier and Type Field Description
      protected static ReadOnlySet<String> PPR_JSON_PROPERTIES
      The list of additional JsonObject properties that the parser should expect when parsing PPR objects from the JSON CDP specification files.
       
      Instance Fields: Fundamental Details about this PPR
      Modifier and Type Field Description
      TCE ownerTCE
      This is a "Back Pointer" to the TCE (either a TypeNode, CommandNode or EventNode) that is the parent or owner of 'this' PPR instance.
      WhichPPR which
      Expresses, explicitly, (without requiring an 'instanceof' operator), whether or not 'this' instance repesents a property, a parameter or a return-value.
       
      Instance Fields: Unlinked, Still-In-String-Format, Raw References.
      Modifier and Type Field Description
      String ref
      This field is declared final, and contains the raw-String value which is retrieved (during JSON parsing) from the "$ref" JsonObject property which defines 'this' PPR instance
      String refArray
      This String is declared final, and contains the raw-String value which is retrieved during the parsing of an 'items' JsonObject within this PPR definition.

    • Method Summary

       
      Getters: Return Linked References. These Methods Return the Values of non-Final Fields
      Modifier and Type Method Description
      byte CTAB()
      Returns the value of the private field 'ctab'; a field that represents the "Computed Type as Byte".
      String CTAS()
      Returns the value of the private field 'ctas'; a field that represents the "Computed Type as String" - the Java Type of this PPR, as a String).
      TypeNode reference()
      Returns the value of the private field 'reference'; a field that represents the resolved target of a '$ref' property.
      TypeNode referenceArray()
      Returns the value of the private field 'referenceArray'; a field that represents the resolved target of a '$ref' property which was extracted from an 'items' object.
       
      Methods: class java.lang.Object
      Modifier and Type Method Description
      String toString()
      Returns a String representation of 'this' instance.
      String toStringShort()
      Returns a brief (shorter than the toString()a output)) String summary of 'this' instance.

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, 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;

      • PPR_JSON_PROPERTIES

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

      • which

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final WhichPPR which
        Expresses, explicitly, (without requiring an 'instanceof' operator), whether or not 'this' instance repesents a property, a parameter or a return-value. The JsonAST package has a particular class (this one, 'PPR') that it uses to represent three different kinds of Json elements from the Json API Definition / grammar. Class 'PPR' is used to represent all three kinds of JsonObjects: PROPERTIES, PROPERTIES and RETURNS.

        This field is declared both public and final, and identifies which of the three possibilities 'this' instance was derived ('P', 'P' or 'R' 😃).
        Code:
        Exact Field Declaration Expression:
         public final WhichPPR which;

      • ref

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String ref
        This field is declared final, and contains the raw-String value which is retrieved (during JSON parsing) from the "$ref" JsonObject property which defines 'this' PPR instance

        This field is declared both public and final, and is treated like an instance-specific / object-specific (READ: it is not declared static) constant. The value assigned to this field by the constructor is the raw String contents of the JSON Object Property named '$ref'.

        Every instance of PPR must contain exactly one definition for either the primitive Field, or for this '$ref' Field. Precisely one of these two fields (in this class) must be non-null, while the other field must be assigned null.

        While the complete list of available options that Google might assign to the 'primitive' Json-Property are listed as constants in the Java enum named TypeProp (STRING, INTEGER or BOOLEAN, etc...) the allowed String-Values which may be assigned to this field are, essentially, the list of declared types (all of the 'Nested Data Classes' amongst all of CDP's domains) that are defined by CDP.

        A non-null value in this '$ref' Field indicates that the definition should be understood in terms of an existing named type declared elsewhere in the protocol (for example, TargetInfo in the Target domain).

        During the Linking Phase of AST-Building, a non-null $ref Field will be converted into a non-null (and private) 'reference' field which actually points to the actual TCE-Instance for the Java nested class defined for the type named by the String-Value of this field.

        Remember, the more you look right at "reflection" in any programming language, the more complicated it is to say, mention or document anything about the Source-Code which is operating on the reflective variables. Programmers take words like 'String' and 'reference' for granted - until the day that the variables and values that they are using have names or values (or both names and values) like 'STRING' and 'REFERENCE'
        Code:
        Exact Field Declaration Expression:
         public final String ref;

      • refArray

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String refArray
        This String is declared final, and contains the raw-String value which is retrieved during the parsing of an 'items' JsonObject within this PPR definition.

        It is assigned a non-null value when the JsonObject contans the following *TWO* Object-Properties:

        • "type" : "array"
        • "items" : { "ref$" : "SomeCDPDefinedType" }


        There are on the order of (my Diagnostic-Tool counted 354, to be exact) PPR's that have a value assigned to 'Entity.refArray' inside the Browser-API. There are exactly *TWO* Type-TCE's that have a value assigned to 'Entity.refArray'... Those 2 TCE's were: Target.TargetFilter & DOMSnapshot.ArrayOfStrings

        This field will eventually have to be linked / 'cross-referenced' into an actual object instance of class TCE (from a java.lang.String, which is the format in which it is stored here). Since the linking cannot be done until after the parsing is finished, the Version of field referenceArray is saved here.

        This field is non-null if and only if this 'PPR' instance represents an array; but moreover an array of an actual and reified CDP Class / Type.
        Code:
        Exact Field Declaration Expression:
         public final String refArray;

    • Method Detail

      • reference

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final TypeNode reference()
        Returns the value of the private field 'reference'; a field that represents the resolved target of a '$ref' property. This is a public facing getter for a non-final (and, ergo, private) field. The value assigned to this field cannot be calculated or computed during this object's construction. It is computed after the entire API's AST has been built, and is evaluated during the "Linking Phase" of AST-Building.

        In the CDP protocol JSON specification files, there are numerous Properties, Parameters, and Return-Value definitions that do not declare themselves as simple raw types (such as string, boolean & number etc..), but instead reference another type by name (as a JsonString) using a '$ref' property. This is actually a somewhat common trick among programmers who do use JSON as a means of expessing API Definitions. These '$ref' properties function very similarly to reference variables inside of standard Java Programs. These references are used, simply, to point to other classes, elsewhere in the package tree or project tree.

        Linking Note:
        At object construction time, this cannot yet be resolved, since the target type may be defined later in the same domain or even in another domain. Specifically, if 'this' instance' constructor is invoked before the class constructor named by '$ref', then it is patently impossible to save a reference to that which '$ref' is specifying until after all of the other classes & types have been constructed by the parser.

        During the linking phase, the '$ref' object property is matched to its corresponding TCE ( Type, Command or Event), and this `reference` field is updated to point directly to it.

        Because this happens after construction, the internal field named reference also cannot be declared public either. (Again reference cannot be declard final because it cannot be initialized in the constructor, as per explained above)

        As a result there is also a method named reference() (this method) which functions as a 'getter', thereby providing read-only access to this resolved TCE.
        Code:
        Exact Method Body:
         return reference;

      • referenceArray

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final TypeNode referenceArray()
        Returns the value of the private field 'referenceArray'; a field that represents the resolved target of a '$ref' property which was extracted from an 'items' object.

        This field will contain a non-null String-reference if and only if this JSON for this PPR definition contains:

        • a "type" : "array" property

        • an "items" JsonObject property.

        • That internal "items" object, itself, has a "$ref" : "SomeCDPDefinedType" property which names & specifies a class or type that is defined elsewhere in the CDP specification files.


        This method provides read only access to a private and internal field of the exact same name. The private & internal field named referenceArray is declared private precisely because it cannot be delcared final. It is not declared final (unlike everything else in the AST Node classes) beause it cannot be set by the constructor at object construction time.

        Fields which are to be assigned to some other object reference that may not have yet been instantiated yet have to assigned during the "Linking Phase" instead. The need for a Linking Phase is precisely because the PPR's and TCE's that are parsed during the early / beginning part of the parsing process (at the beginning or top of the CDP JSON spec-files) often name PPR's and TCE's that are defined at the end of that file.

        To combat this "Catch 22", there is a Linking Phase that occurs after the constructor phase, and fields which have to be linked are kept private, rather than public.
        Code:
        Exact Method Body:
         return referenceArray;

      • CTAS

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String CTAS()
        Returns the value of the private field 'ctas'; a field that represents the "Computed Type as String" - the Java Type of this PPR, as a java.lang.String).

        The value assigned to this String is the one that is ultiately used by the Browser-CDP Code Generator, during the Code-Generation Phase. The value assigned to this String could either be a simple / standard Java-Type such as String, int or boolean, but it could also be one of the types which are defined in Google CDP - such as Target.TargetInfo or Network.Cookie
        See Also:
        CTAB()
        Code:
        Exact Method Body:
         return ctas;

      • CTAB

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final byte CTAB()
        Returns the value of the private field 'ctab'; a field that represents the "Computed Type as Byte".

        This is an identical piece of informatio as the value returned by CTAS(). This method merely returns an encoded version of a private & internal 'ctab' field. 'ctab', rather than storing this PPR's type information as a String-literal, it saves it as a simple Java byte-primitive.

        The value stored here is consistent with the numbered list of types available in class CDPTypes.
        See Also:
        CTAS(), CDPTypes
        Code:
        Exact Method Body:
         return ctab;

      • 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 StringPPR.get(this);

      • toStringShort

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String toStringShort()
        Returns a brief (shorter than the toString()a output)) String summary of 'this' instance.
        Code:
        Exact Method Body:
         return
     this.ownerDomain.ownerAPI.name + '.' +  // API-Name
     this.ownerDomain.name + '.' +           // Domain-Name
     this.ownerTCE.name + '.' +              // TCE-Name
     this.name + ' ' +                       // PPR-Name
     "[WhichTCE." + this.ownerTCE.which + ", WhichPPR." + this.which + ']';