Interface NestedHelper<DOMAIN_NESTED extends BaseType<DOMAIN_NESTED>>

  • public interface NestedHelper<DOMAIN_NESTED extends BaseType<DOMAIN_NESTED>>
    ⚠️ This class is designated as an "internal use only class." While there is nothing detrimental about using this class, it is actually only declared 'public' because it's methods & fields are indeed needed in packages outside of Torello.Browser. Classes which are declared 'public' are automatically documented by 'javadoc'. Therefore this page is included for viewing, even though Java-HTML Library users probably don't actually need to know about it!

    💡 Feel free to review it's contents. Perhaps there are explanations which might be of interest.
    Defines the singleton helper contract that supplies metadata, validation, and JSON conversion logic for a nested CDP type, event, or command-return class. The NestedHelper interface defines the implementation contract for the singleton helper classes that support every nested CDP type, event, and command-return-type in the Torello Browser APIs.

    The central design decision in this library is that a CDP "domain" is represented by one large top-level Java class, and that all of the domain's types, events, and command-return-types live as nested classes inside that one container. This keeps the Java source shaped like the protocol: the browser is the real implementation, and the Java code is mostly a carefully organized layer for naming things, binding JSON to Java, and binding Java back to JSON. That design makes the domain class itself grow quite large, so the supporting logic was pushed out into helper classes instead of cluttering every nested data class with repetitive infrastructure.

    A class implementing NestedHelper therefore plays a role similar to an old-style "Impl" class. It is not the public face of the API, and it is not normally the class the end user constructs or calls directly. Instead, it contains the repeated mechanics that every nested CDP class needs:

    • field metadata
    • construction-time presence bookkeeping
    • equality and hashing rules
    • JSON serialization
    • JSON parsing
    • enumerated-string validation

    Each helper is implemented as a singleton instance. The concrete nested class keeps a reference to that singleton and passes it into the BaseType constructor. From then on, the public methods on BaseType delegate to the helper. This is why the end user sees clean, small nested classes, while the repetitive plumbing lives elsewhere.

    The helper pattern here is not trying to create "business logic." Quite the opposite: it is a way to isolate repetitive infrastructure in a codebase whose real job is moving data between Java objects and browser JSON messages.


    • Method Summary

       
      Web-Sockets Transportation: Serialize & De-serialize to & from the browser, with JSON
      Modifier and Type Method Description
      DOMAIN_NESTED fromJSON​(JsonObject jo)
      Parses a JsonObject and creates the corresponding concrete type, event, or command-return instance.
      void toJSON​(DOMAIN_NESTED THIS, String name, JsonGenerator jGen)
      Writes a concrete nested instance into the supplied JSON generator, optionally as a named property of a larger JSON object.
       
      CDP-Types which have String Fields whose Values are Restricted to an Enumerated String Set
      Modifier and Type Method Description
      ReadOnlyMap<String,
           ​ReadOnlyList<String>>      		 allEnumStrROLs()
      Retrieves a ReadOnlyMap mapping field names to a ReadOnlyList of valid String values for each field in the map.
      IntStream enumStrValidate​(DOMAIN_NESTED THIS)
      Returns the indices of any string fields whose values do not match their allowed enumerated constants.
       
      More Implementation / Helpers
      Modifier and Type Method Description
      NestedDescriptor<DOMAIN_NESTED> descriptor()
      Returns the descriptor singleton that describes the field layout and CDP metadata of the nested class.
      ReadOnlyList<Boolean> generateIsPresentList​(DOMAIN_NESTED THIS)
      Builds the read-only isPresent list for a concrete instance by recording which fields are currently considered present.
       
      Methods: class java.lang.Object
      Modifier and Type Method Description
      boolean equals​(DOMAIN_NESTED THIS, Object other)
      A method that must be implemented by a singleton helper which performs the commonly seen, standard Java 'equals' method.
      int hashCode​(DOMAIN_NESTED THIS)
      A method that must be implemented by a singleton helper which performs the commonly seen, standard Java 'hashCode' method.

    • Method Detail

      • descriptor

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        NestedDescriptor<DOMAIN_NESTED> descriptor()
        Returns the descriptor singleton that describes the field layout and CDP metadata of the nested class. Returns the metadata object that describes the concrete nested class' fields, types, optionality flags, and experimental flags.

        A NestedDescriptor is lightweight reflection data prepared specifically for a CDP nested class. Rather than repeatedly using general-purpose Java reflection at runtime, the helper publishes a single descriptor instance containing parallel, read-only lists of:

        • field names
        • CDPTypes 'byte' type codes.
        • boolean 'optional' flags
        • boolean 'experimental' flags
        • a pointer back to the concrete Java class

        This metadata is useful because the Torello CDP library package is not actually doing any heavy in-process computation at all. It is not a 'Web Browser' in any way whatsoever. Actually, its main work-load is describing protocol structures faithfully, and converting them to and from JSON. The descriptor gives the library a compact and uniform description of a nested class without bloating the class definition itself. The descriptor is built once in a static-initializer and then returned from the singleton whenever needed.

        Moving this material into a helper keeps the visible nested class short and readable. The nested class can focus on its fields, while the helper quietly owns the repeated metadata arrays and the implementation details that go with them. That division is especially valuable in a domain class that may contain a very large number of nested types and events.

        The descriptor should be read as "protocol-shape metadata" rather than as an attempt to replace Java's reflection APIs. It is a purpose-built description of the CDP object layout.

      • generateIsPresentList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        ReadOnlyList<java.lang.Boolean> generateIsPresentList​(DOMAIN_NESTED THIS)
        Builds the read-only isPresent list for a concrete instance by recording which fields are currently considered present. Builds the instance's isPresent list, which records which protocol fields are being treated as present for that specific object.

        The highest-level point about generateIsPresentList() is that it exists primarily for objects constructed directly by user code, not for objects reconstructed from JSON returned by the browser.

        When a CDP type, event, or command-return-type is instantiated by the Web-Sockets Transport Layer from a browser-supplied JsonObject, the correct value for the constructor parameter isPresent is determined directly from the JSON itself. In that case, the transport layer builds the list using the presence of JSON property names: 

        new ReadOnlyArrayList<Boolean>(
    jo.containsKey("fieldName1"),
    jo.containsKey("fieldName2"),
    ...
    jo.containsKey("fieldNameN")
);


        This is the most accurate way to determine field presence, because it preserves the difference between a property that was omitted entirely and a property that was present in the JSON payload. That distinction is, in fact, the main reason the isPresent field exists at all.

        By contrast, when a CDP type, event, or command-return-type is instantiated directly by the user through a public constructor, it is often reasonable, and usually best practice, to pass null for the isPresent parameter and allow the constructor to invoke generateIsPresentList() automatically. This method therefore acts as a constructor-time fallback for user-created objects when no explicit presence list has been supplied.

        The purpose of the isPresent list is to distinguish between a field that is absent from the protocol message and a field that is merely assigned a Java value such as null. Although JSON null and Java null may appear similar, they are not treated as identical by this CDP implementation. JSON and Java live in different universes here, and the wrapper must preserve that difference whenever browser JSON is being parsed.

        This method is not a general-purpose utility, and it is not intended to be called repeatedly during the life of an object. It exists solely to assist the concrete nested class during construction. Each nested type, event, or command-return-type constructor already accepts an isPresent parameter. The helper method generateIsPresentList() is used only when that constructor parameter has been passed as null.

        Because of that design, this method should only be invoked by the actual nested class' constructor, and under normal use it should only be invoked once for any given object instance. After the constructor assigns the object's fields, the helper inspects those fields and builds the read-only presence list that will be stored by the new instance.

        When generateIsPresentList() is invoked, it makes its decision using a very simple rule: it asks whether each field currently contains a reference or is null. The result for index i in the generated list is determined entirely by the field assigned to that same positional index in the concrete nested class. Thus, the field order in the owner class matters: the first declared field corresponds to presence index 0, the second to index 1, and so on.

        A field whose value is null is considered not present, and therefore isPresent.get(i) will be false. Conversely, a field that contains a non-null reference is considered present, and the corresponding list entry will be true.

        This rule is correct in virtually all situations. The only exception is when the user explicitly intends to send a JSON null value to the browser. In that case, a field may be null while still being considered present. Because generateIsPresentList() equates null with "not present," it cannot be used for this scenario. Any user wishing to transmit JSON null must provide an explicit isPresent list to the constructor.

        The behavior of this method is also tightly coupled to the library's type-mapping design decisions. Fields that are non-optional and map naturally to Java primitives, such as int or boolean, are always considered present, because primitives cannot be null. Optional fields, or fields where nullability must be preserved, are represented using reference types. In practice, this leads to conventions such as:

        • Non-optional integer ➜ int
        • Optional integer ➜ java.lang.Integer
        • String (optional or not) ➜ java.lang.String
        • Number ➜ java.lang.Number

        Because of this mapping, the default presence calculation behaves as follows:

        1. Primitive field ➜ always present
        2. Reference field ➜ present if and only if non-null

        This default behavior is sufficient for essentially all real-world usage. It is extremely unlikely that a user will need to explicitly send JSON null values through the CDP interface, and therefore relying on generateIsPresentList() is acceptable in the overwhelming majority of cases.

        There is one final edge case related to protocol conformance. If the browser were to omit a field that is defined as mandatory in the CDP specification, and that field has been mapped to a Java primitive type, then a true "not present" state cannot be represented directly. In this situation, the Web-Sockets Transport Layer substitutes sentinel values rather than throwing an exception:

        • Missing integer ➜ Integer.MIN_VALUE
        • Missing boolean ➜ false


        This behavior reflects the broader design goal of the wrapper: to report as faithfully as possible what the browser actually sent, while avoiding runtime failures merely because the browser behaved unexpectedly. The browser and its compatible implementations are enormous systems, and this wrapper does not attempt to guarantee their correctness. Instead, it attempts to preserve and expose their output in a form the user may inspect and interpret.

        In short, generateIsPresentList() is a one-time constructor helper for user-created objects, whereas browser-created objects should receive their isPresent list directly from JSON property presence using jo.containsKey(...).

      • equals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        boolean equals​(DOMAIN_NESTED THIS,
               java.lang.Object other)
        A method that must be implemented by a singleton helper which performs the commonly seen, standard Java 'equals' method.

      • toJSON

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        void toJSON​(DOMAIN_NESTED THIS,
            java.lang.String name,
            JsonGenerator jGen)
        Writes a concrete nested instance into the supplied JSON generator, optionally as a named property of a larger JSON object. Serializes the concrete nested object into JSON using the supplied JsonGenerator.

        This method writes the JSON representation of the concrete type, event, or command-return object. It accepts the object being serialized, an optional property name, and the active JsonGenerator that should receive the JSON output. If a non-null name is provided, the object is written as a named property inside some enclosing JSON object; if the name is null, the object is written as an unnamed top-level JSON object.

        The reason this method accepts a generator and returns void is architectural. These CDP types are often nested inside one another. A larger object may need to serialize one of its fields by asking that field to contribute JSON directly into the same open generator. If this method instead returned a standalone JSON string, composing larger JSON structures out of smaller ones would become awkward and error-prone. The current signature lets parent and child objects participate in one continuous JSON write operation.

        This design also matches how the rest of the library works. Sometimes the end user may call toJSON directly. More often, however, JSON generation happens as part of request marshalling in the WebSocket layer, or while another concrete CDP object is serializing one of its own nested fields. The helper method is therefore not just a convenience; it is the reusable primitive that lets the whole object graph serialize cleanly.

        In the uploaded helper examples, the method opens a JSON object, consults the instance's isPresent() list, and then writes only the fields currently marked present. Simple fields are written directly, while nested CDP objects are recursively asked to write themselves through their own toJSON methods.

      • enumStrValidate

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        java.util.stream.IntStream enumStrValidate​(DOMAIN_NESTED THIS)
        Returns the indices of any string fields whose values do not match their allowed enumerated constants. Validates enumerated string fields and returns the indices of any fields whose values are not members of their allowed constant lists.

        Some CDP string fields are not arbitrary text; they are effectively enum values represented as strings. The purpose of this method is to scan the concrete object and identify which of those fields, if any, contain invalid values. The return type is an IntStream so the caller receives the field indices of the failures rather than a simple yes-or-no answer. That makes the result easy to inspect, transform, or feed into an exception-building method.

        At the public API level, this helper method is surfaced by BaseType.enumStrValidate() and paired with BaseType.enumStrValidateThrow(). The first lets the caller inspect errors non-destructively; the second turns those errors into a formatted InvalidEnumStrException. This matches the same overall philosophy used for optional field validation: the library records and reports structure carefully, but it leaves strict enforcement under caller control.

        Not every helper currently has meaningful enum-string validation logic. A helper may legally return an empty stream when no enumerated-string fields exist, when all such fields are valid, or when the concrete type simply has no enum-typed string properties to check.
        See Also:
        BaseType.enumStrValidate(), BaseType.enumStrValidateThrow()

      • allEnumStrROLs

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        ReadOnlyMap<java.lang.String,​ReadOnlyList<java.lang.String>> allEnumStrROLs
            ()
        Retrieves a ReadOnlyMap mapping field names to a ReadOnlyList of valid String values for each field in the map.

        • 🧱 Some String fields declared within CDP data-types may have their values restricted to a fixed set of enumerated strings (similar to a Java enum).

        • 🔧 CDP classes which contain enumeration-restricted String fields do not automatically validate those values within the class constructor itself. However, the CDP root ancestor class (BaseType) provides a dedicated validation method named enumStrValidate() .

        • 🎯 The map returned by this method contains references to the enumerated-string set associated with each restricted String field in this class.

          You may query the map using the field's name (as a java.lang.String).

          If the returned value is non-null, then the queried field is enumeration-restricted, and the returned list contains all valid string values for that field.

        • 🔍 If the returned map is queried using a string which is not the name of a valid String field in this class, then the map will simply return null.

          No exception is thrown by the map's get() method in this situation.

        • 💡 This method returns a non-null, empty map if this particular CDP type does not contain any String fields, or if none of the string fields in this class are enumeration-restricted.
        See Also:
        BaseType.allEnumStrROLs()