Class BrowserConn

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<BrowserConn>
    public class BrowserConn
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable<BrowserConn>, java.lang.Cloneable
    A Connection to a Browser, rather than an individual Page within the Browser.

    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: getBrowserConn. This instance contains 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(WebSocketSender) method.

    Obtaining the WebSocketSender instance can be achieved by invoking BrowserConn.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/version.

    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
      BrowserConn​(String browser, String protocolVersion, String userAgent, String v8Version, String webkitVersion, String webSocketDebuggerUrl)
      Constructs an instance of this type.
      BrowserConn​(JsonObject jo)

    • Method Summary

       
      Create Browser WebSocket Sender
      Modifier and Type Method Description
      WebSocketSender createSender​(ConnRecord connRec)
      Creates a WebSocketSender connected to the webSocketDebuggerUrl for this tab.
       
      Static-Getter: Creates an Instance of this Class
      Modifier and Type Method Description
      static BrowserConn getBrowserConn​(Integer port, boolean quiet)
      Retrieves the WebSocketDebugger URL for the main browser instance.
       
      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​(BrowserConn other)  
       
      Methods: interface java.lang.Cloneable
      Modifier and Type Method Description
      BrowserConn 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;

      • browser

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String browser
        The browser's identity string, typically in the format "Chrome/123.0.0.0". This value identifies the actual build and version of the running Chrome instance.
        Code:
        Exact Field Declaration Expression:
         public final String browser;

      • protocolVersion

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String protocolVersion
        The protocol version exposed by the Chrome DevTools Protocol. Usually in the format "1.3". Required for feature compatibility and command dispatch matching.
        Code:
        Exact Field Declaration Expression:
         public final String protocolVersion;

      • userAgent

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String userAgent
        The full User-Agent string as reported by the browser. This is typically sent with HTTP requests and can be used for debugging or emulating different clients.
        Code:
        Exact Field Declaration Expression:
         public final String userAgent;

      • v8Version

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String v8Version
        The version string for the embedded V8 JavaScript engine. Informational only; useful for diagnostics or feature expectations tied to ECMAScript support.
        Code:
        Exact Field Declaration Expression:
         public final String v8Version;

      • webkitVersion

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String webkitVersion
        The WebKit version string used in the rendering engine. Like the V8 version, this is generally used for diagnostic purposes, especially in rendering bug analysis.
        Code:
        Exact Field Declaration Expression:
         public final String webkitVersion;

      • webSocketDebuggerUrl

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String webSocketDebuggerUrl
        The WebSocket Debugger URL used to initiate communication with the Chrome DevTools Protocol. This URL is required to establish a live debugging session or automation bridge with the browser instance.
        Code:
        Exact Field Declaration Expression:
         public final String webSocketDebuggerUrl;

    • Constructor Detail

      • BrowserConn

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public BrowserConn​(java.lang.String browser,
                   java.lang.String protocolVersion,
                   java.lang.String userAgent,
                   java.lang.String v8Version,
                   java.lang.String webkitVersion,
                   java.lang.String webSocketDebuggerUrl)
        Constructs an instance of this type.
        Throws:
        java.lang.NullPointerException - if 'webSocketDebuggerUrl' is passed null.
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(webSocketDebuggerUrl, "webSocketDebuggerUrl is null");

 this.browser                = browser;
 this.protocolVersion        = protocolVersion;
 this.userAgent              = userAgent;
 this.v8Version              = v8Version;
 this.webkitVersion          = webkitVersion;
 this.webSocketDebuggerUrl   = webSocketDebuggerUrl;

      • BrowserConn

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public BrowserConn​(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 - The exact JsonObject that was generated by querying the HTTP End-Point /json/version.
        See Also:
        ReadJSON.getString(JsonObject, String, boolean, boolean)
        Code:
        Exact Constructor Body:
         this.browser            = ReadJSON.getString(jo, "Browser",             false,  true);
 this.protocolVersion    = ReadJSON.getString(jo, "Protocol-Version",    false,  true);
 this.userAgent          = ReadJSON.getString(jo, "User-Agent",          false,  true);
 this.v8Version          = ReadJSON.getString(jo, "V8-Version",          true,   false);
 this.webkitVersion      = ReadJSON.getString(jo, "WebKit-Version",      true,   false);

 this.webSocketDebuggerUrl =
     ReadJSON.getString(jo, "webSocketDebuggerUrl", false,  true);

    • Method Detail

      • getBrowserConn

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public static BrowserConn getBrowserConn​(java.lang.Integer port,
                                         boolean quiet)
        Retrieves the WebSocketDebugger URL for the main browser instance. This queries /json/version and parses the result into an instance.
        Parameters:
        port - The DevTools port Chrome is listening on (default is 9222 if null).
        quiet - If false, debug output is printed to the console.
        Returns:
        A BrowserConn instance representing the browser-level connection.
        Code:
        Exact Method Body:
         return BCBuilder.getBrowserConn(port, quiet);

      • toString

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

      • hashCode

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

      • equals

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