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 THROWS.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 : RJArrIntoStream.strArr(jo.getJsonArray("includedCategories"), null, 0).toArray(String[]::new); 267 268 this.excludedCategories = (jo.getJsonArray("excludedCategories") == null) 269 ? null 270 : RJArrIntoStream.strArr(jo.getJsonArray("excludedCategories"), null, 0).toArray(String[]::new); 271 272 this.syntheticDelays = (jo.getJsonArray("syntheticDelays") == null) 273 ? null 274 : RJArrIntoStream.strArr(jo.getJsonArray("syntheticDelays"), null, 0).toArray(String[]::new); 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 (this == other) return true; 284 if (other == null) return false; 285 if (other.getClass() != this.getClass()) return false; 286 287 TraceConfig o = (TraceConfig) other; 288 289 return 290 Objects.equals(this.recordMode, o.recordMode) 291 && Objects.equals(this.enableSampling, o.enableSampling) 292 && Objects.equals(this.enableSystrace, o.enableSystrace) 293 && Objects.equals(this.enableArgumentFilter, o.enableArgumentFilter) 294 && Arrays.deepEquals(this.includedCategories, o.includedCategories) 295 && Arrays.deepEquals(this.excludedCategories, o.excludedCategories) 296 && Arrays.deepEquals(this.syntheticDelays, o.syntheticDelays) 297 && Objects.equals(this.memoryDumpConfig, o.memoryDumpConfig); 298 } 299 300 /** Generates a Hash-Code for {@code 'this'} instance */ 301 public int hashCode() 302 { 303 return 304 Objects.hashCode(this.recordMode) 305 + Objects.hashCode(this.enableSampling) 306 + Objects.hashCode(this.enableSystrace) 307 + Objects.hashCode(this.enableArgumentFilter) 308 + Arrays.deepHashCode(this.includedCategories) 309 + Arrays.deepHashCode(this.excludedCategories) 310 + Arrays.deepHashCode(this.syntheticDelays) 311 + this.memoryDumpConfig.hashCode(); 312 } 313 } 314 315 /** <CODE>[No Description Provided by Google]</CODE> */ 316 public static class bufferUsage 317 extends BrowserEvent 318 implements java.io.Serializable 319 { 320 /** For Object Serialization. java.io.Serializable */ 321 protected static final long serialVersionUID = 1; 322 323 public boolean[] optionals() 324 { return new boolean[] { true, true, true, }; } 325 326 /** 327 * A number in range [0..1] that indicates the used size of event buffer as a fraction of its 328 * total size. 329 * <BR /> 330 * <BR /><B>OPTIONAL</B> 331 */ 332 public final Number percentFull; 333 334 /** 335 * An approximate number of events in the trace log. 336 * <BR /> 337 * <BR /><B>OPTIONAL</B> 338 */ 339 public final Number eventCount; 340 341 /** 342 * A number in range [0..1] that indicates the used size of event buffer as a fraction of its 343 * total size. 344 * <BR /> 345 * <BR /><B>OPTIONAL</B> 346 */ 347 public final Number value; 348 349 /** 350 * Constructor 351 * 352 * @param percentFull 353 * A number in range [0..1] that indicates the used size of event buffer as a fraction of its 354 * total size. 355 * <BR /><B>OPTIONAL</B> 356 * 357 * @param eventCount An approximate number of events in the trace log. 358 * <BR /><B>OPTIONAL</B> 359 * 360 * @param value 361 * A number in range [0..1] that indicates the used size of event buffer as a fraction of its 362 * total size. 363 * <BR /><B>OPTIONAL</B> 364 */ 365 public bufferUsage(Number percentFull, Number eventCount, Number value) 366 { 367 super("Tracing", "bufferUsage", 3); 368 369 this.percentFull = percentFull; 370 this.eventCount = eventCount; 371 this.value = value; 372 } 373 374 /** 375 * JSON Object Constructor 376 * @param jo A Json-Object having data about an instance of {@code 'bufferUsage'}. 377 */ 378 public bufferUsage (JsonObject jo) 379 { 380 super("Tracing", "bufferUsage", 3); 381 382 this.percentFull = ReadNumberJSON.get(jo, "percentFull", true, false); 383 this.eventCount = ReadNumberJSON.get(jo, "eventCount", true, false); 384 this.value = ReadNumberJSON.get(jo, "value", true, false); 385 } 386 387 388 /** Checks whether {@code 'this'} equals an input Java-{@code Object} */ 389 public boolean equals(Object other) 390 { 391 if (this == other) return true; 392 if (other == null) return false; 393 if (other.getClass() != this.getClass()) return false; 394 395 bufferUsage o = (bufferUsage) other; 396 397 return 398 Objects.equals(this.percentFull, o.percentFull) 399 && Objects.equals(this.eventCount, o.eventCount) 400 && Objects.equals(this.value, o.value); 401 } 402 403 /** Generates a Hash-Code for {@code 'this'} instance */ 404 public int hashCode() 405 { 406 return 407 Objects.hashCode(this.percentFull) 408 + Objects.hashCode(this.eventCount) 409 + Objects.hashCode(this.value); 410 } 411 } 412 413 /** 414 * Contains an bucket of collected trace events. When tracing is stopped collected events will be 415 * send as a sequence of dataCollected events followed by tracingComplete event. 416 */ 417 public static class dataCollected 418 extends BrowserEvent 419 implements java.io.Serializable 420 { 421 /** For Object Serialization. java.io.Serializable */ 422 protected static final long serialVersionUID = 1; 423 424 public boolean[] optionals() 425 { return new boolean[] { false, }; } 426 427 /** <CODE>[No Description Provided by Google]</CODE> */ 428 public final JsonArray value; 429 430 /** 431 * Constructor 432 * 433 * @param value - 434 */ 435 public dataCollected(JsonArray value) 436 { 437 super("Tracing", "dataCollected", 1); 438 439 // Exception-Check(s) to ensure that if any parameters which are not declared as 440 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 441 442 if (value == null) THROWS.throwNPE("value"); 443 444 this.value = value; 445 } 446 447 /** 448 * JSON Object Constructor 449 * @param jo A Json-Object having data about an instance of {@code 'dataCollected'}. 450 */ 451 public dataCollected (JsonObject jo) 452 { 453 super("Tracing", "dataCollected", 1); 454 455 this.value = jo.getJsonArray("value"); 456 } 457 458 459 /** Checks whether {@code 'this'} equals an input Java-{@code Object} */ 460 public boolean equals(Object other) 461 { 462 if (this == other) return true; 463 if (other == null) return false; 464 if (other.getClass() != this.getClass()) return false; 465 466 dataCollected o = (dataCollected) other; 467 468 return 469 Objects.equals(this.value, o.value); 470 } 471 472 /** Generates a Hash-Code for {@code 'this'} instance */ 473 public int hashCode() 474 { 475 return 476 Objects.hashCode(this.value); 477 } 478 } 479 480 /** 481 * Signals that tracing is stopped and there is no trace buffers pending flush, all data were 482 * delivered via dataCollected events. 483 */ 484 public static class tracingComplete 485 extends BrowserEvent 486 implements java.io.Serializable 487 { 488 /** For Object Serialization. java.io.Serializable */ 489 protected static final long serialVersionUID = 1; 490 491 public boolean[] optionals() 492 { return new boolean[] { false, true, true, true, }; } 493 494 /** 495 * Indicates whether some trace data is known to have been lost, e.g. because the trace ring 496 * buffer wrapped around. 497 */ 498 public final boolean dataLossOccurred; 499 500 /** 501 * A handle of the stream that holds resulting trace data. 502 * <BR /> 503 * <BR /><B>OPTIONAL</B> 504 */ 505 public final String stream; 506 507 /** 508 * Trace data format of returned stream. 509 * <BR /> 510 * <BR /><B>OPTIONAL</B> 511 */ 512 public final String traceFormat; 513 514 /** 515 * Compression format of returned stream. 516 * <BR /> 517 * <BR /><B>OPTIONAL</B> 518 */ 519 public final String streamCompression; 520 521 /** 522 * Constructor 523 * 524 * @param dataLossOccurred 525 * Indicates whether some trace data is known to have been lost, e.g. because the trace ring 526 * buffer wrapped around. 527 * 528 * @param stream A handle of the stream that holds resulting trace data. 529 * <BR /><B>OPTIONAL</B> 530 * 531 * @param traceFormat Trace data format of returned stream. 532 * <BR /><B>OPTIONAL</B> 533 * 534 * @param streamCompression Compression format of returned stream. 535 * <BR /><B>OPTIONAL</B> 536 */ 537 public tracingComplete 538 (boolean dataLossOccurred, String stream, String traceFormat, String streamCompression) 539 { 540 super("Tracing", "tracingComplete", 4); 541 542 // Exception-Check(s) to ensure that if any parameters which must adhere to a 543 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 544 545 THROWS.checkIAE("traceFormat", traceFormat, "Tracing.StreamFormat", Tracing.StreamFormat); 546 THROWS.checkIAE("streamCompression", streamCompression, "Tracing.StreamCompression", Tracing.StreamCompression); 547 548 this.dataLossOccurred = dataLossOccurred; 549 this.stream = stream; 550 this.traceFormat = traceFormat; 551 this.streamCompression = streamCompression; 552 } 553 554 /** 555 * JSON Object Constructor 556 * @param jo A Json-Object having data about an instance of {@code 'tracingComplete'}. 557 */ 558 public tracingComplete (JsonObject jo) 559 { 560 super("Tracing", "tracingComplete", 4); 561 562 this.dataLossOccurred = ReadPrimJSON.getBoolean(jo, "dataLossOccurred"); 563 this.stream = ReadJSON.getString(jo, "stream", true, false); 564 this.traceFormat = ReadJSON.getString(jo, "traceFormat", true, false); 565 this.streamCompression = ReadJSON.getString(jo, "streamCompression", true, false); 566 } 567 568 569 /** Checks whether {@code 'this'} equals an input Java-{@code Object} */ 570 public boolean equals(Object other) 571 { 572 if (this == other) return true; 573 if (other == null) return false; 574 if (other.getClass() != this.getClass()) return false; 575 576 tracingComplete o = (tracingComplete) other; 577 578 return 579 (this.dataLossOccurred == o.dataLossOccurred) 580 && Objects.equals(this.stream, o.stream) 581 && Objects.equals(this.traceFormat, o.traceFormat) 582 && Objects.equals(this.streamCompression, o.streamCompression); 583 } 584 585 /** Generates a Hash-Code for {@code 'this'} instance */ 586 public int hashCode() 587 { 588 return 589 (this.dataLossOccurred ? 1 : 0) 590 + Objects.hashCode(this.stream) 591 + Objects.hashCode(this.traceFormat) 592 + Objects.hashCode(this.streamCompression); 593 } 594 } 595 596 597 // Counter for keeping the WebSocket Request ID's distinct. 598 private static int counter = 1; 599 600 /** 601 * Stop trace events collection. 602 * 603 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 604 * {@link Ret0}></CODE> 605 * 606 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 607 * browser receives the invocation-request. 608 * 609 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 610 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 611 * {@code >} to ensure the Browser Function has run to completion. 612 */ 613 public static Script<String, JsonObject, Ret0> end() 614 { 615 final int webSocketID = 41000000 + counter++; 616 final boolean[] optionals = new boolean[0]; 617 618 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 619 String requestJSON = WriteJSON.get( 620 parameterTypes.get("end"), 621 parameterNames.get("end"), 622 optionals, webSocketID, 623 "Tracing.end" 624 ); 625 626 // This Remote Command does not have a Return-Value. 627 return new Script<> 628 (webSocketID, requestJSON, VOID_RETURN.NoReturnValues); 629 } 630 631 /** 632 * Gets supported tracing categories. 633 * 634 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 635 * String[]></CODE> 636 * 637 * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using 638 * {@link Script#exec()}, and afterwards, a {@link Promise}<CODE><JsonObject, 639 * String[]></CODE> will be returned. 640 * 641 * <BR /><BR />Finally, the <B>{@code Promise}</B> may be <B STYLE='color: red'>awaited</B>, 642 * using {@link Promise#await()}, <I>and the returned result of this Browser Function may 643 * may be retrieved.</I> 644 * 645 * <BR /><BR />This Browser Function <B STYLE='color: red'>returns</B> 646 * <BR /><BR /><UL CLASS=JDUL> 647 * <LI><CODE>String[] (<B>categories</B></CODE>) 648 * <BR />A list of supported tracing categories. 649 * </LI> 650 * </UL> */ 651 public static Script<String, JsonObject, String[]> getCategories() 652 { 653 final int webSocketID = 41001000 + counter++; 654 final boolean[] optionals = new boolean[0]; 655 656 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 657 String requestJSON = WriteJSON.get( 658 parameterTypes.get("getCategories"), 659 parameterNames.get("getCategories"), 660 optionals, webSocketID, 661 "Tracing.getCategories" 662 ); 663 664 // 'JSON Binding' ... Converts Browser Response-JSON to 'String[]' 665 Function<JsonObject, String[]> responseProcessor = (JsonObject jo) -> 666 (jo.getJsonArray("categories") == null) 667 ? null 668 : RJArrIntoStream.strArr(jo.getJsonArray("categories"), null, 0).toArray(String[]::new); 669 670 return new Script<>(webSocketID, requestJSON, responseProcessor); 671 } 672 673 /** 674 * Record a clock sync marker in the trace. 675 * 676 * @param syncId The ID of this clock sync marker 677 * 678 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 679 * {@link Ret0}></CODE> 680 * 681 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 682 * browser receives the invocation-request. 683 * 684 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 685 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 686 * {@code >} to ensure the Browser Function has run to completion. 687 */ 688 public static Script<String, JsonObject, Ret0> recordClockSyncMarker(String syncId) 689 { 690 // Exception-Check(s) to ensure that if any parameters which are not declared as 691 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 692 693 if (syncId == null) THROWS.throwNPE("syncId"); 694 695 final int webSocketID = 41002000 + counter++; 696 final boolean[] optionals = { false, }; 697 698 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 699 String requestJSON = WriteJSON.get( 700 parameterTypes.get("recordClockSyncMarker"), 701 parameterNames.get("recordClockSyncMarker"), 702 optionals, webSocketID, 703 "Tracing.recordClockSyncMarker", 704 syncId 705 ); 706 707 // This Remote Command does not have a Return-Value. 708 return new Script<> 709 (webSocketID, requestJSON, VOID_RETURN.NoReturnValues); 710 } 711 712 /** 713 * Request a global memory dump. 714 * 715 * @param deterministic Enables more deterministic results by forcing garbage collection 716 * <BR /><B>OPTIONAL</B> 717 * 718 * @param levelOfDetail Specifies level of details in memory dump. Defaults to "detailed". 719 * <BR /><B>OPTIONAL</B> 720 * 721 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 722 * {@link Ret2}></CODE> 723 * 724 * <BR /><BR />This {@link Script} may be <B STYLE='color:red'>executed</B> (using 725 * {@link Script#exec()}), and a {@link Promise} returned. 726 * 727 * <BR /><BR />When the {@code Promise} is <B STYLE='color: red'>awaited</B> 728 * (using {@link Promise#await()}), the {@code Ret2} will subsequently 729 * be returned from that call. 730 * 731 * <BR /><BR />The <B STYLE='color: red'>returned</B> values are encapsulated 732 * in an instance of <B>{@link Ret2}</B> 733 * 734 * <BR /><BR /><UL CLASS=JDUL> 735 * <LI><CODE><B>Ret2.a:</B> String (<B>dumpGuid</B>)</CODE> 736 * <BR />GUID of the resulting global memory dump. 737 * <BR /><BR /></LI> 738 * <LI><CODE><B>Ret2.b:</B> Boolean (<B>success</B>)</CODE> 739 * <BR />True iff the global memory dump succeeded. 740 * </LI> 741 * </UL> 742 */ 743 public static Script<String, JsonObject, Ret2<String, Boolean>> requestMemoryDump 744 (Boolean deterministic, String levelOfDetail) 745 { 746 // Exception-Check(s) to ensure that if any parameters which must adhere to a 747 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 748 749 THROWS.checkIAE("levelOfDetail", levelOfDetail, "Tracing.MemoryDumpLevelOfDetail", Tracing.MemoryDumpLevelOfDetail); 750 751 final int webSocketID = 41003000 + counter++; 752 final boolean[] optionals = { true, true, }; 753 754 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 755 String requestJSON = WriteJSON.get( 756 parameterTypes.get("requestMemoryDump"), 757 parameterNames.get("requestMemoryDump"), 758 optionals, webSocketID, 759 "Tracing.requestMemoryDump", 760 deterministic, levelOfDetail 761 ); 762 763 // 'JSON Binding' ... Converts Browser Response-JSON into Java-Type 'Ret2' 764 Function<JsonObject, Ret2<String, Boolean>> 765 responseProcessor = (JsonObject jo) -> new Ret2<>( 766 ReadJSON.getString(jo, "dumpGuid", false, true), 767 ReadBoxedJSON.getBoolean(jo, "success", true) 768 ); 769 770 return new Script<>(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 THROWS.checkIAE( 835 "transferMode", transferMode, 836 "ReportEvents", "ReturnAsStream" 837 ); 838 THROWS.checkIAE("streamFormat", streamFormat, "Tracing.StreamFormat", Tracing.StreamFormat); 839 THROWS.checkIAE("streamCompression", streamCompression, "Tracing.StreamCompression", Tracing.StreamCompression); 840 THROWS.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 (webSocketID, requestJSON, VOID_RETURN.NoReturnValues); 858 } 859 860}