package Torello.Browser;

import java.util.*;
import javax.json.*;
import javax.json.stream.*;
import java.io.*;

import java.lang.reflect.Method;
import java.lang.reflect.Parameter;
import java.util.function.Function;

import Torello.Java.Additional.*;
import Torello.Java.JSON.*;

import static Torello.Java.JSON.JFlag.*;

import Torello.Java.StrCmpr;
import Torello.JavaDoc.StaticFunctional;
import Torello.JavaDoc.JDHeaderBackgroundImg;
import Torello.JavaDoc.Excuse;

/**
 * <SPAN CLASS=COPIEDJDK><B>DOM debugging allows setting breakpoints on particular DOM operations and events. JavaScript
 * execution will stop on these operations as if there was a regular breakpoint set.</B></SPAN>
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=CODE_GEN_NOTE>
 */
@StaticFunctional(Excused={"counter"}, Excuses={Excuse.CONFIGURATION})
@JDHeaderBackgroundImg(EmbedTagFileID="WOOD_PLANK_NOTE")
public class DOMDebugger
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Class Header Stuff
    // ********************************************************************************************
    // ********************************************************************************************


    // No Pubic Constructors
    private DOMDebugger () { }

    // These two Vector's are used by all the "Methods" exported by this class.  java.lang.reflect
    // is used to generate the JSON String's.  It saves thousands of lines of Auto-Generated Code.
    private static final Map<String, Vector<String>>    parameterNames = new HashMap<>();
    private static final Map<String, Vector<Class<?>>>  parameterTypes = new HashMap<>();

    // Some Methods do not take any parameters - for instance all the "enable()" and "disable()"
    // I simply could not get ride of RAW-TYPES and UNCHECKED warnings... so there are now,
    // offically, two empty-vectors.  One for String's, and the other for Classes.

    private static final Vector<String>     EMPTY_VEC_STR = new Vector<>();
    private static final Vector<Class<?>>   EMPTY_VEC_CLASS = new Vector<>();

    static
    {
        for (Method m : DOMDebugger.class.getMethods())
        {
            // This doesn't work!  The parameter names are all "arg0" ... "argN"
            // It works for java.lang.reflect.Field, BUT NOT java.lang.reflect.Parameter!
            //
            // Vector<String> parameterNamesList = new Vector<>(); -- NOPE!

            Vector<Class<?>> parameterTypesList = new Vector<>();
        
            for (Parameter p : m.getParameters()) parameterTypesList.add(p.getType());

            parameterTypes.put(
                m.getName(),
                (parameterTypesList.size() > 0) ? parameterTypesList : EMPTY_VEC_CLASS
            );
        }
    }

    static
    {
        Vector<String> v = null;

        v = new Vector<String>(3);
        parameterNames.put("getEventListeners", v);
        Collections.addAll(v, new String[]
        { "objectId", "depth", "pierce", });

        v = new Vector<String>(2);
        parameterNames.put("removeDOMBreakpoint", v);
        Collections.addAll(v, new String[]
        { "nodeId", "type", });

        v = new Vector<String>(2);
        parameterNames.put("removeEventListenerBreakpoint", v);
        Collections.addAll(v, new String[]
        { "eventName", "targetName", });

        v = new Vector<String>(1);
        parameterNames.put("removeInstrumentationBreakpoint", v);
        Collections.addAll(v, new String[]
        { "eventName", });

        v = new Vector<String>(1);
        parameterNames.put("removeXHRBreakpoint", v);
        Collections.addAll(v, new String[]
        { "url", });

        v = new Vector<String>(1);
        parameterNames.put("setBreakOnCSPViolation", v);
        Collections.addAll(v, new String[]
        { "violationTypes", });

        v = new Vector<String>(2);
        parameterNames.put("setDOMBreakpoint", v);
        Collections.addAll(v, new String[]
        { "nodeId", "type", });

        v = new Vector<String>(2);
        parameterNames.put("setEventListenerBreakpoint", v);
        Collections.addAll(v, new String[]
        { "eventName", "targetName", });

        v = new Vector<String>(1);
        parameterNames.put("setInstrumentationBreakpoint", v);
        Collections.addAll(v, new String[]
        { "eventName", });

        v = new Vector<String>(1);
        parameterNames.put("setXHRBreakpoint", v);
        Collections.addAll(v, new String[]
        { "url", });
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Types - Static Inner Classes
    // ********************************************************************************************
    // ********************************************************************************************

    /** DOM breakpoint type. */
    public static final String[] DOMBreakpointType =
    { "subtree-modified", "attribute-modified", "node-removed", };
    
    /**
     * CSP Violation type.
     * <BR />
     * <BR /><B>EXPERIMENTAL</B>
     */
    public static final String[] CSPViolationType =
    { "trustedtype-sink-violation", "trustedtype-policy-violation", };
    
    /** Object event listener. */
    public static class EventListener
        extends BaseType
        implements java.io.Serializable
    {
        /** For Object Serialization.  java.io.Serializable */
        protected static final long serialVersionUID = 1;
        
        public boolean[] optionals()
        { return new boolean[] { false, false, false, false, false, false, false, true, true, true, }; }
        
        /** <CODE>EventListener</CODE>'s type. */
        public final String type;
        
        /** <CODE>EventListener</CODE>'s useCapture. */
        public final boolean useCapture;
        
        /** <CODE>EventListener</CODE>'s passive flag. */
        public final boolean passive;
        
        /** <CODE>EventListener</CODE>'s once flag. */
        public final boolean once;
        
        /** Script id of the handler code. */
        public final String scriptId;
        
        /** Line number in the script (0-based). */
        public final int lineNumber;
        
        /** Column number in the script (0-based). */
        public final int columnNumber;
        
        /**
         * Event handler function value.
         * <BR />
         * <BR /><B>OPTIONAL</B>
         */
        public final RunTime.RemoteObject handler;
        
        /**
         * Event original handler function value.
         * <BR />
         * <BR /><B>OPTIONAL</B>
         */
        public final RunTime.RemoteObject originalHandler;
        
        /**
         * Node the listener is added to (if any).
         * <BR />
         * <BR /><B>OPTIONAL</B>
         */
        public final Integer backendNodeId;
        
        /**
         * Constructor
         *
         * @param type <CODE>EventListener</CODE>'s type.
         * 
         * @param useCapture <CODE>EventListener</CODE>'s useCapture.
         * 
         * @param passive <CODE>EventListener</CODE>'s passive flag.
         * 
         * @param once <CODE>EventListener</CODE>'s once flag.
         * 
         * @param scriptId Script id of the handler code.
         * 
         * @param lineNumber Line number in the script (0-based).
         * 
         * @param columnNumber Column number in the script (0-based).
         * 
         * @param handler Event handler function value.
         * <BR /><B>OPTIONAL</B>
         * 
         * @param originalHandler Event original handler function value.
         * <BR /><B>OPTIONAL</B>
         * 
         * @param backendNodeId Node the listener is added to (if any).
         * <BR /><B>OPTIONAL</B>
         */
        public EventListener(
                String type, boolean useCapture, boolean passive, boolean once, String scriptId, 
                int lineNumber, int columnNumber, RunTime.RemoteObject handler, 
                RunTime.RemoteObject originalHandler, Integer backendNodeId
            )
        {
            // Exception-Check(s) to ensure that if any parameters which are not declared as
            // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
            
            if (type == null)     BRDPC.throwNPE("type");
            if (scriptId == null) BRDPC.throwNPE("scriptId");
            
            this.type             = type;
            this.useCapture       = useCapture;
            this.passive          = passive;
            this.once             = once;
            this.scriptId         = scriptId;
            this.lineNumber       = lineNumber;
            this.columnNumber     = columnNumber;
            this.handler          = handler;
            this.originalHandler  = originalHandler;
            this.backendNodeId    = backendNodeId;
        }
        
        /**
         * JSON Object Constructor
         * @param jo A Json-Object having data about an instance of {@code 'EventListener'}.
         */
        public EventListener (JsonObject jo)
        {
            this.type             = ReadJSON.getString(jo, "type", false, true);
            this.useCapture       = ReadPrimJSON.getBoolean(jo, "useCapture");
            this.passive          = ReadPrimJSON.getBoolean(jo, "passive");
            this.once             = ReadPrimJSON.getBoolean(jo, "once");
            this.scriptId         = ReadJSON.getString(jo, "scriptId", false, true);
            this.lineNumber       = ReadPrimJSON.getInt(jo, "lineNumber");
            this.columnNumber     = ReadPrimJSON.getInt(jo, "columnNumber");
            this.handler          = ReadJSON.getObject(jo, "handler", RunTime.RemoteObject.class, true, false);
            this.originalHandler  = ReadJSON.getObject(jo, "originalHandler", RunTime.RemoteObject.class, true, false);
            this.backendNodeId    = ReadBoxedJSON.getInteger(jo, "backendNodeId", true);
        }
        
        
        /** Checks whether {@code 'this'} equals an input Java-{@code Object} */
        public boolean equals(Object other)
        {
            if (other == null)                       return false;
            if (other.getClass() != this.getClass()) return false;
        
            EventListener o = (EventListener) other;
        
            return
                    Objects.equals(this.type, o.type)
                &&  (this.useCapture == o.useCapture)
                &&  (this.passive == o.passive)
                &&  (this.once == o.once)
                &&  Objects.equals(this.scriptId, o.scriptId)
                &&  (this.lineNumber == o.lineNumber)
                &&  (this.columnNumber == o.columnNumber)
                &&  Objects.equals(this.handler, o.handler)
                &&  Objects.equals(this.originalHandler, o.originalHandler)
                &&  Objects.equals(this.backendNodeId, o.backendNodeId);
        }
        
        /** Generates a Hash-Code for {@code 'this'} instance */
        public int hashCode()
        {
            return
                    Objects.hashCode(this.type)
                +   (this.useCapture ? 1 : 0)
                +   (this.passive ? 1 : 0)
                +   (this.once ? 1 : 0)
                +   Objects.hashCode(this.scriptId)
                +   this.lineNumber
                +   this.columnNumber
                +   this.handler.hashCode()
                +   this.originalHandler.hashCode()
                +   Objects.hashCode(this.backendNodeId);
        }
    }
    
    
    // Counter for keeping the WebSocket Request ID's distinct.
    private static int counter = 1;
    
    /**
     * Returns event listeners of the given object.
     * 
     * @param objectId Identifier of the object to return listeners for.
     * 
     * @param depth 
     * The maximum depth at which Node children should be retrieved, defaults to 1. Use -1 for the
     * entire subtree or provide an integer larger than 0.
     * <BR /><B>OPTIONAL</B>
     * 
     * @param pierce 
     * Whether or not iframes and shadow roots should be traversed when returning the subtree
     * (default is false). Reports listeners for all contexts if pierce is enabled.
     * <BR /><B>OPTIONAL</B>
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * {@link DOMDebugger.EventListener}[]&gt;</CODE>
     * 
     * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using
     * {@link Script#exec()}, and afterwards, a {@link Promise}<CODE>&lt;JsonObject,
     * {@link DOMDebugger.EventListener}[]&gt;</CODE> will be returned.
     *
     * <BR /><BR />Finally, the <B>{@code Promise}</B> may be <B STYLE='color: red'>awaited</B>,
     * using {@link Promise#await()}, <I>and the returned result of this Browser Function may
      * may be retrieved.</I>
     *
     * <BR /><BR />This Browser Function <B STYLE='color: red'>returns</B>
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI><CODE>{@link DOMDebugger.EventListener}[] (<B>listeners</B></CODE>)
     *     <BR />Array of relevant listeners.
     * </LI>
     * </UL> */
    public static Script<String, JsonObject, DOMDebugger.EventListener[]> getEventListeners
        (String objectId, Integer depth, Boolean pierce)
    {
        // Exception-Check(s) to ensure that if any parameters which are not declared as
        // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
        
        if (objectId == null) BRDPC.throwNPE("objectId");
        
        final int       webSocketID = 16000000 + counter++;
        final boolean[] optionals   = { false, true, true, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("getEventListeners"),
            parameterNames.get("getEventListeners"),
            optionals, webSocketID,
            "DOMDebugger.getEventListeners",
            objectId, depth, pierce
        );
        
        // 'JSON Binding' ... Converts Browser Response-JSON to 'DOMDebugger.EventListener[]'
        Function<JsonObject, DOMDebugger.EventListener[]> responseProcessor = (JsonObject jo) ->
            (jo.getJsonArray("listeners") == null)
                ? null
                : RJArrDimN.objArr(jo.getJsonArray("listeners"), null, 0, DOMDebugger.EventListener[].class);
        
        // Pass the 'defaultSender' to Script-Constructor
        // The sender that is used can be changed before executing script.
        return new Script<>(BRDPC.defaultSender, webSocketID, requestJSON, responseProcessor);
    }
    
    /**
     * Removes DOM breakpoint that was set using <CODE>setDOMBreakpoint</CODE>.
     * 
     * @param nodeId Identifier of the node to remove breakpoint from.
     * 
     * @param type Type of the breakpoint to remove.
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * {@link Ret0}&gt;</CODE>
     *
     * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the
     * browser receives the invocation-request.
     *
     * <BR /><BR />This Browser-Function <I>does not have</I> a return-value.  You may choose to
     * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0}
     * {@code >} to ensure the Browser Function has run to completion.
     */
    public static Script<String, JsonObject, Ret0> removeDOMBreakpoint(int nodeId, String type)
    {
        // Exception-Check(s) to ensure that if any parameters which are not declared as
        // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
        
        if (type == null) BRDPC.throwNPE("type");
        
        // Exception-Check(s) to ensure that if any parameters which must adhere to a
        // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw.
        
        BRDPC.checkIAE("type", type, "DOMDebugger.DOMBreakpointType", DOMDebugger.DOMBreakpointType);
        
        final int       webSocketID = 16001000 + counter++;
        final boolean[] optionals   = { false, false, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("removeDOMBreakpoint"),
            parameterNames.get("removeDOMBreakpoint"),
            optionals, webSocketID,
            "DOMDebugger.removeDOMBreakpoint",
            nodeId, type
        );
        
        // This Remote Command does not have a Return-Value.
        return new Script<>
            (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues);
    }
    
    /**
     * Removes breakpoint on particular DOM event.
     * 
     * @param eventName Event name.
     * 
     * @param targetName EventTarget interface name.
     * <BR /><B>OPTIONAL</B>
     * <BR /><B>EXPERIMENTAL</B>
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * {@link Ret0}&gt;</CODE>
     *
     * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the
     * browser receives the invocation-request.
     *
     * <BR /><BR />This Browser-Function <I>does not have</I> a return-value.  You may choose to
     * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0}
     * {@code >} to ensure the Browser Function has run to completion.
     */
    public static Script<String, JsonObject, Ret0> removeEventListenerBreakpoint
        (String eventName, String targetName)
    {
        // Exception-Check(s) to ensure that if any parameters which are not declared as
        // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
        
        if (eventName == null) BRDPC.throwNPE("eventName");
        
        final int       webSocketID = 16002000 + counter++;
        final boolean[] optionals   = { false, true, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("removeEventListenerBreakpoint"),
            parameterNames.get("removeEventListenerBreakpoint"),
            optionals, webSocketID,
            "DOMDebugger.removeEventListenerBreakpoint",
            eventName, targetName
        );
        
        // This Remote Command does not have a Return-Value.
        return new Script<>
            (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues);
    }
    
    /**
     * Removes breakpoint on particular native event.
     * <BR /><B>EXPERIMENTAL</B>
     * 
     * @param eventName Instrumentation name to stop on.
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * {@link Ret0}&gt;</CODE>
     *
     * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the
     * browser receives the invocation-request.
     *
     * <BR /><BR />This Browser-Function <I>does not have</I> a return-value.  You may choose to
     * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0}
     * {@code >} to ensure the Browser Function has run to completion.
     */
    public static Script<String, JsonObject, Ret0> removeInstrumentationBreakpoint
        (String eventName)
    {
        // Exception-Check(s) to ensure that if any parameters which are not declared as
        // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
        
        if (eventName == null) BRDPC.throwNPE("eventName");
        
        final int       webSocketID = 16003000 + counter++;
        final boolean[] optionals   = { false, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("removeInstrumentationBreakpoint"),
            parameterNames.get("removeInstrumentationBreakpoint"),
            optionals, webSocketID,
            "DOMDebugger.removeInstrumentationBreakpoint",
            eventName
        );
        
        // This Remote Command does not have a Return-Value.
        return new Script<>
            (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues);
    }
    
    /**
     * Removes breakpoint from XMLHttpRequest.
     * 
     * @param url Resource URL substring.
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * {@link Ret0}&gt;</CODE>
     *
     * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the
     * browser receives the invocation-request.
     *
     * <BR /><BR />This Browser-Function <I>does not have</I> a return-value.  You may choose to
     * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0}
     * {@code >} to ensure the Browser Function has run to completion.
     */
    public static Script<String, JsonObject, Ret0> removeXHRBreakpoint(String url)
    {
        // Exception-Check(s) to ensure that if any parameters which are not declared as
        // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
        
        if (url == null) BRDPC.throwNPE("url");
        
        final int       webSocketID = 16004000 + counter++;
        final boolean[] optionals   = { false, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("removeXHRBreakpoint"),
            parameterNames.get("removeXHRBreakpoint"),
            optionals, webSocketID,
            "DOMDebugger.removeXHRBreakpoint",
            url
        );
        
        // This Remote Command does not have a Return-Value.
        return new Script<>
            (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues);
    }
    
    /**
     * Sets breakpoint on particular CSP violations.
     * <BR /><B>EXPERIMENTAL</B>
     * 
     * @param violationTypes CSP Violations to stop upon.
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * {@link Ret0}&gt;</CODE>
     *
     * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the
     * browser receives the invocation-request.
     *
     * <BR /><BR />This Browser-Function <I>does not have</I> a return-value.  You may choose to
     * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0}
     * {@code >} to ensure the Browser Function has run to completion.
     */
    public static Script<String, JsonObject, Ret0> setBreakOnCSPViolation
        (String[] violationTypes)
    {
        // Exception-Check(s) to ensure that if any parameters which are not declared as
        // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
        
        if (violationTypes == null) BRDPC.throwNPE("violationTypes");
        
        final int       webSocketID = 16005000 + counter++;
        final boolean[] optionals   = { false, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("setBreakOnCSPViolation"),
            parameterNames.get("setBreakOnCSPViolation"),
            optionals, webSocketID,
            "DOMDebugger.setBreakOnCSPViolation",
            (Object) violationTypes
        );
        
        // This Remote Command does not have a Return-Value.
        return new Script<>
            (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues);
    }
    
    /**
     * Sets breakpoint on particular operation with DOM.
     * 
     * @param nodeId Identifier of the node to set breakpoint on.
     * 
     * @param type Type of the operation to stop upon.
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * {@link Ret0}&gt;</CODE>
     *
     * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the
     * browser receives the invocation-request.
     *
     * <BR /><BR />This Browser-Function <I>does not have</I> a return-value.  You may choose to
     * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0}
     * {@code >} to ensure the Browser Function has run to completion.
     */
    public static Script<String, JsonObject, Ret0> setDOMBreakpoint(int nodeId, String type)
    {
        // Exception-Check(s) to ensure that if any parameters which are not declared as
        // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
        
        if (type == null) BRDPC.throwNPE("type");
        
        // Exception-Check(s) to ensure that if any parameters which must adhere to a
        // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw.
        
        BRDPC.checkIAE("type", type, "DOMDebugger.DOMBreakpointType", DOMDebugger.DOMBreakpointType);
        
        final int       webSocketID = 16006000 + counter++;
        final boolean[] optionals   = { false, false, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("setDOMBreakpoint"),
            parameterNames.get("setDOMBreakpoint"),
            optionals, webSocketID,
            "DOMDebugger.setDOMBreakpoint",
            nodeId, type
        );
        
        // This Remote Command does not have a Return-Value.
        return new Script<>
            (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues);
    }
    
    /**
     * Sets breakpoint on particular DOM event.
     * 
     * @param eventName DOM Event name to stop on (any DOM event will do).
     * 
     * @param targetName 
     * EventTarget interface name to stop on. If equal to <CODE>"*"</CODE> or not provided, will stop on any
     * EventTarget.
     * <BR /><B>OPTIONAL</B>
     * <BR /><B>EXPERIMENTAL</B>
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * {@link Ret0}&gt;</CODE>
     *
     * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the
     * browser receives the invocation-request.
     *
     * <BR /><BR />This Browser-Function <I>does not have</I> a return-value.  You may choose to
     * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0}
     * {@code >} to ensure the Browser Function has run to completion.
     */
    public static Script<String, JsonObject, Ret0> setEventListenerBreakpoint
        (String eventName, String targetName)
    {
        // Exception-Check(s) to ensure that if any parameters which are not declared as
        // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
        
        if (eventName == null) BRDPC.throwNPE("eventName");
        
        final int       webSocketID = 16007000 + counter++;
        final boolean[] optionals   = { false, true, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("setEventListenerBreakpoint"),
            parameterNames.get("setEventListenerBreakpoint"),
            optionals, webSocketID,
            "DOMDebugger.setEventListenerBreakpoint",
            eventName, targetName
        );
        
        // This Remote Command does not have a Return-Value.
        return new Script<>
            (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues);
    }
    
    /**
     * Sets breakpoint on particular native event.
     * <BR /><B>EXPERIMENTAL</B>
     * 
     * @param eventName Instrumentation name to stop on.
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * {@link Ret0}&gt;</CODE>
     *
     * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the
     * browser receives the invocation-request.
     *
     * <BR /><BR />This Browser-Function <I>does not have</I> a return-value.  You may choose to
     * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0}
     * {@code >} to ensure the Browser Function has run to completion.
     */
    public static Script<String, JsonObject, Ret0> setInstrumentationBreakpoint
        (String eventName)
    {
        // Exception-Check(s) to ensure that if any parameters which are not declared as
        // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
        
        if (eventName == null) BRDPC.throwNPE("eventName");
        
        final int       webSocketID = 16008000 + counter++;
        final boolean[] optionals   = { false, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("setInstrumentationBreakpoint"),
            parameterNames.get("setInstrumentationBreakpoint"),
            optionals, webSocketID,
            "DOMDebugger.setInstrumentationBreakpoint",
            eventName
        );
        
        // This Remote Command does not have a Return-Value.
        return new Script<>
            (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues);
    }
    
    /**
     * Sets breakpoint on XMLHttpRequest.
     * 
     * @param url Resource URL substring. All XHRs having this substring in the URL will get stopped upon.
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * {@link Ret0}&gt;</CODE>
     *
     * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the
     * browser receives the invocation-request.
     *
     * <BR /><BR />This Browser-Function <I>does not have</I> a return-value.  You may choose to
     * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0}
     * {@code >} to ensure the Browser Function has run to completion.
     */
    public static Script<String, JsonObject, Ret0> setXHRBreakpoint(String url)
    {
        // Exception-Check(s) to ensure that if any parameters which are not declared as
        // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
        
        if (url == null) BRDPC.throwNPE("url");
        
        final int       webSocketID = 16009000 + counter++;
        final boolean[] optionals   = { false, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("setXHRBreakpoint"),
            parameterNames.get("setXHRBreakpoint"),
            optionals, webSocketID,
            "DOMDebugger.setXHRBreakpoint",
            url
        );
        
        // This Remote Command does not have a Return-Value.
        return new Script<>
            (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues);
    }
    
}