Class ConnRecord

  • public class ConnRecord
extends java.lang.Object
    Central record, log collector, and user-callback router for a CDP browser session.

    A ConnRecord is the single place where the Browser Tool stores the visible products of a Chrome DevTools Protocol connection. A CDP session emits both ordinary text and strongly typed Java objects. Some of that information comes from the low-level WebSocket driver, some comes from the Browser Tool's command/response dispatcher, and some comes from decoded browser events. Without a central record, the output quickly becomes scattered across the connection classes, handler classes, promises, and user examples.

    💡 ConnRecord exists because a CDP session does not produce just one kind of output. It produces a firehose of transport text, JSON request/response text, decoded browser objects, browser-returned errors, and Java-side protocol errors.


    The class centralizes that firehose into two related groups:
    Group What It Contains
    Text Streams: rawSB stores low-level WebSocket / NeoVisionaries reporting.

    appSB stores interpreted CDP activity, such as JSON requests, incoming datagrams, command responses, event decoding, and promise cancellation.

    errSB stores diagnostic and failure text.
    Object Streams: events stores decoded BrowserEvent objects.

    browserErrors stores errors returned by Chrome in response to CDP commands.

    rdpErrors stores Java-side Browser Tool errors raised while handling Remote Debugging Protocol traffic.

    Each text stream may be saved internally, redirected to a user-provided Appendable, or both. Each object stream may be saved internally, forwarded to a user-provided Consumer, or both.

    🎯 The practical result is that examples, tests, and users can decide how much CDP output they want: quiet execution, terminal printing, saved logs, typed event collection, error inspection, or all of those at once.

    This Documentation Page originally drafted by ChatGPT on May 8th, 2026
    Edited and formatted by Ralph Torello for use in the Java HTML Library documentation.



    • Field Detail

      • browserConn

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public BrowserConn browserConn
        Optional reference to the browser-level connection descriptor used by this session.

        This field is provided strictly as a convenience holder for the example classes, and for user code. Neither the methods in this class, nor others in this package read or modify it.

        🧠 This field will only be set by the programmer, and only for convenience, storage purposes
        Code:
        Exact Field Declaration Expression:
         public BrowserConn browserConn = null;

      • pageConn

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public PageConn pageConn
        Optional reference to the page-level connection descriptor used by this session.

        This field is provided strictly as a convenience holder for the example classes, and for user code. Neither the methods in this class, nor others in this package read or modify it.

        🧠 This field will only be set by the programmer, and only for convenience, storage purposes
        Code:
        Exact Field Declaration Expression:
         public PageConn pageConn = null;

      • bws

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public WebSocketSender bws
        Optional reference to the browser-level WebSocketSender used by this session.

        Example code often needs to keep both the browser socket and the page socket close at hand. This field provides a conventional place to store the browser socket.

        🧠 This field will only be set by the programmer, and only for convenience, storage purposes
        Code:
        Exact Field Declaration Expression:
         public WebSocketSender bws = null;

      • pws

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public WebSocketSender pws
        Optional reference to the page-level WebSocketSender used by this session.

        Example code often needs to keep both the browser socket and the page socket close at hand. This field provides a conventional place to store the page socket.

        🧠 This field will only be set by the programmer, and only for convenience, storage purposes
        Code:
        Exact Field Declaration Expression:
         public WebSocketSender pws = null;

      • events

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.util.List<BrowserEvent<?>> events
        List of decoded browser events received during this session.

        📌 Events are added by the package-private event-handling pipeline after a raw CDP event message has been converted into a BrowserEvent instance.
        See Also:
        BrowserEvent, saveEvents
        Code:
        Exact Field Declaration Expression:
         public final List<BrowserEvent<?>> events = new Vector<>();

      • browserErrors

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.util.List<BrowserError> browserErrors
        List of browser-returned command errors received during this session.

        📌 These errors are emitted by Chrome in response to a specific command request. They are distinct from rdpErrors, which are produced by the Java-side Browser Tool when it cannot correctly handle protocol traffic.
        See Also:
        BrowserError, saveBrowserErrors
        Code:
        Exact Field Declaration Expression:
         public final List<BrowserError> browserErrors = new Vector<>();

      • rdpErrors

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.util.List<RDPError> rdpErrors
        List of internal Browser Tool / Remote Debugging Protocol errors received during this session.

        📌 These errors usually indicate malformed, unexpected, unrecognized, or unhandled protocol traffic, or an exception thrown while the Java-side dispatch logic is decoding browser data.
        See Also:
        RDPError, saveRDPErrors
        Code:
        Exact Field Declaration Expression:
         public final List<RDPError> rdpErrors = new Vector<>();

      • rawSB

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.StringBuffer rawSB
        Saved raw WebSocket / NeoVisionaries transport text.

        This stream receives low-level socket-frame, thread, ping, pong, close, disconnect, and other driver-layer messages. It is the closest stream to the WebSocket transport itself.
        See Also:
        saveRawText
        Code:
        Exact Field Declaration Expression:
         public final StringBuffer rawSB = new StringBuffer();

      • appSB

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.StringBuffer appSB
        Saved application-level CDP interpretation text.

        This stream receives text describing outgoing JSON requests, incoming JSON datagrams, command-response handling, browser-event decoding, and promise cancellation.
        See Also:
        saveAppText
        Code:
        Exact Field Declaration Expression:
         public final StringBuffer appSB = new StringBuffer();

      • errSB

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.StringBuffer errSB
        Saved error and diagnostic text.

        This stream receives text describing browser-command errors, unrecognized protocol messages, WebSocket exceptions, malformed responses, and other failures detected while handling CDP traffic.
        See Also:
        saveErrText
        Code:
        Exact Field Declaration Expression:
         public final StringBuffer errSB = new StringBuffer();

    • Constructor Detail

      • ConnRecord

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ConnRecord()
        Creates an empty connection record.

        All object-saving and text-saving switches are enabled by default. The public convenience references for browser/page connections and browser/page WebSocket senders are initialized to null, and may be filled in by example code or connection-building helpers.

    • Method Detail

      • setEventHandler

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void setEventHandler​
            (java.util.function.Consumer<? super BrowserEvent<?>> handler)
        Installs a callback that receives each decoded browser event.

        Passing null clears the current callback. The callback is invoked even when saveEvents is false; the save flag controls only whether the event is stored in events.

        If this handler is non-null, this is invoked in addition to the handler used to store and save BrowserEvent objects in a storage list. This method assigns the programmer's handler to the internal 'userProvidedEventHandler' field, which is a second internal handler for events!
        Parameters:
        handler - A callback for decoded browser events, or null to clear it.
        Code:
        Exact Method Body:
         this.userProvidedEventHandler = handler;

      • setBrowserErrorHandler

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void setBrowserErrorHandler​
            (java.util.function.Consumer<? super BrowserError> handler)
        Installs a callback that receives browser-returned command errors.

        Passing null clears the current callback. The callback is invoked even when saveBrowserErrors is false; the save flag controls only whether the error is stored in browserErrors.

        If this handler is non-null, this is invoked in addition to the handler used to store and save BrowserError objects in a storage list. This assigns the programmer's handler to the internal 'userProvidedBrowserErrorHandler' field, which is a second internal handler for browser errors!
        Parameters:
        handler - A callback for browser-returned command errors, or null to clear it.
        Code:
        Exact Method Body:
         this.userProvidedBrowserErrorHandler = handler;

      • setRDPErrorHandler

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void setRDPErrorHandler​
            (java.util.function.Consumer<? super RDPError> handler)
        Installs a callback that receives internal Browser Tool / RDP errors.

        Passing null clears the current callback. The callback is invoked even when saveRDPErrors is false; the save flag controls only whether the error is stored in rdpErrors.

        If this handler is non-null, this is invoked in addition to the handler used to store and save RDPError objects in a storage list. This assigns the programmer's handler to the internal 'userProvidedRDPErrorHandler' field, which is a second internal handler for transport layer errors.
        Parameters:
        handler - A callback for internal RDP errors, or null to clear it.
        Code:
        Exact Method Body:
         this.userProvidedRDPErrorHandler = handler;

      • acceptEvent

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected void acceptEvent​(BrowserEvent<?> be)
        Accepts a decoded browser event and routes it to storage and/or the user callback.

        This method is protected because it is intended for the Browser Tool's internal handler classes, not for direct end-user invocation.
        Parameters:
        be - The decoded browser event that has been received from Chrome.
        Code:
        Exact Method Body:
         if (this.saveEvents)
     this.events.add(be);

 if (this.userProvidedEventHandler != null)
     this.userProvidedEventHandler.accept(be);

      • acceptBrowserError

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected void acceptBrowserError​(BrowserError bErr)
        Accepts a browser-returned command error and routes it to storage and/or the user callback.

        This method is protected because it is intended for the Browser Tool's internal command response handler, not for direct end-user invocation.
        Parameters:
        bErr - The browser-returned command error that has been received from Chrome.
        Code:
        Exact Method Body:
         if (this.saveBrowserErrors)
     this.browserErrors.add(bErr);

 if (this.userProvidedBrowserErrorHandler != null)
     this.userProvidedBrowserErrorHandler.accept(bErr);

      • acceptRDPError

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected void acceptRDPError​(RDPError rdpErr)
        Accepts an internal Browser Tool / RDP error and routes it to storage and/or the user callback.

        This method is protected because it is intended for the Browser Tool's internal WebSocket and dispatch handlers, not for direct end-user invocation.
        Parameters:
        rdpErr - The internal RDP error that has been produced by the Browser Tool.
        Code:
        Exact Method Body:
         if (this.saveRDPErrors)
     this.rdpErrors.add(rdpErr);

 if (this.userProvidedRDPErrorHandler != null)
     this.userProvidedRDPErrorHandler.accept(rdpErr);

      • setRawTextReceiver

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void setRawTextReceiver​(java.lang.Appendable a)
        Installs an Appendable that receives raw WebSocket / transport text.

        Typical values are System.out, a StringBuilder, a Writer, or an AppendableSafe. Passing null clears the current receiver.
        Parameters:
        a - The destination for raw WebSocket text, or null to clear it.
        See Also:
        AppendableSafe, checkIsInstance(Appendable)
        Code:
        Exact Method Body:
         this.userProvidedRaw = checkIsInstance(a);

      • setAppTextReceiver

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void setAppTextReceiver​(java.lang.Appendable a)
        Installs an Appendable that receives application-level CDP interpretation text.

        Typical values are System.out, a StringBuilder, a Writer, or an AppendableSafe. Passing null clears the current receiver.
        Parameters:
        a - The destination for application-level CDP text, or null to clear it.
        See Also:
        AppendableSafe, checkIsInstance(Appendable)
        Code:
        Exact Method Body:
         this.userProvidedApp = checkIsInstance(a);

      • setErrTextReceiver

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void setErrTextReceiver​(java.lang.Appendable a)
        Installs an Appendable that receives error and diagnostic text.

        Typical values are System.out, a StringBuilder, a Writer, or an AppendableSafe. Passing null clears the current receiver.
        Parameters:
        a - The destination for error and diagnostic text, or null to clear it.
        See Also:
        AppendableSafe, checkIsInstance(Appendable)
        Code:
        Exact Method Body:
         this.userProvidedErr = checkIsInstance(a);

      • raw

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected void raw​(java.lang.String text)
        Accepts raw WebSocket / transport text and routes it to storage and/or the raw receiver.

        This method is protected because raw transport text is produced by the internal WebSocket adapter, not by ordinary end-user code.
        Parameters:
        text - The raw WebSocket / transport text to record.
        See Also:
        saveRawText, rawSB
        Code:
        Exact Method Body:
         if (this.saveRawText)               this.rawSB.append(text);
 if (this.userProvidedRaw != null)   this.userProvidedRaw.append(text);

      • app

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected void app​(java.lang.String text)
        Accepts application-level CDP text and routes it to storage and/or the application receiver.

        This method is protected because application-level CDP text is produced by the internal sender, dispatcher, event handler, and command-response handler.
        Parameters:
        text - The application-level CDP text to record.
        See Also:
        saveAppText, appSB
        Code:
        Exact Method Body:
         if (this.saveAppText)               this.appSB.append(text);
 if (this.userProvidedApp != null)   this.userProvidedApp.append(text);

      • err

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected void err​(java.lang.String text)
        Accepts error and diagnostic text and routes it to storage and/or the error receiver.

        This method is protected because error text is produced by the internal WebSocket, dispatch, event, and command-response handlers.
        Parameters:
        text - The error or diagnostic text to record.
        See Also:
        saveErrText, errSB
        Code:
        Exact Method Body:
         if (this.saveErrText)               this.errSB.append(text);
 if (this.userProvidedErr != null)   this.userProvidedErr.append(text);

      • checkIsInstance

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        protected static AppendableSafe checkIsInstance​(java.lang.Appendable a)
        Ensures that a user-provided Appendable is safe for unchecked logging calls.

        If the appendable is already an AppendableSafe, it is returned directly. Otherwise, it is wrapped so that IOException may be handled by handleLogIOE(IOException). A null value is preserved as null.
        Parameters:
        a - The appendable to check or wrap.
        Returns:
        An AppendableSafe wrapper, the original wrapper, or null.
        Code:
        Exact Method Body:
         return (a == null)
     ? null
     : (a instanceof AppendableSafe)
         ? (AppendableSafe) a
         : new AppendableSafe(a, ConnRecord::handleLogIOE);