Class PageConn

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<PageConn>
    public class PageConn
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable<PageConn>, java.lang.Cloneable
    A class which represents a connection to a particular Page or Tab that has been opened within the Browser, rather than a connection to the Browser itself.

    Represents a snapshot of metadata returned from Chrome’s /json/version End-Point. This includes protocol versioning, V8 details, and the root WebSocket URL for establishing DevTools sessions.

    Although this class offers a public constructor, the recommended way to build an instance is via the static method: getAllPageConn. This stream of instances which are returned each contain a few informational fields that were scraped from the Json-Response to the above mentioned Chrome response object.

    A WebSocketSender Instance:
    To begin sending CDP commands, it is mandatory to obtain an instance of the WebSocketSender class which has been connected to a Web Browser. This instance should be passed as the sender to any of the available API methods offered by the Domain Classes in the packages BrowserAPI and / or the classes in JavaScriptAPI. You should review the methods exported by each of the domains and classes within those packages, and note that the Script objects returned by them expose an Script.exec(Torello.Browser.WebSocketSender) method, which cannot be invoked without an instance of WebSocketSender.

    Obtaining the WebSocketSender instance can be achieved by invoking PageConn.createSender, a method offered by this class. This method initializes a WebSocketSender which is connected to the associated webSocketDebuggerUrl. That sender can be used to make invocations into all CDP Domains.

    The individual fields exported by this class are documented below, and within their respective documentation. This class, itself, is largely a structured data holder with minimal logic. Mostly, it parses the Json which is returned by the Web-Browser endpoint /json/list

    Issuing Commands to a Browser:
    The most important aspect to understand when it comes to using the classes BrowserConn, PageConn, and WebSocketSender is what needs to be done in order to start sending commands to the browser over a Web-Socket using the Browser's Remote Debug Port API. These are the steps, listed below, that a programmer should take to begin using the Java-Script and Browser API Tools offered by these pacakges

    1. Ensure that Chrome (or another Chromium-compatible browser) is installed.

    2. Start the browser with its RDP (Remote Debug Port) feature enabled.
      Note: It is acceptable to start a full graphical browser rather than a headless one — as long as RDP is active.

    3. Successfully extract either a BrowserConn or a PageConn instance by invoking their respective get methods.

    4. Invoke either BrowserConn.createSender or PageConn.createSender to retrieve an instance of WebSocketSender.
      This instance can be passed to any Script object generated by the domain class methods in the BrowserAPI or JavaScriptAPI packages.

    5. This package provides example classes demonstrating how to establish connections with either a headless or full browser, and how to issue commands using the domain classes.
    See Also:
    Serialized Form


    • Constructor Summary

      Constructors 
      Constructor Description
      PageConn​(String id, String type, String title, String url, String description, String webSocketDebuggerUrl, String devtoolsFrontendUrl, String faviconUrl)
      Constructs an instance of this type.
      PageConn​(JsonObject jo)

    • Method Summary

       
      Create Page / Tab WebSocket Sender
      Modifier and Type Method Description
      WebSocketSender createSender​(ConnRecord connRec)
      Creates a WebSocketSender connected to the webSocketDebuggerUrl for this tab.
       
      Static-Getter: Creates a Stream of Instance of this Class
      Modifier and Type Method Description
      static Stream<PageConn> getAllPageConn​(Integer port, boolean quiet)
      Retrieves all pages from the CDP-RDP endpoint currently open on the named port.
       
      Methods: class java.lang.Object
      Modifier and Type Method Description
      boolean equals​(Object o)  
      int hashCode()  
      String toString()  
       
      Methods: interface java.lang.Comparable
      Modifier and Type Method Description
      int compareTo​(PageConn other)  
       
      Methods: interface java.lang.Cloneable
      Modifier and Type Method Description
      PageConn clone()  

      • Methods inherited from class java.lang.Object

        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;

      • id

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String id
        Unique identifier for the DevTools target (usually a browser tab or iframe).
        Code:
        Exact Field Declaration Expression:
         public final String id;

      • type

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String type
        The type of target, typically "page", but can also be "iframe", etc.
        Code:
        Exact Field Declaration Expression:
         public final String type;

      • title

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String title
        The title of the web page as reported by the browser.
        Code:
        Exact Field Declaration Expression:
         public final String title;

      • url

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String url
        The URL currently loaded in the target/tab.
        Code:
        Exact Field Declaration Expression:
         public final String url;

      • description

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String description
        Optional description of the DevTools target. Often an empty string.
        Code:
        Exact Field Declaration Expression:
         public final String description;

      • webSocketDebuggerUrl

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String webSocketDebuggerUrl
        WebSocket endpoint to connect to this target via the Chrome DevTools Protocol.
        Code:
        Exact Field Declaration Expression:
         public final String webSocketDebuggerUrl;

      • devtoolsFrontendUrl

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String devtoolsFrontendUrl
        Internal URL that opens Chrome's DevTools frontend UI for this target.
        Code:
        Exact Field Declaration Expression:
         public final String devtoolsFrontendUrl;

      • faviconUrl

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String faviconUrl
        The URL of the favicon for the target page, if available.
        Code:
        Exact Field Declaration Expression:
         public final String faviconUrl;

    • Constructor Detail

      • PageConn

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public PageConn​(java.lang.String id,
                java.lang.String type,
                java.lang.String title,
                java.lang.String url,
                java.lang.String description,
                java.lang.String webSocketDebuggerUrl,
                java.lang.String devtoolsFrontendUrl,
                java.lang.String faviconUrl)
        Constructs an instance of this type.
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(webSocketDebuggerUrl, "webSocketDebuggerUrl is null");

 this.id                     = id;
 this.type                   = type;
 this.title                  = title;
 this.url                    = url;
 this.description            = description;
 this.webSocketDebuggerUrl   = webSocketDebuggerUrl;
 this.devtoolsFrontendUrl    = devtoolsFrontendUrl;
 this.faviconUrl             = faviconUrl;

      • PageConn

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public PageConn​(JsonObject jo)

        Field Extraction Behavior for PageConn, from a JsonObject

        Field isOptional throwOnNull
        id ❌ false ✅ true
        type ❌ false ✅ true
        title ✅ true ❌ false
        url ❌ false ✅ true
        description ✅ true ❌ false
        webSocketDebuggerUrl ❌ false ✅ true
        devtoolsFrontendUrl ✅ true ❌ false
        faviconUrl ✅ true ❌ false

        🔥 Why This Works

        Feature Explanation
        Predictable: You will never silently receive null on a required field.
        Traceable: If Chrome breaks compatibility, the programmer will receive an exception pointing directly to it.
        Safe: Chrome Optional fields that disappear or return null won't break anything.

        This is exactly how you should structure a wrapper for an external spec you don't control — aggressive for connection-critical data, forgiving for decorative or diagnostic fields.

        💡 If Google changes their output?

        The excellent ReadJSON layer would immediately generate either a JsonPropMissingException or JsonNullObjException allowing the programmer to know eactly which field has failed.

        Page originally drafted by ChatGPT on 2025-07-16.
        Edited and formatted for use in Chrome DevTools Protocol Documentation.

        Parameters:
        jo - Any one of the JsonObject instqnces that were generated by querying the HTTP End-Point /json/list, and selecting one of pages listed within the returned JsonArray.
        See Also:
        ReadJSON.getString(JsonObject, String, boolean, boolean)
        Code:
        Exact Constructor Body:
         // Boolean #1: 'isOptional'
 //      FALSE   ==> throws if Missing
 //      TRUE    ==> Assigns Null if Missing
 // 
 // Boolean #2: 'throwOnNull'
 //      FALSE   ==> returns null if Json-Null has been passed
 //      TRUE    ==> throws if Json-Null has been passed

 this.id     = ReadJSON.getString(jo, "id",      false, true);
 this.type   = ReadJSON.getString(jo, "type",    false, true);
 this.title  = ReadJSON.getString(jo, "title",   true, false);
 this.url    = ReadJSON.getString(jo, "url",     false, true);
    
 this.description =
     ReadJSON.getString(jo, "description", true, false);
    
 this.webSocketDebuggerUrl =
     ReadJSON.getString(jo, "webSocketDebuggerUrl", false, true);
    
 this.devtoolsFrontendUrl =
     ReadJSON.getString(jo, "devtoolsFrontendUrl", true, false);
    
 this.faviconUrl =
     ReadJSON.getString(jo, "faviconUrl", true, false);

    • Method Detail

      • getAllPageConn

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public static java.util.stream.Stream<PageConn> getAllPageConn​
            (java.lang.Integer port,
             boolean quiet)
        Retrieves all pages from the CDP-RDP endpoint currently open on the named port. This queries /json/list and returns a Java-Stream of the instnces of this class.
        Parameters:
        port - The DevTools port Chrome is listening on (default is 9222 if null).
        quiet - If TRUE, output is shunted.
        Returns:
        A list of all Open-Pages, as instances of PageConn
        Code:
        Exact Method Body:
         return PCBuilder.getAllPageConn(port, quiet);

      • toString

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
        Code:
        Exact Method Body:
         return PCHelper.toString(this);

      • hashCode

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
        Code:
        Exact Method Body:
         return PCHelper.hashCode(this);

      • equals

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object
        Code:
        Exact Method Body:
         return PCHelper.equals(this, o);

      • compareTo

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public int compareTo​(PageConn other)
        Specified by:
        compareTo in interface java.lang.Comparable<PageConn>
        Code:
        Exact Method Body:
         return this.webSocketDebuggerUrl.compareTo(other.webSocketDebuggerUrl);