001package Torello.Browser; 002 003import java.util.*; 004import javax.json.*; 005import javax.json.stream.*; 006import java.io.*; 007 008import java.lang.reflect.Method; 009import java.lang.reflect.Parameter; 010import java.util.function.Function; 011 012import Torello.Java.Additional.*; 013import Torello.Java.JSON.*; 014 015import static Torello.Java.JSON.JFlag.*; 016 017import Torello.Java.StrCmpr; 018import Torello.JavaDoc.StaticFunctional; 019import Torello.JavaDoc.JDHeaderBackgroundImg; 020import Torello.JavaDoc.Excuse; 021 022/** 023 * <SPAN CLASS=COPIEDJDK><B><CODE>[No Description Provided by Google]</CODE></B></SPAN> 024 * 025 * <EMBED CLASS='external-html' DATA-FILE-ID=CODE_GEN_NOTE> 026 */ 027@StaticFunctional(Excused={"counter"}, Excuses={Excuse.CONFIGURATION}) 028@JDHeaderBackgroundImg(EmbedTagFileID="WOOD_PLANK_NOTE") 029public class Tracing 030{ 031 // ******************************************************************************************** 032 // ******************************************************************************************** 033 // Class Header Stuff 034 // ******************************************************************************************** 035 // ******************************************************************************************** 036 037 038 // No Pubic Constructors 039 private Tracing () { } 040 041 // These two Vector's are used by all the "Methods" exported by this class. java.lang.reflect 042 // is used to generate the JSON String's. It saves thousands of lines of Auto-Generated Code. 043 private static final Map<String, Vector<String>> parameterNames = new HashMap<>(); 044 private static final Map<String, Vector<Class<?>>> parameterTypes = new HashMap<>(); 045 046 // Some Methods do not take any parameters - for instance all the "enable()" and "disable()" 047 // I simply could not get ride of RAW-TYPES and UNCHECKED warnings... so there are now, 048 // offically, two empty-vectors. One for String's, and the other for Classes. 049 050 private static final Vector<String> EMPTY_VEC_STR = new Vector<>(); 051 private static final Vector<Class<?>> EMPTY_VEC_CLASS = new Vector<>(); 052 053 static 054 { 055 for (Method m : Tracing.class.getMethods()) 056 { 057 // This doesn't work! The parameter names are all "arg0" ... "argN" 058 // It works for java.lang.reflect.Field, BUT NOT java.lang.reflect.Parameter! 059 // 060 // Vector<String> parameterNamesList = new Vector<>(); -- NOPE! 061 062 Vector<Class<?>> parameterTypesList = new Vector<>(); 063 064 for (Parameter p : m.getParameters()) parameterTypesList.add(p.getType()); 065 066 parameterTypes.put( 067 m.getName(), 068 (parameterTypesList.size() > 0) ? parameterTypesList : EMPTY_VEC_CLASS 069 ); 070 } 071 } 072 073 static 074 { 075 Vector<String> v = null; 076 077 parameterNames.put("end", EMPTY_VEC_STR); 078 079 parameterNames.put("getCategories", EMPTY_VEC_STR); 080 081 v = new Vector<String>(1); 082 parameterNames.put("recordClockSyncMarker", v); 083 Collections.addAll(v, new String[] 084 { "syncId", }); 085 086 v = new Vector<String>(2); 087 parameterNames.put("requestMemoryDump", v); 088 Collections.addAll(v, new String[] 089 { "deterministic", "levelOfDetail", }); 090 091 v = new Vector<String>(9); 092 parameterNames.put("start", v); 093 Collections.addAll(v, new String[] 094 { "categories", "options", "bufferUsageReportingInterval", "transferMode", "streamFormat", "streamCompression", "traceConfig", "perfettoConfig", "tracingBackend", }); 095 } 096 097 098 // ******************************************************************************************** 099 // ******************************************************************************************** 100 // Types - Static Inner Classes 101 // ******************************************************************************************** 102 // ******************************************************************************************** 103 104 // public static class MemoryDumpConfig => JsonObject 105 106 /** 107 * Data format of a trace. Can be either the legacy JSON format or the 108 * protocol buffer format. Note that the JSON format will be deprecated soon. 109 */ 110 public static final String[] StreamFormat = 111 { "json", "proto", }; 112 113 /** Compression type to use for traces returned via streams. */ 114 public static final String[] StreamCompression = 115 { "none", "gzip", }; 116 117 /** 118 * Details exposed when memory request explicitly declared. 119 * Keep consistent with memory_dump_request_args.h and 120 * memory_instrumentation.mojom 121 */ 122 public static final String[] MemoryDumpLevelOfDetail = 123 { "background", "light", "detailed", }; 124 125 /** 126 * Backend type to use for tracing. <CODE>chrome</CODE> uses the Chrome-integrated 127 * tracing service and is supported on all platforms. <CODE>system</CODE> is only 128 * supported on Chrome OS and uses the Perfetto system tracing service. 129 * <CODE>auto</CODE> chooses <CODE>system</CODE> when the perfettoConfig provided to Tracing.start 130 * specifies at least one non-Chrome data source; otherwise uses <CODE>chrome</CODE>. 131 */ 132 public static final String[] TracingBackend = 133 { "auto", "chrome", "system", }; 134 135 /** <CODE>[No Description Provided by Google]</CODE> */ 136 public static class TraceConfig 137 extends BaseType 138 implements java.io.Serializable 139 { 140 /** For Object Serialization. java.io.Serializable */ 141 protected static final long serialVersionUID = 1; 142 143 public boolean[] optionals() 144 { return new boolean[] { true, true, true, true, true, true, true, true, }; } 145 146 /** 147 * Controls how the trace buffer stores data. 148 * <BR /> 149 * <BR /><B>OPTIONAL</B> 150 */ 151 public final String recordMode; 152 153 /** 154 * Turns on JavaScript stack sampling. 155 * <BR /> 156 * <BR /><B>OPTIONAL</B> 157 */ 158 public final Boolean enableSampling; 159 160 /** 161 * Turns on system tracing. 162 * <BR /> 163 * <BR /><B>OPTIONAL</B> 164 */ 165 public final Boolean enableSystrace; 166 167 /** 168 * Turns on argument filter. 169 * <BR /> 170 * <BR /><B>OPTIONAL</B> 171 */ 172 public final Boolean enableArgumentFilter; 173 174 /** 175 * Included category filters. 176 * <BR /> 177 * <BR /><B>OPTIONAL</B> 178 */ 179 public final String[] includedCategories; 180 181 /** 182 * Excluded category filters. 183 * <BR /> 184 * <BR /><B>OPTIONAL</B> 185 */ 186 public final String[] excludedCategories; 187 188 /** 189 * Configuration to synthesize the delays in tracing. 190 * <BR /> 191 * <BR /><B>OPTIONAL</B> 192 */ 193 public final String[] syntheticDelays; 194 195 /** 196 * Configuration for memory dump triggers. Used only when "memory-infra" category is enabled. 197 * <BR /> 198 * <BR /><B>OPTIONAL</B> 199 */ 200 public final JsonObject memoryDumpConfig; 201 202 /** 203 * Constructor 204 * 205 * @param recordMode Controls how the trace buffer stores data. 206 * <BR />Acceptable Values: ["recordUntilFull", "recordContinuously", "recordAsMuchAsPossible", "echoToConsole"] 207 * <BR /><B>OPTIONAL</B> 208 * 209 * @param enableSampling Turns on JavaScript stack sampling. 210 * <BR /><B>OPTIONAL</B> 211 * 212 * @param enableSystrace Turns on system tracing. 213 * <BR /><B>OPTIONAL</B> 214 * 215 * @param enableArgumentFilter Turns on argument filter. 216 * <BR /><B>OPTIONAL</B> 217 * 218 * @param includedCategories Included category filters. 219 * <BR /><B>OPTIONAL</B> 220 * 221 * @param excludedCategories Excluded category filters. 222 * <BR /><B>OPTIONAL</B> 223 * 224 * @param syntheticDelays Configuration to synthesize the delays in tracing. 225 * <BR /><B>OPTIONAL</B> 226 * 227 * @param memoryDumpConfig Configuration for memory dump triggers. Used only when "memory-infra" category is enabled. 228 * <BR /><B>OPTIONAL</B> 229 */ 230 public TraceConfig( 231 String recordMode, Boolean enableSampling, Boolean enableSystrace, 232 Boolean enableArgumentFilter, String[] includedCategories, 233 String[] excludedCategories, String[] syntheticDelays, JsonObject memoryDumpConfig 234 ) 235 { 236 // Exception-Check(s) to ensure that if any parameters which must adhere to a 237 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 238 239 BRDPC.checkIAE( 240 "recordMode", recordMode, 241 "recordUntilFull", "recordContinuously", "recordAsMuchAsPossible", "echoToConsole" 242 ); 243 244 this.recordMode = recordMode; 245 this.enableSampling = enableSampling; 246 this.enableSystrace = enableSystrace; 247 this.enableArgumentFilter = enableArgumentFilter; 248 this.includedCategories = includedCategories; 249 this.excludedCategories = excludedCategories; 250 this.syntheticDelays = syntheticDelays; 251 this.memoryDumpConfig = memoryDumpConfig; 252 } 253 254 /** 255 * JSON Object Constructor 256 * @param jo A Json-Object having data about an instance of {@code 'TraceConfig'}. 257 */ 258 public TraceConfig (JsonObject jo) 259 { 260 this.recordMode = ReadJSON.getString(jo, "recordMode", true, false); 261 this.enableSampling = ReadBoxedJSON.getBoolean(jo, "enableSampling", true); 262 this.enableSystrace = ReadBoxedJSON.getBoolean(jo, "enableSystrace", true); 263 this.enableArgumentFilter = ReadBoxedJSON.getBoolean(jo, "enableArgumentFilter", true); 264 this.includedCategories = (jo.getJsonArray("includedCategories") == null) 265 ? null 266 : ReadArrJSON.DimN.strArr(jo.getJsonArray("includedCategories"), null, 0, String[].class); 267 268 this.excludedCategories = (jo.getJsonArray("excludedCategories") == null) 269 ? null 270 : ReadArrJSON.DimN.strArr(jo.getJsonArray("excludedCategories"), null, 0, String[].class); 271 272 this.syntheticDelays = (jo.getJsonArray("syntheticDelays") == null) 273 ? null 274 : ReadArrJSON.DimN.strArr(jo.getJsonArray("syntheticDelays"), null, 0, String[].class); 275 276 this.memoryDumpConfig = jo.getJsonObject("memoryDumpConfig"); 277 } 278 279 280 /** Checks whether {@code 'this'} equals an input Java-{@code Object} */ 281 public boolean equals(Object other) 282 { 283 if (other == null) return false; 284 if (other.getClass() != this.getClass()) return false; 285 286 TraceConfig o = (TraceConfig) other; 287 288 return 289 Objects.equals(this.recordMode, o.recordMode) 290 && Objects.equals(this.enableSampling, o.enableSampling) 291 && Objects.equals(this.enableSystrace, o.enableSystrace) 292 && Objects.equals(this.enableArgumentFilter, o.enableArgumentFilter) 293 && Arrays.deepEquals(this.includedCategories, o.includedCategories) 294 && Arrays.deepEquals(this.excludedCategories, o.excludedCategories) 295 && Arrays.deepEquals(this.syntheticDelays, o.syntheticDelays) 296 && Objects.equals(this.memoryDumpConfig, o.memoryDumpConfig); 297 } 298 299 /** Generates a Hash-Code for {@code 'this'} instance */ 300 public int hashCode() 301 { 302 return 303 Objects.hashCode(this.recordMode) 304 + Objects.hashCode(this.enableSampling) 305 + Objects.hashCode(this.enableSystrace) 306 + Objects.hashCode(this.enableArgumentFilter) 307 + Arrays.deepHashCode(this.includedCategories) 308 + Arrays.deepHashCode(this.excludedCategories) 309 + Arrays.deepHashCode(this.syntheticDelays) 310 + this.memoryDumpConfig.hashCode(); 311 } 312 } 313 314 /** <CODE>[No Description Provided by Google]</CODE> */ 315 public static class bufferUsage 316 extends BrowserEvent 317 implements java.io.Serializable 318 { 319 /** For Object Serialization. java.io.Serializable */ 320 protected static final long serialVersionUID = 1; 321 322 public boolean[] optionals() 323 { return new boolean[] { true, true, true, }; } 324 325 /** 326 * A number in range [0..1] that indicates the used size of event buffer as a fraction of its 327 * total size. 328 * <BR /> 329 * <BR /><B>OPTIONAL</B> 330 */ 331 public final Number percentFull; 332 333 /** 334 * An approximate number of events in the trace log. 335 * <BR /> 336 * <BR /><B>OPTIONAL</B> 337 */ 338 public final Number eventCount; 339 340 /** 341 * A number in range [0..1] that indicates the used size of event buffer as a fraction of its 342 * total size. 343 * <BR /> 344 * <BR /><B>OPTIONAL</B> 345 */ 346 public final Number value; 347 348 /** 349 * Constructor 350 * 351 * @param percentFull 352 * A number in range [0..1] that indicates the used size of event buffer as a fraction of its 353 * total size. 354 * <BR /><B>OPTIONAL</B> 355 * 356 * @param eventCount An approximate number of events in the trace log. 357 * <BR /><B>OPTIONAL</B> 358 * 359 * @param value 360 * A number in range [0..1] that indicates the used size of event buffer as a fraction of its 361 * total size. 362 * <BR /><B>OPTIONAL</B> 363 */ 364 public bufferUsage(Number percentFull, Number eventCount, Number value) 365 { 366 super("Tracing", "bufferUsage", 3); 367 368 this.percentFull = percentFull; 369 this.eventCount = eventCount; 370 this.value = value; 371 } 372 373 /** 374 * JSON Object Constructor 375 * @param jo A Json-Object having data about an instance of {@code 'bufferUsage'}. 376 */ 377 public bufferUsage (JsonObject jo) 378 { 379 super("Tracing", "bufferUsage", 3); 380 381 this.percentFull = ReadNumberJSON.get(jo, "percentFull", true, false); 382 this.eventCount = ReadNumberJSON.get(jo, "eventCount", true, false); 383 this.value = ReadNumberJSON.get(jo, "value", true, false); 384 } 385 386 387 /** Checks whether {@code 'this'} equals an input Java-{@code Object} */ 388 public boolean equals(Object other) 389 { 390 if (other == null) return false; 391 if (other.getClass() != this.getClass()) return false; 392 393 bufferUsage o = (bufferUsage) other; 394 395 return 396 Objects.equals(this.percentFull, o.percentFull) 397 && Objects.equals(this.eventCount, o.eventCount) 398 && Objects.equals(this.value, o.value); 399 } 400 401 /** Generates a Hash-Code for {@code 'this'} instance */ 402 public int hashCode() 403 { 404 return 405 Objects.hashCode(this.percentFull) 406 + Objects.hashCode(this.eventCount) 407 + Objects.hashCode(this.value); 408 } 409 } 410 411 /** 412 * Contains an bucket of collected trace events. When tracing is stopped collected events will be 413 * send as a sequence of dataCollected events followed by tracingComplete event. 414 */ 415 public static class dataCollected 416 extends BrowserEvent 417 implements java.io.Serializable 418 { 419 /** For Object Serialization. java.io.Serializable */ 420 protected static final long serialVersionUID = 1; 421 422 public boolean[] optionals() 423 { return new boolean[] { false, }; } 424 425 /** <CODE>[No Description Provided by Google]</CODE> */ 426 public final JsonArray value; 427 428 /** 429 * Constructor 430 * 431 * @param value - 432 */ 433 public dataCollected(JsonArray value) 434 { 435 super("Tracing", "dataCollected", 1); 436 437 // Exception-Check(s) to ensure that if any parameters which are not declared as 438 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 439 440 if (value == null) BRDPC.throwNPE("value"); 441 442 this.value = value; 443 } 444 445 /** 446 * JSON Object Constructor 447 * @param jo A Json-Object having data about an instance of {@code 'dataCollected'}. 448 */ 449 public dataCollected (JsonObject jo) 450 { 451 super("Tracing", "dataCollected", 1); 452 453 this.value = jo.getJsonArray("value"); 454 } 455 456 457 /** Checks whether {@code 'this'} equals an input Java-{@code Object} */ 458 public boolean equals(Object other) 459 { 460 if (other == null) return false; 461 if (other.getClass() != this.getClass()) return false; 462 463 dataCollected o = (dataCollected) other; 464 465 return 466 Objects.equals(this.value, o.value); 467 } 468 469 /** Generates a Hash-Code for {@code 'this'} instance */ 470 public int hashCode() 471 { 472 return 473 Objects.hashCode(this.value); 474 } 475 } 476 477 /** 478 * Signals that tracing is stopped and there is no trace buffers pending flush, all data were 479 * delivered via dataCollected events. 480 */ 481 public static class tracingComplete 482 extends BrowserEvent 483 implements java.io.Serializable 484 { 485 /** For Object Serialization. java.io.Serializable */ 486 protected static final long serialVersionUID = 1; 487 488 public boolean[] optionals() 489 { return new boolean[] { false, true, true, true, }; } 490 491 /** 492 * Indicates whether some trace data is known to have been lost, e.g. because the trace ring 493 * buffer wrapped around. 494 */ 495 public final boolean dataLossOccurred; 496 497 /** 498 * A handle of the stream that holds resulting trace data. 499 * <BR /> 500 * <BR /><B>OPTIONAL</B> 501 */ 502 public final String stream; 503 504 /** 505 * Trace data format of returned stream. 506 * <BR /> 507 * <BR /><B>OPTIONAL</B> 508 */ 509 public final String traceFormat; 510 511 /** 512 * Compression format of returned stream. 513 * <BR /> 514 * <BR /><B>OPTIONAL</B> 515 */ 516 public final String streamCompression; 517 518 /** 519 * Constructor 520 * 521 * @param dataLossOccurred 522 * Indicates whether some trace data is known to have been lost, e.g. because the trace ring 523 * buffer wrapped around. 524 * 525 * @param stream A handle of the stream that holds resulting trace data. 526 * <BR /><B>OPTIONAL</B> 527 * 528 * @param traceFormat Trace data format of returned stream. 529 * <BR /><B>OPTIONAL</B> 530 * 531 * @param streamCompression Compression format of returned stream. 532 * <BR /><B>OPTIONAL</B> 533 */ 534 public tracingComplete 535 (boolean dataLossOccurred, String stream, String traceFormat, String streamCompression) 536 { 537 super("Tracing", "tracingComplete", 4); 538 539 // Exception-Check(s) to ensure that if any parameters which must adhere to a 540 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 541 542 BRDPC.checkIAE("traceFormat", traceFormat, "Tracing.StreamFormat", Tracing.StreamFormat); 543 BRDPC.checkIAE("streamCompression", streamCompression, "Tracing.StreamCompression", Tracing.StreamCompression); 544 545 this.dataLossOccurred = dataLossOccurred; 546 this.stream = stream; 547 this.traceFormat = traceFormat; 548 this.streamCompression = streamCompression; 549 } 550 551 /** 552 * JSON Object Constructor 553 * @param jo A Json-Object having data about an instance of {@code 'tracingComplete'}. 554 */ 555 public tracingComplete (JsonObject jo) 556 { 557 super("Tracing", "tracingComplete", 4); 558 559 this.dataLossOccurred = ReadPrimJSON.getBoolean(jo, "dataLossOccurred"); 560 this.stream = ReadJSON.getString(jo, "stream", true, false); 561 this.traceFormat = ReadJSON.getString(jo, "traceFormat", true, false); 562 this.streamCompression = ReadJSON.getString(jo, "streamCompression", true, false); 563 } 564 565 566 /** Checks whether {@code 'this'} equals an input Java-{@code Object} */ 567 public boolean equals(Object other) 568 { 569 if (other == null) return false; 570 if (other.getClass() != this.getClass()) return false; 571 572 tracingComplete o = (tracingComplete) other; 573 574 return 575 (this.dataLossOccurred == o.dataLossOccurred) 576 && Objects.equals(this.stream, o.stream) 577 && Objects.equals(this.traceFormat, o.traceFormat) 578 && Objects.equals(this.streamCompression, o.streamCompression); 579 } 580 581 /** Generates a Hash-Code for {@code 'this'} instance */ 582 public int hashCode() 583 { 584 return 585 (this.dataLossOccurred ? 1 : 0) 586 + Objects.hashCode(this.stream) 587 + Objects.hashCode(this.traceFormat) 588 + Objects.hashCode(this.streamCompression); 589 } 590 } 591 592 593 // Counter for keeping the WebSocket Request ID's distinct. 594 private static int counter = 1; 595 596 /** 597 * Stop trace events collection. 598 * 599 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 600 * {@link Ret0}></CODE> 601 * 602 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 603 * browser receives the invocation-request. 604 * 605 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 606 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 607 * {@code >} to ensure the Browser Function has run to completion. 608 */ 609 public static Script<String, JsonObject, Ret0> end() 610 { 611 final int webSocketID = 41000000 + counter++; 612 final boolean[] optionals = new boolean[0]; 613 614 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 615 String requestJSON = WriteJSON.get( 616 parameterTypes.get("end"), 617 parameterNames.get("end"), 618 optionals, webSocketID, 619 "Tracing.end" 620 ); 621 622 // This Remote Command does not have a Return-Value. 623 return new Script<> 624 (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues); 625 } 626 627 /** 628 * Gets supported tracing categories. 629 * 630 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 631 * String[]></CODE> 632 * 633 * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using 634 * {@link Script#exec()}, and afterwards, a {@link Promise}<CODE><JsonObject, 635 * String[]></CODE> will be returned. 636 * 637 * <BR /><BR />Finally, the <B>{@code Promise}</B> may be <B STYLE='color: red'>awaited</B>, 638 * using {@link Promise#await()}, <I>and the returned result of this Browser Function may 639 * may be retrieved.</I> 640 * 641 * <BR /><BR />This Browser Function <B STYLE='color: red'>returns</B> 642 * <BR /><BR /><UL CLASS=JDUL> 643 * <LI><CODE>String[] (<B>categories</B></CODE>) 644 * <BR />A list of supported tracing categories. 645 * </LI> 646 * </UL> */ 647 public static Script<String, JsonObject, String[]> getCategories() 648 { 649 final int webSocketID = 41001000 + counter++; 650 final boolean[] optionals = new boolean[0]; 651 652 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 653 String requestJSON = WriteJSON.get( 654 parameterTypes.get("getCategories"), 655 parameterNames.get("getCategories"), 656 optionals, webSocketID, 657 "Tracing.getCategories" 658 ); 659 660 // 'JSON Binding' ... Converts Browser Response-JSON to 'String[]' 661 Function<JsonObject, String[]> responseProcessor = (JsonObject jo) -> 662 (jo.getJsonArray("categories") == null) 663 ? null 664 : ReadArrJSON.DimN.strArr(jo.getJsonArray("categories"), null, 0, String[].class); 665 666 // Pass the 'defaultSender' to Script-Constructor 667 // The sender that is used can be changed before executing script. 668 return new Script<>(BRDPC.defaultSender, webSocketID, requestJSON, responseProcessor); 669 } 670 671 /** 672 * Record a clock sync marker in the trace. 673 * 674 * @param syncId The ID of this clock sync marker 675 * 676 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 677 * {@link Ret0}></CODE> 678 * 679 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 680 * browser receives the invocation-request. 681 * 682 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 683 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 684 * {@code >} to ensure the Browser Function has run to completion. 685 */ 686 public static Script<String, JsonObject, Ret0> recordClockSyncMarker(String syncId) 687 { 688 // Exception-Check(s) to ensure that if any parameters which are not declared as 689 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 690 691 if (syncId == null) BRDPC.throwNPE("syncId"); 692 693 final int webSocketID = 41002000 + counter++; 694 final boolean[] optionals = { false, }; 695 696 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 697 String requestJSON = WriteJSON.get( 698 parameterTypes.get("recordClockSyncMarker"), 699 parameterNames.get("recordClockSyncMarker"), 700 optionals, webSocketID, 701 "Tracing.recordClockSyncMarker", 702 syncId 703 ); 704 705 // This Remote Command does not have a Return-Value. 706 return new Script<> 707 (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues); 708 } 709 710 /** 711 * Request a global memory dump. 712 * 713 * @param deterministic Enables more deterministic results by forcing garbage collection 714 * <BR /><B>OPTIONAL</B> 715 * 716 * @param levelOfDetail Specifies level of details in memory dump. Defaults to "detailed". 717 * <BR /><B>OPTIONAL</B> 718 * 719 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 720 * {@link Ret2}></CODE> 721 * 722 * <BR /><BR />This {@link Script} may be <B STYLE='color:red'>executed</B> (using 723 * {@link Script#exec()}), and a {@link Promise} returned. 724 * 725 * <BR /><BR />When the {@code Promise} is <B STYLE='color: red'>awaited</B> 726 * (using {@link Promise#await()}), the {@code Ret2} will subsequently 727 * be returned from that call. 728 * 729 * <BR /><BR />The <B STYLE='color: red'>returned</B> values are encapsulated 730 * in an instance of <B>{@link Ret2}</B> 731 * 732 * <BR /><BR /><UL CLASS=JDUL> 733 * <LI><CODE><B>Ret2.a:</B> String (<B>dumpGuid</B>)</CODE> 734 * <BR />GUID of the resulting global memory dump. 735 * <BR /><BR /></LI> 736 * <LI><CODE><B>Ret2.b:</B> Boolean (<B>success</B>)</CODE> 737 * <BR />True iff the global memory dump succeeded. 738 * </LI> 739 * </UL> 740 */ 741 public static Script<String, JsonObject, Ret2<String, Boolean>> requestMemoryDump 742 (Boolean deterministic, String levelOfDetail) 743 { 744 // Exception-Check(s) to ensure that if any parameters which must adhere to a 745 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 746 747 BRDPC.checkIAE("levelOfDetail", levelOfDetail, "Tracing.MemoryDumpLevelOfDetail", Tracing.MemoryDumpLevelOfDetail); 748 749 final int webSocketID = 41003000 + counter++; 750 final boolean[] optionals = { true, true, }; 751 752 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 753 String requestJSON = WriteJSON.get( 754 parameterTypes.get("requestMemoryDump"), 755 parameterNames.get("requestMemoryDump"), 756 optionals, webSocketID, 757 "Tracing.requestMemoryDump", 758 deterministic, levelOfDetail 759 ); 760 761 // 'JSON Binding' ... Converts Browser Response-JSON into Java-Type 'Ret2' 762 Function<JsonObject, Ret2<String, Boolean>> 763 responseProcessor = (JsonObject jo) -> new Ret2<>( 764 ReadJSON.getString(jo, "dumpGuid", false, true), 765 ReadBoxedJSON.getBoolean(jo, "success", true) 766 ); 767 768 // Pass the 'defaultSender' to Script-Constructor 769 // The sender that is used can be changed before executing script. 770 return new Script<>(BRDPC.defaultSender, webSocketID, requestJSON, responseProcessor); 771 } 772 773 /** 774 * Start trace events collection. 775 * 776 * @param categories Category/tag filter 777 * <BR /><B>OPTIONAL</B> 778 * <BR /><B>DEPRECATED</B> 779 * 780 * @param options Tracing options 781 * <BR /><B>OPTIONAL</B> 782 * <BR /><B>DEPRECATED</B> 783 * 784 * @param bufferUsageReportingInterval If set, the agent will issue bufferUsage events at this interval, specified in milliseconds 785 * <BR /><B>OPTIONAL</B> 786 * 787 * @param transferMode 788 * Whether to report trace events as series of dataCollected events or to save trace to a 789 * stream (defaults to <CODE>ReportEvents</CODE>). 790 * <BR />Acceptable Values: ["ReportEvents", "ReturnAsStream"] 791 * <BR /><B>OPTIONAL</B> 792 * 793 * @param streamFormat 794 * Trace data format to use. This only applies when using <CODE>ReturnAsStream</CODE> 795 * transfer mode (defaults to <CODE>json</CODE>). 796 * <BR /><B>OPTIONAL</B> 797 * 798 * @param streamCompression 799 * Compression format to use. This only applies when using <CODE>ReturnAsStream</CODE> 800 * transfer mode (defaults to <CODE>none</CODE>) 801 * <BR /><B>OPTIONAL</B> 802 * 803 * @param traceConfig - 804 * <BR /><B>OPTIONAL</B> 805 * 806 * @param perfettoConfig 807 * Base64-encoded serialized perfetto.protos.TraceConfig protobuf message 808 * When specified, the parameters <CODE>categories</CODE>, <CODE>options</CODE>, <CODE>traceConfig</CODE> 809 * are ignored. (Encoded as a base64 string when passed over JSON) 810 * <BR /><B>OPTIONAL</B> 811 * 812 * @param tracingBackend Backend type (defaults to <CODE>auto</CODE>) 813 * <BR /><B>OPTIONAL</B> 814 * 815 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 816 * {@link Ret0}></CODE> 817 * 818 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 819 * browser receives the invocation-request. 820 * 821 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 822 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 823 * {@code >} to ensure the Browser Function has run to completion. 824 */ 825 public static Script<String, JsonObject, Ret0> start( 826 String categories, String options, Number bufferUsageReportingInterval, 827 String transferMode, String streamFormat, String streamCompression, 828 Tracing.TraceConfig traceConfig, String perfettoConfig, String tracingBackend 829 ) 830 { 831 // Exception-Check(s) to ensure that if any parameters which must adhere to a 832 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 833 834 BRDPC.checkIAE( 835 "transferMode", transferMode, 836 "ReportEvents", "ReturnAsStream" 837 ); 838 BRDPC.checkIAE("streamFormat", streamFormat, "Tracing.StreamFormat", Tracing.StreamFormat); 839 BRDPC.checkIAE("streamCompression", streamCompression, "Tracing.StreamCompression", Tracing.StreamCompression); 840 BRDPC.checkIAE("tracingBackend", tracingBackend, "Tracing.TracingBackend", Tracing.TracingBackend); 841 842 final int webSocketID = 41004000 + counter++; 843 final boolean[] optionals = { true, true, true, true, true, true, true, true, true, }; 844 845 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 846 String requestJSON = WriteJSON.get( 847 parameterTypes.get("start"), 848 parameterNames.get("start"), 849 optionals, webSocketID, 850 "Tracing.start", 851 categories, options, bufferUsageReportingInterval, transferMode, streamFormat, 852 streamCompression, traceConfig, perfettoConfig, tracingBackend 853 ); 854 855 // This Remote Command does not have a Return-Value. 856 return new Script<> 857 (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues); 858 } 859 860}