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><CODE>[No Description Provided by Google]</CODE></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 Tracing
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Class Header Stuff
    // ********************************************************************************************
    // ********************************************************************************************


    // No Pubic Constructors
    private Tracing () { }

    // 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 : Tracing.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;

        parameterNames.put("end", EMPTY_VEC_STR);

        parameterNames.put("getCategories", EMPTY_VEC_STR);

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

        v = new Vector<String>(2);
        parameterNames.put("requestMemoryDump", v);
        Collections.addAll(v, new String[]
        { "deterministic", "levelOfDetail", });

        v = new Vector<String>(9);
        parameterNames.put("start", v);
        Collections.addAll(v, new String[]
        { "categories", "options", "bufferUsageReportingInterval", "transferMode", "streamFormat", "streamCompression", "traceConfig", "perfettoConfig", "tracingBackend", });
    }


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

    // public static class MemoryDumpConfig => JsonObject
    
    /**
     * Data format of a trace. Can be either the legacy JSON format or the
     * protocol buffer format. Note that the JSON format will be deprecated soon.
     */
    public static final String[] StreamFormat =
    { "json", "proto", };
    
    /** Compression type to use for traces returned via streams. */
    public static final String[] StreamCompression =
    { "none", "gzip", };
    
    /**
     * Details exposed when memory request explicitly declared.
     * Keep consistent with memory_dump_request_args.h and
     * memory_instrumentation.mojom
     */
    public static final String[] MemoryDumpLevelOfDetail =
    { "background", "light", "detailed", };
    
    /**
     * Backend type to use for tracing. <CODE>chrome</CODE> uses the Chrome-integrated
     * tracing service and is supported on all platforms. <CODE>system</CODE> is only
     * supported on Chrome OS and uses the Perfetto system tracing service.
     * <CODE>auto</CODE> chooses <CODE>system</CODE> when the perfettoConfig provided to Tracing.start
     * specifies at least one non-Chrome data source; otherwise uses <CODE>chrome</CODE>.
     */
    public static final String[] TracingBackend =
    { "auto", "chrome", "system", };
    
    /** <CODE>[No Description Provided by Google]</CODE> */
    public static class TraceConfig
        extends BaseType
        implements java.io.Serializable
    {
        /** For Object Serialization.  java.io.Serializable */
        protected static final long serialVersionUID = 1;
        
        public boolean[] optionals()
        { return new boolean[] { true, true, true, true, true, true, true, true, }; }
        
        /**
         * Controls how the trace buffer stores data.
         * <BR />
         * <BR /><B>OPTIONAL</B>
         */
        public final String recordMode;
        
        /**
         * Turns on JavaScript stack sampling.
         * <BR />
         * <BR /><B>OPTIONAL</B>
         */
        public final Boolean enableSampling;
        
        /**
         * Turns on system tracing.
         * <BR />
         * <BR /><B>OPTIONAL</B>
         */
        public final Boolean enableSystrace;
        
        /**
         * Turns on argument filter.
         * <BR />
         * <BR /><B>OPTIONAL</B>
         */
        public final Boolean enableArgumentFilter;
        
        /**
         * Included category filters.
         * <BR />
         * <BR /><B>OPTIONAL</B>
         */
        public final String[] includedCategories;
        
        /**
         * Excluded category filters.
         * <BR />
         * <BR /><B>OPTIONAL</B>
         */
        public final String[] excludedCategories;
        
        /**
         * Configuration to synthesize the delays in tracing.
         * <BR />
         * <BR /><B>OPTIONAL</B>
         */
        public final String[] syntheticDelays;
        
        /**
         * Configuration for memory dump triggers. Used only when "memory-infra" category is enabled.
         * <BR />
         * <BR /><B>OPTIONAL</B>
         */
        public final JsonObject memoryDumpConfig;
        
        /**
         * Constructor
         *
         * @param recordMode Controls how the trace buffer stores data.
         * <BR />Acceptable Values: ["recordUntilFull", "recordContinuously", "recordAsMuchAsPossible", "echoToConsole"]
         * <BR /><B>OPTIONAL</B>
         * 
         * @param enableSampling Turns on JavaScript stack sampling.
         * <BR /><B>OPTIONAL</B>
         * 
         * @param enableSystrace Turns on system tracing.
         * <BR /><B>OPTIONAL</B>
         * 
         * @param enableArgumentFilter Turns on argument filter.
         * <BR /><B>OPTIONAL</B>
         * 
         * @param includedCategories Included category filters.
         * <BR /><B>OPTIONAL</B>
         * 
         * @param excludedCategories Excluded category filters.
         * <BR /><B>OPTIONAL</B>
         * 
         * @param syntheticDelays Configuration to synthesize the delays in tracing.
         * <BR /><B>OPTIONAL</B>
         * 
         * @param memoryDumpConfig Configuration for memory dump triggers. Used only when "memory-infra" category is enabled.
         * <BR /><B>OPTIONAL</B>
         */
        public TraceConfig(
                String recordMode, Boolean enableSampling, Boolean enableSystrace, 
                Boolean enableArgumentFilter, String[] includedCategories, 
                String[] excludedCategories, String[] syntheticDelays, JsonObject memoryDumpConfig
            )
        {
            // 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(
                "recordMode", recordMode,
                "recordUntilFull", "recordContinuously", "recordAsMuchAsPossible", "echoToConsole"
            );
            
            this.recordMode            = recordMode;
            this.enableSampling        = enableSampling;
            this.enableSystrace        = enableSystrace;
            this.enableArgumentFilter  = enableArgumentFilter;
            this.includedCategories    = includedCategories;
            this.excludedCategories    = excludedCategories;
            this.syntheticDelays       = syntheticDelays;
            this.memoryDumpConfig      = memoryDumpConfig;
        }
        
        /**
         * JSON Object Constructor
         * @param jo A Json-Object having data about an instance of {@code 'TraceConfig'}.
         */
        public TraceConfig (JsonObject jo)
        {
            this.recordMode            = ReadJSON.getString(jo, "recordMode", true, false);
            this.enableSampling        = ReadBoxedJSON.getBoolean(jo, "enableSampling", true);
            this.enableSystrace        = ReadBoxedJSON.getBoolean(jo, "enableSystrace", true);
            this.enableArgumentFilter  = ReadBoxedJSON.getBoolean(jo, "enableArgumentFilter", true);
            this.includedCategories = (jo.getJsonArray("includedCategories") == null)
                ? null
                : RJArrIntoStream.strArr(jo.getJsonArray("includedCategories"), null, 0).toArray(String[]::new);
        
            this.excludedCategories = (jo.getJsonArray("excludedCategories") == null)
                ? null
                : RJArrIntoStream.strArr(jo.getJsonArray("excludedCategories"), null, 0).toArray(String[]::new);
        
            this.syntheticDelays = (jo.getJsonArray("syntheticDelays") == null)
                ? null
                : RJArrIntoStream.strArr(jo.getJsonArray("syntheticDelays"), null, 0).toArray(String[]::new);
        
            this.memoryDumpConfig      = jo.getJsonObject("memoryDumpConfig");
        }
        
        
        /** 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;
        
            TraceConfig o = (TraceConfig) other;
        
            return
                    Objects.equals(this.recordMode, o.recordMode)
                &&  Objects.equals(this.enableSampling, o.enableSampling)
                &&  Objects.equals(this.enableSystrace, o.enableSystrace)
                &&  Objects.equals(this.enableArgumentFilter, o.enableArgumentFilter)
                &&  Arrays.deepEquals(this.includedCategories, o.includedCategories)
                &&  Arrays.deepEquals(this.excludedCategories, o.excludedCategories)
                &&  Arrays.deepEquals(this.syntheticDelays, o.syntheticDelays)
                &&  Objects.equals(this.memoryDumpConfig, o.memoryDumpConfig);
        }
        
        /** Generates a Hash-Code for {@code 'this'} instance */
        public int hashCode()
        {
            return
                    Objects.hashCode(this.recordMode)
                +   Objects.hashCode(this.enableSampling)
                +   Objects.hashCode(this.enableSystrace)
                +   Objects.hashCode(this.enableArgumentFilter)
                +   Arrays.deepHashCode(this.includedCategories)
                +   Arrays.deepHashCode(this.excludedCategories)
                +   Arrays.deepHashCode(this.syntheticDelays)
                +   this.memoryDumpConfig.hashCode();
        }
    }
    
    /** <CODE>[No Description Provided by Google]</CODE> */
    public static class bufferUsage
        extends BrowserEvent
        implements java.io.Serializable
    {
        /** For Object Serialization.  java.io.Serializable */
        protected static final long serialVersionUID = 1;
        
        public boolean[] optionals()
        { return new boolean[] { true, true, true, }; }
        
        /**
         * A number in range [0..1] that indicates the used size of event buffer as a fraction of its
         * total size.
         * <BR />
         * <BR /><B>OPTIONAL</B>
         */
        public final Number percentFull;
        
        /**
         * An approximate number of events in the trace log.
         * <BR />
         * <BR /><B>OPTIONAL</B>
         */
        public final Number eventCount;
        
        /**
         * A number in range [0..1] that indicates the used size of event buffer as a fraction of its
         * total size.
         * <BR />
         * <BR /><B>OPTIONAL</B>
         */
        public final Number value;
        
        /**
         * Constructor
         *
         * @param percentFull 
         * A number in range [0..1] that indicates the used size of event buffer as a fraction of its
         * total size.
         * <BR /><B>OPTIONAL</B>
         * 
         * @param eventCount An approximate number of events in the trace log.
         * <BR /><B>OPTIONAL</B>
         * 
         * @param value 
         * A number in range [0..1] that indicates the used size of event buffer as a fraction of its
         * total size.
         * <BR /><B>OPTIONAL</B>
         */
        public bufferUsage(Number percentFull, Number eventCount, Number value)
        {
            super("Tracing", "bufferUsage", 3);
            
            this.percentFull  = percentFull;
            this.eventCount   = eventCount;
            this.value        = value;
        }
        
        /**
         * JSON Object Constructor
         * @param jo A Json-Object having data about an instance of {@code 'bufferUsage'}.
         */
        public bufferUsage (JsonObject jo)
        {
            super("Tracing", "bufferUsage", 3);
        
            this.percentFull  = ReadNumberJSON.get(jo, "percentFull", true, false);
            this.eventCount   = ReadNumberJSON.get(jo, "eventCount", true, false);
            this.value        = ReadNumberJSON.get(jo, "value", true, false);
        }
        
        
        /** 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;
        
            bufferUsage o = (bufferUsage) other;
        
            return
                    Objects.equals(this.percentFull, o.percentFull)
                &&  Objects.equals(this.eventCount, o.eventCount)
                &&  Objects.equals(this.value, o.value);
        }
        
        /** Generates a Hash-Code for {@code 'this'} instance */
        public int hashCode()
        {
            return
                    Objects.hashCode(this.percentFull)
                +   Objects.hashCode(this.eventCount)
                +   Objects.hashCode(this.value);
        }
    }
    
    /**
     * Contains an bucket of collected trace events. When tracing is stopped collected events will be
     * send as a sequence of dataCollected events followed by tracingComplete event.
     */
    public static class dataCollected
        extends BrowserEvent
        implements java.io.Serializable
    {
        /** For Object Serialization.  java.io.Serializable */
        protected static final long serialVersionUID = 1;
        
        public boolean[] optionals()
        { return new boolean[] { false, }; }
        
        /** <CODE>[No Description Provided by Google]</CODE> */
        public final JsonArray value;
        
        /**
         * Constructor
         *
         * @param value -
         */
        public dataCollected(JsonArray value)
        {
            super("Tracing", "dataCollected", 1);
            
            // 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 (value == null) BRDPC.throwNPE("value");
            
            this.value  = value;
        }
        
        /**
         * JSON Object Constructor
         * @param jo A Json-Object having data about an instance of {@code 'dataCollected'}.
         */
        public dataCollected (JsonObject jo)
        {
            super("Tracing", "dataCollected", 1);
        
            this.value  = jo.getJsonArray("value");
        }
        
        
        /** 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;
        
            dataCollected o = (dataCollected) other;
        
            return
                    Objects.equals(this.value, o.value);
        }
        
        /** Generates a Hash-Code for {@code 'this'} instance */
        public int hashCode()
        {
            return
                    Objects.hashCode(this.value);
        }
    }
    
    /**
     * Signals that tracing is stopped and there is no trace buffers pending flush, all data were
     * delivered via dataCollected events.
     */
    public static class tracingComplete
        extends BrowserEvent
        implements java.io.Serializable
    {
        /** For Object Serialization.  java.io.Serializable */
        protected static final long serialVersionUID = 1;
        
        public boolean[] optionals()
        { return new boolean[] { false, true, true, true, }; }
        
        /**
         * Indicates whether some trace data is known to have been lost, e.g. because the trace ring
         * buffer wrapped around.
         */
        public final boolean dataLossOccurred;
        
        /**
         * A handle of the stream that holds resulting trace data.
         * <BR />
         * <BR /><B>OPTIONAL</B>
         */
        public final String stream;
        
        /**
         * Trace data format of returned stream.
         * <BR />
         * <BR /><B>OPTIONAL</B>
         */
        public final String traceFormat;
        
        /**
         * Compression format of returned stream.
         * <BR />
         * <BR /><B>OPTIONAL</B>
         */
        public final String streamCompression;
        
        /**
         * Constructor
         *
         * @param dataLossOccurred 
         * Indicates whether some trace data is known to have been lost, e.g. because the trace ring
         * buffer wrapped around.
         * 
         * @param stream A handle of the stream that holds resulting trace data.
         * <BR /><B>OPTIONAL</B>
         * 
         * @param traceFormat Trace data format of returned stream.
         * <BR /><B>OPTIONAL</B>
         * 
         * @param streamCompression Compression format of returned stream.
         * <BR /><B>OPTIONAL</B>
         */
        public tracingComplete
            (boolean dataLossOccurred, String stream, String traceFormat, String streamCompression)
        {
            super("Tracing", "tracingComplete", 4);
            
            // 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("traceFormat", traceFormat, "Tracing.StreamFormat", Tracing.StreamFormat);
            BRDPC.checkIAE("streamCompression", streamCompression, "Tracing.StreamCompression", Tracing.StreamCompression);
            
            this.dataLossOccurred   = dataLossOccurred;
            this.stream             = stream;
            this.traceFormat        = traceFormat;
            this.streamCompression  = streamCompression;
        }
        
        /**
         * JSON Object Constructor
         * @param jo A Json-Object having data about an instance of {@code 'tracingComplete'}.
         */
        public tracingComplete (JsonObject jo)
        {
            super("Tracing", "tracingComplete", 4);
        
            this.dataLossOccurred   = ReadPrimJSON.getBoolean(jo, "dataLossOccurred");
            this.stream             = ReadJSON.getString(jo, "stream", true, false);
            this.traceFormat        = ReadJSON.getString(jo, "traceFormat", true, false);
            this.streamCompression  = ReadJSON.getString(jo, "streamCompression", true, false);
        }
        
        
        /** 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;
        
            tracingComplete o = (tracingComplete) other;
        
            return
                    (this.dataLossOccurred == o.dataLossOccurred)
                &&  Objects.equals(this.stream, o.stream)
                &&  Objects.equals(this.traceFormat, o.traceFormat)
                &&  Objects.equals(this.streamCompression, o.streamCompression);
        }
        
        /** Generates a Hash-Code for {@code 'this'} instance */
        public int hashCode()
        {
            return
                    (this.dataLossOccurred ? 1 : 0)
                +   Objects.hashCode(this.stream)
                +   Objects.hashCode(this.traceFormat)
                +   Objects.hashCode(this.streamCompression);
        }
    }
    
    
    // Counter for keeping the WebSocket Request ID's distinct.
    private static int counter = 1;
    
    /**
     * Stop trace events collection.
     * 
     * @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> end()
    {
        final int          webSocketID = 41000000 + counter++;
        final boolean[]    optionals   = new boolean[0];
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("end"),
            parameterNames.get("end"),
            optionals, webSocketID,
            "Tracing.end"
        );
        
        // This Remote Command does not have a Return-Value.
        return new Script<>
            (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues);
    }
    
    /**
     * Gets supported tracing categories.
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * String[]&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,
     * String[]&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>String[] (<B>categories</B></CODE>)
     *     <BR />A list of supported tracing categories.
     * </LI>
     * </UL> */
    public static Script<String, JsonObject, String[]> getCategories()
    {
        final int          webSocketID = 41001000 + counter++;
        final boolean[]    optionals   = new boolean[0];
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("getCategories"),
            parameterNames.get("getCategories"),
            optionals, webSocketID,
            "Tracing.getCategories"
        );
        
        // 'JSON Binding' ... Converts Browser Response-JSON to 'String[]'
        Function<JsonObject, String[]> responseProcessor = (JsonObject jo) ->
            (jo.getJsonArray("categories") == null)
                ? null
                : RJArrIntoStream.strArr(jo.getJsonArray("categories"), null, 0).toArray(String[]::new);
        
        // 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);
    }
    
    /**
     * Record a clock sync marker in the trace.
     * 
     * @param syncId The ID of this clock sync marker
     * 
     * @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> recordClockSyncMarker(String syncId)
    {
        // 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 (syncId == null) BRDPC.throwNPE("syncId");
        
        final int       webSocketID = 41002000 + counter++;
        final boolean[] optionals   = { false, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("recordClockSyncMarker"),
            parameterNames.get("recordClockSyncMarker"),
            optionals, webSocketID,
            "Tracing.recordClockSyncMarker",
            syncId
        );
        
        // This Remote Command does not have a Return-Value.
        return new Script<>
            (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues);
    }
    
    /**
     * Request a global memory dump.
     * 
     * @param deterministic Enables more deterministic results by forcing garbage collection
     * <BR /><B>OPTIONAL</B>
     * 
     * @param levelOfDetail Specifies level of details in memory dump. Defaults to "detailed".
     * <BR /><B>OPTIONAL</B>
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * {@link Ret2}&gt;</CODE>
     *
     * <BR /><BR />This {@link Script} may be <B STYLE='color:red'>executed</B> (using 
     * {@link Script#exec()}), and a {@link Promise} returned.
     *
     * <BR /><BR />When the {@code Promise} is <B STYLE='color: red'>awaited</B>
     * (using {@link Promise#await()}), the {@code Ret2} will subsequently
     * be returned from that call.
     * 
     * <BR /><BR />The <B STYLE='color: red'>returned</B> values are encapsulated
     * in an instance of <B>{@link Ret2}</B>
     *
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI><CODE><B>Ret2.a:</B> String (<B>dumpGuid</B>)</CODE>
     *     <BR />GUID of the resulting global memory dump.
     *     <BR /><BR /></LI>
     * <LI><CODE><B>Ret2.b:</B> Boolean (<B>success</B>)</CODE>
     *     <BR />True iff the global memory dump succeeded.
     *     </LI>
     * </UL>
     */
    public static Script<String, JsonObject, Ret2<String, Boolean>> requestMemoryDump
        (Boolean deterministic, String levelOfDetail)
    {
        // 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("levelOfDetail", levelOfDetail, "Tracing.MemoryDumpLevelOfDetail", Tracing.MemoryDumpLevelOfDetail);
        
        final int       webSocketID = 41003000 + counter++;
        final boolean[] optionals   = { true, true, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("requestMemoryDump"),
            parameterNames.get("requestMemoryDump"),
            optionals, webSocketID,
            "Tracing.requestMemoryDump",
            deterministic, levelOfDetail
        );
        
        // 'JSON Binding' ... Converts Browser Response-JSON into Java-Type 'Ret2'
        Function<JsonObject, Ret2<String, Boolean>> 
            responseProcessor = (JsonObject jo) -> new Ret2<>(
                ReadJSON.getString(jo, "dumpGuid", false, true),
                ReadBoxedJSON.getBoolean(jo, "success", true)
            );
        
        // 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);
    }
    
    /**
     * Start trace events collection.
     * 
     * @param categories Category/tag filter
     * <BR /><B>OPTIONAL</B>
     * <BR /><B>DEPRECATED</B>
     * 
     * @param options Tracing options
     * <BR /><B>OPTIONAL</B>
     * <BR /><B>DEPRECATED</B>
     * 
     * @param bufferUsageReportingInterval If set, the agent will issue bufferUsage events at this interval, specified in milliseconds
     * <BR /><B>OPTIONAL</B>
     * 
     * @param transferMode 
     * Whether to report trace events as series of dataCollected events or to save trace to a
     * stream (defaults to <CODE>ReportEvents</CODE>).
     * <BR />Acceptable Values: ["ReportEvents", "ReturnAsStream"]
     * <BR /><B>OPTIONAL</B>
     * 
     * @param streamFormat 
     * Trace data format to use. This only applies when using <CODE>ReturnAsStream</CODE>
     * transfer mode (defaults to <CODE>json</CODE>).
     * <BR /><B>OPTIONAL</B>
     * 
     * @param streamCompression 
     * Compression format to use. This only applies when using <CODE>ReturnAsStream</CODE>
     * transfer mode (defaults to <CODE>none</CODE>)
     * <BR /><B>OPTIONAL</B>
     * 
     * @param traceConfig -
     * <BR /><B>OPTIONAL</B>
     * 
     * @param perfettoConfig 
     * Base64-encoded serialized perfetto.protos.TraceConfig protobuf message
     * When specified, the parameters <CODE>categories</CODE>, <CODE>options</CODE>, <CODE>traceConfig</CODE>
     * are ignored. (Encoded as a base64 string when passed over JSON)
     * <BR /><B>OPTIONAL</B>
     * 
     * @param tracingBackend Backend type (defaults to <CODE>auto</CODE>)
     * <BR /><B>OPTIONAL</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> start(
            String categories, String options, Number bufferUsageReportingInterval, 
            String transferMode, String streamFormat, String streamCompression, 
            Tracing.TraceConfig traceConfig, String perfettoConfig, String tracingBackend
        )
    {
        // 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(
            "transferMode", transferMode,
            "ReportEvents", "ReturnAsStream"
        );
        BRDPC.checkIAE("streamFormat", streamFormat, "Tracing.StreamFormat", Tracing.StreamFormat);
        BRDPC.checkIAE("streamCompression", streamCompression, "Tracing.StreamCompression", Tracing.StreamCompression);
        BRDPC.checkIAE("tracingBackend", tracingBackend, "Tracing.TracingBackend", Tracing.TracingBackend);
        
        final int       webSocketID = 41004000 + counter++;
        final boolean[] optionals   = { true, true, true, true, true, true, true, true, true, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("start"),
            parameterNames.get("start"),
            optionals, webSocketID,
            "Tracing.start",
            categories, options, bufferUsageReportingInterval, transferMode, streamFormat,
            streamCompression, traceConfig, perfettoConfig, tracingBackend
        );
        
        // This Remote Command does not have a Return-Value.
        return new Script<>
            (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues);
    }
    
}