001package Torello.Browser.BrowserAPI; 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.Browser.BrowserEvent; 013import Torello.Browser.JavaScriptAPI.*; 014import Torello.Browser.helper.*; 015 016import Torello.Java.Additional.*; 017import Torello.Java.JSON.*; 018 019import static Torello.Java.JSON.JFlag.*; 020 021import Torello.Java.StrCmpr; 022import Torello.JavaDoc.StaticFunctional; 023import Torello.JavaDoc.JDHeaderBackgroundImg; 024import Torello.JavaDoc.Excuse; 025 026/** 027 * <SPAN CLASS=COPIEDJDK><B>The Browser domain defines methods and events for browser managing.</B></SPAN> 028 * 029 * <EMBED CLASS='external-html' DATA-FILE-ID=CODE_GEN_NOTE> 030 */ 031@StaticFunctional(Excused={"counter"}, Excuses={Excuse.CONFIGURATION}) 032@JDHeaderBackgroundImg(EmbedTagFileID="WOOD_PLANK_NOTE") 033public class Browser 034{ 035 // ******************************************************************************************** 036 // ******************************************************************************************** 037 // Class Header Stuff 038 // ******************************************************************************************** 039 // ******************************************************************************************** 040 041 042 // No Pubic Constructors 043 private Browser () { } 044 045 // These two Vector's are used by all the "Methods" exported by this class. java.lang.reflect 046 // is used to generate the JSON String's. It saves thousands of lines of Auto-Generated Code. 047 private static final Map<String, Vector<String>> parameterNames = new HashMap<>(); 048 private static final Map<String, Vector<Class<?>>> parameterTypes = new HashMap<>(); 049 050 // Some Methods do not take any parameters - for instance all the "enable()" and "disable()" 051 // I simply could not get ride of RAW-TYPES and UNCHECKED warnings... so there are now, 052 // offically, two empty-vectors. One for String's, and the other for Classes. 053 054 private static final Vector<String> EMPTY_VEC_STR = new Vector<>(); 055 private static final Vector<Class<?>> EMPTY_VEC_CLASS = new Vector<>(); 056 057 static 058 { 059 for (Method m : Browser.class.getMethods()) 060 { 061 // This doesn't work! The parameter names are all "arg0" ... "argN" 062 // It works for java.lang.reflect.Field, BUT NOT java.lang.reflect.Parameter! 063 // 064 // Vector<String> parameterNamesList = new Vector<>(); -- NOPE! 065 066 Vector<Class<?>> parameterTypesList = new Vector<>(); 067 068 for (Parameter p : m.getParameters()) parameterTypesList.add(p.getType()); 069 070 parameterTypes.put( 071 m.getName(), 072 (parameterTypesList.size() > 0) ? parameterTypesList : EMPTY_VEC_CLASS 073 ); 074 } 075 } 076 077 static 078 { 079 Vector<String> v = null; 080 081 v = new Vector<String>(4); 082 parameterNames.put("setPermission", v); 083 Collections.addAll(v, new String[] 084 { "permission", "setting", "origin", "browserContextId", }); 085 086 v = new Vector<String>(3); 087 parameterNames.put("grantPermissions", v); 088 Collections.addAll(v, new String[] 089 { "permissions", "origin", "browserContextId", }); 090 091 v = new Vector<String>(1); 092 parameterNames.put("resetPermissions", v); 093 Collections.addAll(v, new String[] 094 { "browserContextId", }); 095 096 v = new Vector<String>(4); 097 parameterNames.put("setDownloadBehavior", v); 098 Collections.addAll(v, new String[] 099 { "behavior", "browserContextId", "downloadPath", "eventsEnabled", }); 100 101 v = new Vector<String>(2); 102 parameterNames.put("cancelDownload", v); 103 Collections.addAll(v, new String[] 104 { "guid", "browserContextId", }); 105 106 parameterNames.put("close", EMPTY_VEC_STR); 107 108 parameterNames.put("crash", EMPTY_VEC_STR); 109 110 parameterNames.put("crashGpuProcess", EMPTY_VEC_STR); 111 112 parameterNames.put("getVersion", EMPTY_VEC_STR); 113 114 parameterNames.put("getBrowserCommandLine", EMPTY_VEC_STR); 115 116 v = new Vector<String>(2); 117 parameterNames.put("getHistograms", v); 118 Collections.addAll(v, new String[] 119 { "query", "delta", }); 120 121 v = new Vector<String>(2); 122 parameterNames.put("getHistogram", v); 123 Collections.addAll(v, new String[] 124 { "name", "delta", }); 125 126 v = new Vector<String>(1); 127 parameterNames.put("getWindowBounds", v); 128 Collections.addAll(v, new String[] 129 { "windowId", }); 130 131 v = new Vector<String>(1); 132 parameterNames.put("getWindowForTarget", v); 133 Collections.addAll(v, new String[] 134 { "targetId", }); 135 136 v = new Vector<String>(2); 137 parameterNames.put("setWindowBounds", v); 138 Collections.addAll(v, new String[] 139 { "windowId", "bounds", }); 140 141 v = new Vector<String>(3); 142 parameterNames.put("setContentsSize", v); 143 Collections.addAll(v, new String[] 144 { "windowId", "width", "height", }); 145 146 v = new Vector<String>(2); 147 parameterNames.put("setDockTile", v); 148 Collections.addAll(v, new String[] 149 { "badgeLabel", "image", }); 150 151 v = new Vector<String>(1); 152 parameterNames.put("executeBrowserCommand", v); 153 Collections.addAll(v, new String[] 154 { "commandId", }); 155 156 v = new Vector<String>(1); 157 parameterNames.put("addPrivacySandboxEnrollmentOverride", v); 158 Collections.addAll(v, new String[] 159 { "url", }); 160 161 v = new Vector<String>(4); 162 parameterNames.put("addPrivacySandboxCoordinatorKeyConfig", v); 163 Collections.addAll(v, new String[] 164 { "api", "coordinatorOrigin", "keyConfig", "browserContextId", }); 165 } 166 167 168 // ******************************************************************************************** 169 // ******************************************************************************************** 170 // Types - Static Inner Classes 171 // ******************************************************************************************** 172 // ******************************************************************************************** 173 174 // public static class BrowserContextID => String 175 176 // public static class WindowID => Integer 177 178 /** 179 * The state of the browser window. 180 * <BR /><B CLASS=Exp>EXPERIMENTAL</B> 181 */ 182 public static final String[] WindowState = 183 { "normal", "minimized", "maximized", "fullscreen", }; 184 185 /** 186 * <CODE>[No Description Provided by Google]</CODE> 187 * <BR /><B CLASS=Exp>EXPERIMENTAL</B> 188 */ 189 public static final String[] PermissionType = 190 { 191 "ar", "audioCapture", "automaticFullscreen", "backgroundFetch", "backgroundSync", 192 "cameraPanTiltZoom", "capturedSurfaceControl", "clipboardReadWrite", 193 "clipboardSanitizedWrite", "displayCapture", "durableStorage", "geolocation", 194 "handTracking", "idleDetection", "keyboardLock", "localFonts", "localNetworkAccess", 195 "midi", "midiSysex", "nfc", "notifications", "paymentHandler", "periodicBackgroundSync", 196 "pointerLock", "protectedMediaIdentifier", "sensors", "smartCard", "speakerSelection", 197 "storageAccess", "topLevelStorageAccess", "videoCapture", "vr", "wakeLockScreen", 198 "wakeLockSystem", "webAppInstallation", "webPrinting", "windowManagement", 199 }; 200 201 /** 202 * <CODE>[No Description Provided by Google]</CODE> 203 * <BR /><B CLASS=Exp>EXPERIMENTAL</B> 204 */ 205 public static final String[] PermissionSetting = 206 { "granted", "denied", "prompt", }; 207 208 /** 209 * Browser command ids used by executeBrowserCommand. 210 * <BR /><B CLASS=Exp>EXPERIMENTAL</B> 211 */ 212 public static final String[] BrowserCommandId = 213 { "openTabSearch", "closeTabSearch", "openGlic", }; 214 215 /** 216 * <CODE>[No Description Provided by Google]</CODE> 217 * <BR /><B CLASS=Exp>EXPERIMENTAL</B> 218 */ 219 public static final String[] PrivacySandboxAPI = 220 { "BiddingAndAuctionServices", "TrustedKeyValue", }; 221 222 /** 223 * Browser window bounds information 224 * <BR /><B CLASS=Exp>EXPERIMENTAL</B> 225 */ 226 public static class Bounds 227 extends BaseType 228 implements java.io.Serializable 229 { 230 /** For Object Serialization. java.io.Serializable */ 231 protected static final long serialVersionUID = 1; 232 233 public boolean[] optionals() 234 { return new boolean[] { true, true, true, true, true, }; } 235 236 /** 237 * The offset from the left edge of the screen to the window in pixels. 238 * <BR /><B CLASS=Opt>OPTIONAL</B> 239 */ 240 public final Integer left; 241 242 /** 243 * The offset from the top edge of the screen to the window in pixels. 244 * <BR /><B CLASS=Opt>OPTIONAL</B> 245 */ 246 public final Integer top; 247 248 /** 249 * The window width in pixels. 250 * <BR /><B CLASS=Opt>OPTIONAL</B> 251 */ 252 public final Integer width; 253 254 /** 255 * The window height in pixels. 256 * <BR /><B CLASS=Opt>OPTIONAL</B> 257 */ 258 public final Integer height; 259 260 /** 261 * The window state. Default to normal. 262 * <BR /><B CLASS=Opt>OPTIONAL</B> 263 */ 264 public final String windowState; 265 266 /** 267 * Constructor 268 * 269 * @param left The offset from the left edge of the screen to the window in pixels. 270 * <BR /><B CLASS=Opt>OPTIONAL</B> 271 * 272 * @param top The offset from the top edge of the screen to the window in pixels. 273 * <BR /><B CLASS=Opt>OPTIONAL</B> 274 * 275 * @param width The window width in pixels. 276 * <BR /><B CLASS=Opt>OPTIONAL</B> 277 * 278 * @param height The window height in pixels. 279 * <BR /><B CLASS=Opt>OPTIONAL</B> 280 * 281 * @param windowState The window state. Default to normal. 282 * <BR /><B CLASS=Opt>OPTIONAL</B> 283 */ 284 public Bounds 285 (Integer left, Integer top, Integer width, Integer height, String windowState) 286 { 287 // Exception-Check(s) to ensure that if any parameters which must adhere to a 288 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 289 290 THROWS.checkIAE("windowState", windowState, "Browser.WindowState", Browser.WindowState); 291 292 this.left = left; 293 this.top = top; 294 this.width = width; 295 this.height = height; 296 this.windowState = windowState; 297 } 298 299 /** 300 * JSON Object Constructor 301 * @param jo A Json-Object having data about an instance of {@code 'Bounds'}. 302 */ 303 public Bounds (JsonObject jo) 304 { 305 this.left = ReadBoxedJSON.getInteger(jo, "left", true); 306 this.top = ReadBoxedJSON.getInteger(jo, "top", true); 307 this.width = ReadBoxedJSON.getInteger(jo, "width", true); 308 this.height = ReadBoxedJSON.getInteger(jo, "height", true); 309 this.windowState = ReadJSON.getString(jo, "windowState", true, false); 310 } 311 312 313 /** Checks whether {@code 'this'} equals an input Java-{@code Object} */ 314 public boolean equals(Object other) 315 { 316 if (this == other) return true; 317 if (other == null) return false; 318 if (other.getClass() != this.getClass()) return false; 319 320 Bounds o = (Bounds) other; 321 322 return 323 Objects.equals(this.left, o.left) 324 && Objects.equals(this.top, o.top) 325 && Objects.equals(this.width, o.width) 326 && Objects.equals(this.height, o.height) 327 && Objects.equals(this.windowState, o.windowState); 328 } 329 330 /** Generates a Hash-Code for {@code 'this'} instance */ 331 public int hashCode() 332 { 333 return 334 Objects.hashCode(this.left) 335 + Objects.hashCode(this.top) 336 + Objects.hashCode(this.width) 337 + Objects.hashCode(this.height) 338 + Objects.hashCode(this.windowState); 339 } 340 } 341 342 /** 343 * Definition of PermissionDescriptor defined in the Permissions API: 344 * https://w3c.github.io/permissions/#dom-permissiondescriptor. 345 * <BR /><B CLASS=Exp>EXPERIMENTAL</B> 346 */ 347 public static class PermissionDescriptor 348 extends BaseType 349 implements java.io.Serializable 350 { 351 /** For Object Serialization. java.io.Serializable */ 352 protected static final long serialVersionUID = 1; 353 354 public boolean[] optionals() 355 { return new boolean[] { false, true, true, true, true, true, }; } 356 357 /** 358 * Name of permission. 359 * See https://cs.chromium.org/chromium/src/third_party/blink/renderer/modules/permissions/permission_descriptor.idl for valid permission names. 360 */ 361 public final String name; 362 363 /** 364 * For "midi" permission, may also specify sysex control. 365 * <BR /><B CLASS=Opt>OPTIONAL</B> 366 */ 367 public final Boolean sysex; 368 369 /** 370 * For "push" permission, may specify userVisibleOnly. 371 * Note that userVisibleOnly = true is the only currently supported type. 372 * <BR /><B CLASS=Opt>OPTIONAL</B> 373 */ 374 public final Boolean userVisibleOnly; 375 376 /** 377 * For "clipboard" permission, may specify allowWithoutSanitization. 378 * <BR /><B CLASS=Opt>OPTIONAL</B> 379 */ 380 public final Boolean allowWithoutSanitization; 381 382 /** 383 * For "fullscreen" permission, must specify allowWithoutGesture:true. 384 * <BR /><B CLASS=Opt>OPTIONAL</B> 385 */ 386 public final Boolean allowWithoutGesture; 387 388 /** 389 * For "camera" permission, may specify panTiltZoom. 390 * <BR /><B CLASS=Opt>OPTIONAL</B> 391 */ 392 public final Boolean panTiltZoom; 393 394 /** 395 * Constructor 396 * 397 * @param name 398 * Name of permission. 399 * See https://cs.chromium.org/chromium/src/third_party/blink/renderer/modules/permissions/permission_descriptor.idl for valid permission names. 400 * 401 * @param sysex For "midi" permission, may also specify sysex control. 402 * <BR /><B CLASS=Opt>OPTIONAL</B> 403 * 404 * @param userVisibleOnly 405 * For "push" permission, may specify userVisibleOnly. 406 * Note that userVisibleOnly = true is the only currently supported type. 407 * <BR /><B CLASS=Opt>OPTIONAL</B> 408 * 409 * @param allowWithoutSanitization For "clipboard" permission, may specify allowWithoutSanitization. 410 * <BR /><B CLASS=Opt>OPTIONAL</B> 411 * 412 * @param allowWithoutGesture For "fullscreen" permission, must specify allowWithoutGesture:true. 413 * <BR /><B CLASS=Opt>OPTIONAL</B> 414 * 415 * @param panTiltZoom For "camera" permission, may specify panTiltZoom. 416 * <BR /><B CLASS=Opt>OPTIONAL</B> 417 */ 418 public PermissionDescriptor( 419 String name, Boolean sysex, Boolean userVisibleOnly, 420 Boolean allowWithoutSanitization, Boolean allowWithoutGesture, Boolean panTiltZoom 421 ) 422 { 423 // Exception-Check(s) to ensure that if any parameters which are not declared as 424 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 425 426 if (name == null) THROWS.throwNPE("name"); 427 428 this.name = name; 429 this.sysex = sysex; 430 this.userVisibleOnly = userVisibleOnly; 431 this.allowWithoutSanitization = allowWithoutSanitization; 432 this.allowWithoutGesture = allowWithoutGesture; 433 this.panTiltZoom = panTiltZoom; 434 } 435 436 /** 437 * JSON Object Constructor 438 * @param jo A Json-Object having data about an instance of {@code 'PermissionDescriptor'}. 439 */ 440 public PermissionDescriptor (JsonObject jo) 441 { 442 this.name = ReadJSON.getString(jo, "name", false, true); 443 this.sysex = ReadBoxedJSON.getBoolean(jo, "sysex", true); 444 this.userVisibleOnly = ReadBoxedJSON.getBoolean(jo, "userVisibleOnly", true); 445 this.allowWithoutSanitization = ReadBoxedJSON.getBoolean(jo, "allowWithoutSanitization", true); 446 this.allowWithoutGesture = ReadBoxedJSON.getBoolean(jo, "allowWithoutGesture", true); 447 this.panTiltZoom = ReadBoxedJSON.getBoolean(jo, "panTiltZoom", true); 448 } 449 450 451 /** Checks whether {@code 'this'} equals an input Java-{@code Object} */ 452 public boolean equals(Object other) 453 { 454 if (this == other) return true; 455 if (other == null) return false; 456 if (other.getClass() != this.getClass()) return false; 457 458 PermissionDescriptor o = (PermissionDescriptor) other; 459 460 return 461 Objects.equals(this.name, o.name) 462 && Objects.equals(this.sysex, o.sysex) 463 && Objects.equals(this.userVisibleOnly, o.userVisibleOnly) 464 && Objects.equals(this.allowWithoutSanitization, o.allowWithoutSanitization) 465 && Objects.equals(this.allowWithoutGesture, o.allowWithoutGesture) 466 && Objects.equals(this.panTiltZoom, o.panTiltZoom); 467 } 468 469 /** Generates a Hash-Code for {@code 'this'} instance */ 470 public int hashCode() 471 { 472 return 473 Objects.hashCode(this.name) 474 + Objects.hashCode(this.sysex) 475 + Objects.hashCode(this.userVisibleOnly) 476 + Objects.hashCode(this.allowWithoutSanitization) 477 + Objects.hashCode(this.allowWithoutGesture) 478 + Objects.hashCode(this.panTiltZoom); 479 } 480 } 481 482 /** 483 * Chrome histogram bucket. 484 * <BR /><B CLASS=Exp>EXPERIMENTAL</B> 485 */ 486 public static class Bucket 487 extends BaseType 488 implements java.io.Serializable 489 { 490 /** For Object Serialization. java.io.Serializable */ 491 protected static final long serialVersionUID = 1; 492 493 public boolean[] optionals() 494 { return new boolean[] { false, false, false, }; } 495 496 /** Minimum value (inclusive). */ 497 public final int low; 498 499 /** Maximum value (exclusive). */ 500 public final int high; 501 502 /** Number of samples. */ 503 public final int count; 504 505 /** 506 * Constructor 507 * 508 * @param low Minimum value (inclusive). 509 * 510 * @param high Maximum value (exclusive). 511 * 512 * @param count Number of samples. 513 */ 514 public Bucket(int low, int high, int count) 515 { 516 this.low = low; 517 this.high = high; 518 this.count = count; 519 } 520 521 /** 522 * JSON Object Constructor 523 * @param jo A Json-Object having data about an instance of {@code 'Bucket'}. 524 */ 525 public Bucket (JsonObject jo) 526 { 527 this.low = ReadPrimJSON.getInt(jo, "low"); 528 this.high = ReadPrimJSON.getInt(jo, "high"); 529 this.count = ReadPrimJSON.getInt(jo, "count"); 530 } 531 532 533 /** Checks whether {@code 'this'} equals an input Java-{@code Object} */ 534 public boolean equals(Object other) 535 { 536 if (this == other) return true; 537 if (other == null) return false; 538 if (other.getClass() != this.getClass()) return false; 539 540 Bucket o = (Bucket) other; 541 542 return 543 (this.low == o.low) 544 && (this.high == o.high) 545 && (this.count == o.count); 546 } 547 548 /** Generates a Hash-Code for {@code 'this'} instance */ 549 public int hashCode() 550 { 551 return 552 this.low 553 + this.high 554 + this.count; 555 } 556 } 557 558 /** 559 * Chrome histogram. 560 * <BR /><B CLASS=Exp>EXPERIMENTAL</B> 561 */ 562 public static class Histogram 563 extends BaseType 564 implements java.io.Serializable 565 { 566 /** For Object Serialization. java.io.Serializable */ 567 protected static final long serialVersionUID = 1; 568 569 public boolean[] optionals() 570 { return new boolean[] { false, false, false, false, }; } 571 572 /** Name. */ 573 public final String name; 574 575 /** Sum of sample values. */ 576 public final int sum; 577 578 /** Total number of samples. */ 579 public final int count; 580 581 /** Buckets. */ 582 public final Browser.Bucket[] buckets; 583 584 /** 585 * Constructor 586 * 587 * @param name Name. 588 * 589 * @param sum Sum of sample values. 590 * 591 * @param count Total number of samples. 592 * 593 * @param buckets Buckets. 594 */ 595 public Histogram(String name, int sum, int count, Browser.Bucket[] buckets) 596 { 597 // Exception-Check(s) to ensure that if any parameters which are not declared as 598 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 599 600 if (name == null) THROWS.throwNPE("name"); 601 if (buckets == null) THROWS.throwNPE("buckets"); 602 603 this.name = name; 604 this.sum = sum; 605 this.count = count; 606 this.buckets = buckets; 607 } 608 609 /** 610 * JSON Object Constructor 611 * @param jo A Json-Object having data about an instance of {@code 'Histogram'}. 612 */ 613 public Histogram (JsonObject jo) 614 { 615 this.name = ReadJSON.getString(jo, "name", false, true); 616 this.sum = ReadPrimJSON.getInt(jo, "sum"); 617 this.count = ReadPrimJSON.getInt(jo, "count"); 618 this.buckets = (jo.getJsonArray("buckets") == null) 619 ? null 620 : RJArrIntoStream.objArr(jo.getJsonArray("buckets"), null, 0, Browser.Bucket.class).toArray(Browser.Bucket[]::new); 621 622 } 623 624 625 /** Checks whether {@code 'this'} equals an input Java-{@code Object} */ 626 public boolean equals(Object other) 627 { 628 if (this == other) return true; 629 if (other == null) return false; 630 if (other.getClass() != this.getClass()) return false; 631 632 Histogram o = (Histogram) other; 633 634 return 635 Objects.equals(this.name, o.name) 636 && (this.sum == o.sum) 637 && (this.count == o.count) 638 && Arrays.deepEquals(this.buckets, o.buckets); 639 } 640 641 /** Generates a Hash-Code for {@code 'this'} instance */ 642 public int hashCode() 643 { 644 return 645 Objects.hashCode(this.name) 646 + this.sum 647 + this.count 648 + Arrays.deepHashCode(this.buckets); 649 } 650 } 651 652 /** 653 * Fired when page is about to start a download. 654 * <BR /><B CLASS=Exp>EXPERIMENTAL</B> 655 */ 656 public static class downloadWillBegin 657 extends BrowserEvent 658 implements java.io.Serializable 659 { 660 /** For Object Serialization. java.io.Serializable */ 661 protected static final long serialVersionUID = 1; 662 663 public boolean[] optionals() 664 { return new boolean[] { false, false, false, false, }; } 665 666 /** Id of the frame that caused the download to begin. */ 667 public final String frameId; 668 669 /** Global unique identifier of the download. */ 670 public final String guid; 671 672 /** URL of the resource being downloaded. */ 673 public final String url; 674 675 /** Suggested file name of the resource (the actual name of the file saved on disk may differ). */ 676 public final String suggestedFilename; 677 678 /** 679 * Constructor 680 * 681 * @param frameId Id of the frame that caused the download to begin. 682 * 683 * @param guid Global unique identifier of the download. 684 * 685 * @param url URL of the resource being downloaded. 686 * 687 * @param suggestedFilename Suggested file name of the resource (the actual name of the file saved on disk may differ). 688 */ 689 public downloadWillBegin 690 (String frameId, String guid, String url, String suggestedFilename) 691 { 692 super("Browser", "downloadWillBegin", 4); 693 694 // Exception-Check(s) to ensure that if any parameters which are not declared as 695 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 696 697 if (frameId == null) THROWS.throwNPE("frameId"); 698 if (guid == null) THROWS.throwNPE("guid"); 699 if (url == null) THROWS.throwNPE("url"); 700 if (suggestedFilename == null) THROWS.throwNPE("suggestedFilename"); 701 702 this.frameId = frameId; 703 this.guid = guid; 704 this.url = url; 705 this.suggestedFilename = suggestedFilename; 706 } 707 708 /** 709 * JSON Object Constructor 710 * @param jo A Json-Object having data about an instance of {@code 'downloadWillBegin'}. 711 */ 712 public downloadWillBegin (JsonObject jo) 713 { 714 super("Browser", "downloadWillBegin", 4); 715 716 this.frameId = ReadJSON.getString(jo, "frameId", false, true); 717 this.guid = ReadJSON.getString(jo, "guid", false, true); 718 this.url = ReadJSON.getString(jo, "url", false, true); 719 this.suggestedFilename = ReadJSON.getString(jo, "suggestedFilename", false, true); 720 } 721 722 723 /** Checks whether {@code 'this'} equals an input Java-{@code Object} */ 724 public boolean equals(Object other) 725 { 726 if (this == other) return true; 727 if (other == null) return false; 728 if (other.getClass() != this.getClass()) return false; 729 730 downloadWillBegin o = (downloadWillBegin) other; 731 732 return 733 Objects.equals(this.frameId, o.frameId) 734 && Objects.equals(this.guid, o.guid) 735 && Objects.equals(this.url, o.url) 736 && Objects.equals(this.suggestedFilename, o.suggestedFilename); 737 } 738 739 /** Generates a Hash-Code for {@code 'this'} instance */ 740 public int hashCode() 741 { 742 return 743 Objects.hashCode(this.frameId) 744 + Objects.hashCode(this.guid) 745 + Objects.hashCode(this.url) 746 + Objects.hashCode(this.suggestedFilename); 747 } 748 } 749 750 /** 751 * Fired when download makes progress. Last call has |done| == true. 752 * <BR /><B CLASS=Exp>EXPERIMENTAL</B> 753 */ 754 public static class downloadProgress 755 extends BrowserEvent 756 implements java.io.Serializable 757 { 758 /** For Object Serialization. java.io.Serializable */ 759 protected static final long serialVersionUID = 1; 760 761 public boolean[] optionals() 762 { return new boolean[] { false, false, false, false, true, }; } 763 764 /** Global unique identifier of the download. */ 765 public final String guid; 766 767 /** Total expected bytes to download. */ 768 public final Number totalBytes; 769 770 /** Total bytes received. */ 771 public final Number receivedBytes; 772 773 /** Download status. */ 774 public final String state; 775 776 /** 777 * If download is "completed", provides the path of the downloaded file. 778 * Depending on the platform, it is not guaranteed to be set, nor the file 779 * is guaranteed to exist. 780 * <BR /><B CLASS=Opt>OPTIONAL</B> 781 <B CLASS=Exp>EXPERIMENTAL</B> 782 */ 783 public final String filePath; 784 785 /** 786 * Constructor 787 * 788 * @param guid Global unique identifier of the download. 789 * 790 * @param totalBytes Total expected bytes to download. 791 * 792 * @param receivedBytes Total bytes received. 793 * 794 * @param state Download status. 795 * <BR />Acceptable Values: ["inProgress", "completed", "canceled"] 796 * 797 * @param filePath 798 * If download is "completed", provides the path of the downloaded file. 799 * Depending on the platform, it is not guaranteed to be set, nor the file 800 * is guaranteed to exist. 801 * <BR /><B CLASS=Opt>OPTIONAL</B><B CLASS=Exp>EXPERIMENTAL</B> 802 */ 803 public downloadProgress 804 (String guid, Number totalBytes, Number receivedBytes, String state, String filePath) 805 { 806 super("Browser", "downloadProgress", 5); 807 808 // Exception-Check(s) to ensure that if any parameters which are not declared as 809 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 810 811 if (guid == null) THROWS.throwNPE("guid"); 812 if (totalBytes == null) THROWS.throwNPE("totalBytes"); 813 if (receivedBytes == null) THROWS.throwNPE("receivedBytes"); 814 if (state == null) THROWS.throwNPE("state"); 815 816 // Exception-Check(s) to ensure that if any parameters which must adhere to a 817 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 818 819 THROWS.checkIAE( 820 "state", state, 821 "inProgress", "completed", "canceled" 822 ); 823 824 this.guid = guid; 825 this.totalBytes = totalBytes; 826 this.receivedBytes = receivedBytes; 827 this.state = state; 828 this.filePath = filePath; 829 } 830 831 /** 832 * JSON Object Constructor 833 * @param jo A Json-Object having data about an instance of {@code 'downloadProgress'}. 834 */ 835 public downloadProgress (JsonObject jo) 836 { 837 super("Browser", "downloadProgress", 5); 838 839 this.guid = ReadJSON.getString(jo, "guid", false, true); 840 this.totalBytes = ReadNumberJSON.get(jo, "totalBytes", false, true); 841 this.receivedBytes = ReadNumberJSON.get(jo, "receivedBytes", false, true); 842 this.state = ReadJSON.getString(jo, "state", false, true); 843 this.filePath = ReadJSON.getString(jo, "filePath", true, false); 844 } 845 846 847 /** Checks whether {@code 'this'} equals an input Java-{@code Object} */ 848 public boolean equals(Object other) 849 { 850 if (this == other) return true; 851 if (other == null) return false; 852 if (other.getClass() != this.getClass()) return false; 853 854 downloadProgress o = (downloadProgress) other; 855 856 return 857 Objects.equals(this.guid, o.guid) 858 && Objects.equals(this.totalBytes, o.totalBytes) 859 && Objects.equals(this.receivedBytes, o.receivedBytes) 860 && Objects.equals(this.state, o.state) 861 && Objects.equals(this.filePath, o.filePath); 862 } 863 864 /** Generates a Hash-Code for {@code 'this'} instance */ 865 public int hashCode() 866 { 867 return 868 Objects.hashCode(this.guid) 869 + Objects.hashCode(this.totalBytes) 870 + Objects.hashCode(this.receivedBytes) 871 + Objects.hashCode(this.state) 872 + Objects.hashCode(this.filePath); 873 } 874 } 875 876 877 // Counter for keeping the WebSocket Request ID's distinct. 878 private static int counter = 1; 879 880 /** 881 * Set permission settings for given origin. 882 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B> 883 * 884 * @param permission Descriptor of permission to override. 885 * 886 * @param setting Setting of the permission. 887 * 888 * @param origin Origin the permission applies to, all origins if not specified. 889 * <BR /><B CLASS=Opt>OPTIONAL</B> 890 * 891 * @param browserContextId Context to override. When omitted, default browser context is used. 892 * <BR /><B CLASS=Opt>OPTIONAL</B> 893 * 894 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 895 * {@link Ret0}></CODE> 896 * 897 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 898 * browser receives the invocation-request. 899 * 900 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 901 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 902 * {@code >} to ensure the Browser Function has run to completion. 903 */ 904 public static Script<String, JsonObject, Ret0> setPermission( 905 Browser.PermissionDescriptor permission, String setting, String origin, 906 String browserContextId 907 ) 908 { 909 // Exception-Check(s) to ensure that if any parameters which are not declared as 910 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 911 912 if (permission == null) THROWS.throwNPE("permission"); 913 if (setting == null) THROWS.throwNPE("setting"); 914 915 // Exception-Check(s) to ensure that if any parameters which must adhere to a 916 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 917 918 THROWS.checkIAE("setting", setting, "Browser.PermissionSetting", Browser.PermissionSetting); 919 920 final int webSocketID = 13000000 + counter++; 921 final boolean[] optionals = { false, false, true, true, }; 922 923 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 924 String requestJSON = WriteJSON.get( 925 parameterTypes.get("setPermission"), 926 parameterNames.get("setPermission"), 927 optionals, webSocketID, 928 "Browser.setPermission", 929 permission, setting, origin, browserContextId 930 ); 931 932 // This Remote Command does not have a Return-Value. 933 return new Script<> 934 (webSocketID, requestJSON, VOID_RETURN.NoReturnValues); 935 } 936 937 /** 938 * Grant specific permissions to the given origin and reject all others. 939 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B> 940 * 941 * @param permissions - 942 * 943 * @param origin Origin the permission applies to, all origins if not specified. 944 * <BR /><B CLASS=Opt>OPTIONAL</B> 945 * 946 * @param browserContextId BrowserContext to override permissions. When omitted, default browser context is used. 947 * <BR /><B CLASS=Opt>OPTIONAL</B> 948 * 949 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 950 * {@link Ret0}></CODE> 951 * 952 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 953 * browser receives the invocation-request. 954 * 955 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 956 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 957 * {@code >} to ensure the Browser Function has run to completion. 958 */ 959 public static Script<String, JsonObject, Ret0> grantPermissions 960 (String[] permissions, String origin, String browserContextId) 961 { 962 // Exception-Check(s) to ensure that if any parameters which are not declared as 963 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 964 965 if (permissions == null) THROWS.throwNPE("permissions"); 966 967 final int webSocketID = 13001000 + counter++; 968 final boolean[] optionals = { false, true, true, }; 969 970 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 971 String requestJSON = WriteJSON.get( 972 parameterTypes.get("grantPermissions"), 973 parameterNames.get("grantPermissions"), 974 optionals, webSocketID, 975 "Browser.grantPermissions", 976 permissions, origin, browserContextId 977 ); 978 979 // This Remote Command does not have a Return-Value. 980 return new Script<> 981 (webSocketID, requestJSON, VOID_RETURN.NoReturnValues); 982 } 983 984 /** 985 * Reset all permission management for all origins. 986 * 987 * @param browserContextId BrowserContext to reset permissions. When omitted, default browser context is used. 988 * <BR /><B CLASS=Opt>OPTIONAL</B> 989 * 990 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 991 * {@link Ret0}></CODE> 992 * 993 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 994 * browser receives the invocation-request. 995 * 996 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 997 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 998 * {@code >} to ensure the Browser Function has run to completion. 999 */ 1000 public static Script<String, JsonObject, Ret0> resetPermissions(String browserContextId) 1001 { 1002 final int webSocketID = 13002000 + counter++; 1003 final boolean[] optionals = { true, }; 1004 1005 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1006 String requestJSON = WriteJSON.get( 1007 parameterTypes.get("resetPermissions"), 1008 parameterNames.get("resetPermissions"), 1009 optionals, webSocketID, 1010 "Browser.resetPermissions", 1011 browserContextId 1012 ); 1013 1014 // This Remote Command does not have a Return-Value. 1015 return new Script<> 1016 (webSocketID, requestJSON, VOID_RETURN.NoReturnValues); 1017 } 1018 1019 /** 1020 * Set the behavior when downloading a file. 1021 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B> 1022 * 1023 * @param behavior 1024 * Whether to allow all or deny all download requests, or use default Chrome behavior if 1025 * available (otherwise deny). |allowAndName| allows download and names files according to 1026 * their download guids. 1027 * <BR />Acceptable Values: ["deny", "allow", "allowAndName", "default"] 1028 * 1029 * @param browserContextId BrowserContext to set download behavior. When omitted, default browser context is used. 1030 * <BR /><B CLASS=Opt>OPTIONAL</B> 1031 * 1032 * @param downloadPath 1033 * The default path to save downloaded files to. This is required if behavior is set to 'allow' 1034 * or 'allowAndName'. 1035 * <BR /><B CLASS=Opt>OPTIONAL</B> 1036 * 1037 * @param eventsEnabled Whether to emit download events (defaults to false). 1038 * <BR /><B CLASS=Opt>OPTIONAL</B> 1039 * 1040 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1041 * {@link Ret0}></CODE> 1042 * 1043 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 1044 * browser receives the invocation-request. 1045 * 1046 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 1047 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 1048 * {@code >} to ensure the Browser Function has run to completion. 1049 */ 1050 public static Script<String, JsonObject, Ret0> setDownloadBehavior 1051 (String behavior, String browserContextId, String downloadPath, Boolean eventsEnabled) 1052 { 1053 // Exception-Check(s) to ensure that if any parameters which are not declared as 1054 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 1055 1056 if (behavior == null) THROWS.throwNPE("behavior"); 1057 1058 // Exception-Check(s) to ensure that if any parameters which must adhere to a 1059 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 1060 1061 THROWS.checkIAE( 1062 "behavior", behavior, 1063 "deny", "allow", "allowAndName", "default" 1064 ); 1065 1066 final int webSocketID = 13003000 + counter++; 1067 final boolean[] optionals = { false, true, true, true, }; 1068 1069 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1070 String requestJSON = WriteJSON.get( 1071 parameterTypes.get("setDownloadBehavior"), 1072 parameterNames.get("setDownloadBehavior"), 1073 optionals, webSocketID, 1074 "Browser.setDownloadBehavior", 1075 behavior, browserContextId, downloadPath, eventsEnabled 1076 ); 1077 1078 // This Remote Command does not have a Return-Value. 1079 return new Script<> 1080 (webSocketID, requestJSON, VOID_RETURN.NoReturnValues); 1081 } 1082 1083 /** 1084 * Cancel a download if in progress 1085 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B> 1086 * 1087 * @param guid Global unique identifier of the download. 1088 * 1089 * @param browserContextId BrowserContext to perform the action in. When omitted, default browser context is used. 1090 * <BR /><B CLASS=Opt>OPTIONAL</B> 1091 * 1092 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1093 * {@link Ret0}></CODE> 1094 * 1095 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 1096 * browser receives the invocation-request. 1097 * 1098 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 1099 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 1100 * {@code >} to ensure the Browser Function has run to completion. 1101 */ 1102 public static Script<String, JsonObject, Ret0> cancelDownload 1103 (String guid, String browserContextId) 1104 { 1105 // Exception-Check(s) to ensure that if any parameters which are not declared as 1106 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 1107 1108 if (guid == null) THROWS.throwNPE("guid"); 1109 1110 final int webSocketID = 13004000 + counter++; 1111 final boolean[] optionals = { false, true, }; 1112 1113 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1114 String requestJSON = WriteJSON.get( 1115 parameterTypes.get("cancelDownload"), 1116 parameterNames.get("cancelDownload"), 1117 optionals, webSocketID, 1118 "Browser.cancelDownload", 1119 guid, browserContextId 1120 ); 1121 1122 // This Remote Command does not have a Return-Value. 1123 return new Script<> 1124 (webSocketID, requestJSON, VOID_RETURN.NoReturnValues); 1125 } 1126 1127 /** 1128 * Close browser gracefully. 1129 * 1130 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1131 * {@link Ret0}></CODE> 1132 * 1133 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 1134 * browser receives the invocation-request. 1135 * 1136 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 1137 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 1138 * {@code >} to ensure the Browser Function has run to completion. 1139 */ 1140 public static Script<String, JsonObject, Ret0> close() 1141 { 1142 final int webSocketID = 13005000 + counter++; 1143 final boolean[] optionals = new boolean[0]; 1144 1145 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1146 String requestJSON = WriteJSON.get( 1147 parameterTypes.get("close"), 1148 parameterNames.get("close"), 1149 optionals, webSocketID, 1150 "Browser.close" 1151 ); 1152 1153 // This Remote Command does not have a Return-Value. 1154 return new Script<> 1155 (webSocketID, requestJSON, VOID_RETURN.NoReturnValues); 1156 } 1157 1158 /** 1159 * Crashes browser on the main thread. 1160 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B> 1161 * 1162 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1163 * {@link Ret0}></CODE> 1164 * 1165 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 1166 * browser receives the invocation-request. 1167 * 1168 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 1169 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 1170 * {@code >} to ensure the Browser Function has run to completion. 1171 */ 1172 public static Script<String, JsonObject, Ret0> crash() 1173 { 1174 final int webSocketID = 13006000 + counter++; 1175 final boolean[] optionals = new boolean[0]; 1176 1177 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1178 String requestJSON = WriteJSON.get( 1179 parameterTypes.get("crash"), 1180 parameterNames.get("crash"), 1181 optionals, webSocketID, 1182 "Browser.crash" 1183 ); 1184 1185 // This Remote Command does not have a Return-Value. 1186 return new Script<> 1187 (webSocketID, requestJSON, VOID_RETURN.NoReturnValues); 1188 } 1189 1190 /** 1191 * Crashes GPU process. 1192 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B> 1193 * 1194 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1195 * {@link Ret0}></CODE> 1196 * 1197 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 1198 * browser receives the invocation-request. 1199 * 1200 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 1201 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 1202 * {@code >} to ensure the Browser Function has run to completion. 1203 */ 1204 public static Script<String, JsonObject, Ret0> crashGpuProcess() 1205 { 1206 final int webSocketID = 13007000 + counter++; 1207 final boolean[] optionals = new boolean[0]; 1208 1209 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1210 String requestJSON = WriteJSON.get( 1211 parameterTypes.get("crashGpuProcess"), 1212 parameterNames.get("crashGpuProcess"), 1213 optionals, webSocketID, 1214 "Browser.crashGpuProcess" 1215 ); 1216 1217 // This Remote Command does not have a Return-Value. 1218 return new Script<> 1219 (webSocketID, requestJSON, VOID_RETURN.NoReturnValues); 1220 } 1221 1222 /** 1223 * Returns version information. 1224 * 1225 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1226 * {@link Ret5}></CODE> 1227 * 1228 * <BR /><BR />This {@link Script} may be <B STYLE='color:red'>executed</B> (using 1229 * {@link Script#exec()}), and a {@link Promise} returned. 1230 * 1231 * <BR /><BR />When the {@code Promise} is <B STYLE='color: red'>awaited</B> 1232 * (using {@link Promise#await()}), the {@code Ret5} will subsequently 1233 * be returned from that call. 1234 * 1235 * <BR /><BR />The <B STYLE='color: red'>returned</B> values are encapsulated 1236 * in an instance of <B>{@link Ret5}</B> 1237 * 1238 * <BR /><BR /><UL CLASS=JDUL> 1239 * <LI><CODE><B>Ret5.a:</B> String (<B>protocolVersion</B>)</CODE> 1240 * <BR />Protocol version. 1241 * <BR /><BR /></LI> 1242 * <LI><CODE><B>Ret5.b:</B> String (<B>product</B>)</CODE> 1243 * <BR />Product name. 1244 * <BR /><BR /></LI> 1245 * <LI><CODE><B>Ret5.c:</B> String (<B>revision</B>)</CODE> 1246 * <BR />Product revision. 1247 * <BR /><BR /></LI> 1248 * <LI><CODE><B>Ret5.d:</B> String (<B>userAgent</B>)</CODE> 1249 * <BR />User-Agent. 1250 * <BR /><BR /></LI> 1251 * <LI><CODE><B>Ret5.e:</B> String (<B>jsVersion</B>)</CODE> 1252 * <BR />V8 version. 1253 * </LI> 1254 * </UL> 1255 */ 1256 public static Script<String, JsonObject, Ret5<String, String, String, String, String>> getVersion() 1257 { 1258 final int webSocketID = 13008000 + counter++; 1259 final boolean[] optionals = new boolean[0]; 1260 1261 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1262 String requestJSON = WriteJSON.get( 1263 parameterTypes.get("getVersion"), 1264 parameterNames.get("getVersion"), 1265 optionals, webSocketID, 1266 "Browser.getVersion" 1267 ); 1268 1269 // 'JSON Binding' ... Converts Browser Response-JSON into Java-Type 'Ret5' 1270 Function<JsonObject, Ret5<String, String, String, String, String>> 1271 responseProcessor = (JsonObject jo) -> new Ret5<>( 1272 ReadJSON.getString(jo, "protocolVersion", false, true), 1273 ReadJSON.getString(jo, "product", false, true), 1274 ReadJSON.getString(jo, "revision", false, true), 1275 ReadJSON.getString(jo, "userAgent", false, true), 1276 ReadJSON.getString(jo, "jsVersion", false, true) 1277 ); 1278 1279 return new Script<>(webSocketID, requestJSON, responseProcessor); 1280 } 1281 1282 /** 1283 * Returns the command line switches for the browser process if, and only if 1284 * --enable-automation is on the commandline. 1285 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B> 1286 * 1287 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1288 * String[]></CODE> 1289 * 1290 * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using 1291 * {@link Script#exec()}, and afterwards, a {@link Promise}<CODE><JsonObject, 1292 * String[]></CODE> will be returned. 1293 * 1294 * <BR /><BR />Finally, the <B>{@code Promise}</B> may be <B STYLE='color: red'>awaited</B>, 1295 * using {@link Promise#await()}, <I>and the returned result of this Browser Function may 1296 * may be retrieved.</I> 1297 * 1298 * <BR /><BR />This Browser Function <B STYLE='color: red'>returns</B> 1299 * <BR /><BR /><UL CLASS=JDUL> 1300 * <LI><CODE>String[] (<B>arguments</B></CODE>) 1301 * <BR />Commandline parameters 1302 * </LI> 1303 * </UL> */ 1304 public static Script<String, JsonObject, String[]> getBrowserCommandLine() 1305 { 1306 final int webSocketID = 13009000 + counter++; 1307 final boolean[] optionals = new boolean[0]; 1308 1309 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1310 String requestJSON = WriteJSON.get( 1311 parameterTypes.get("getBrowserCommandLine"), 1312 parameterNames.get("getBrowserCommandLine"), 1313 optionals, webSocketID, 1314 "Browser.getBrowserCommandLine" 1315 ); 1316 1317 // 'JSON Binding' ... Converts Browser Response-JSON to 'String[]' 1318 Function<JsonObject, String[]> responseProcessor = (JsonObject jo) -> 1319 (jo.getJsonArray("arguments") == null) 1320 ? null 1321 : RJArrIntoStream.strArr(jo.getJsonArray("arguments"), null, 0).toArray(String[]::new); 1322 1323 return new Script<>(webSocketID, requestJSON, responseProcessor); 1324 } 1325 1326 /** 1327 * Get Chrome histograms. 1328 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B> 1329 * 1330 * @param query 1331 * Requested substring in name. Only histograms which have query as a 1332 * substring in their name are extracted. An empty or absent query returns 1333 * all histograms. 1334 * <BR /><B CLASS=Opt>OPTIONAL</B> 1335 * 1336 * @param delta If true, retrieve delta since last delta call. 1337 * <BR /><B CLASS=Opt>OPTIONAL</B> 1338 * 1339 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1340 * {@link Browser.Histogram}[]></CODE> 1341 * 1342 * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using 1343 * {@link Script#exec()}, and afterwards, a {@link Promise}<CODE><JsonObject, 1344 * {@link Browser.Histogram}[]></CODE> will be returned. 1345 * 1346 * <BR /><BR />Finally, the <B>{@code Promise}</B> may be <B STYLE='color: red'>awaited</B>, 1347 * using {@link Promise#await()}, <I>and the returned result of this Browser Function may 1348 * may be retrieved.</I> 1349 * 1350 * <BR /><BR />This Browser Function <B STYLE='color: red'>returns</B> 1351 * <BR /><BR /><UL CLASS=JDUL> 1352 * <LI><CODE>{@link Browser.Histogram}[] (<B>histograms</B></CODE>) 1353 * <BR />Histograms. 1354 * </LI> 1355 * </UL> */ 1356 public static Script<String, JsonObject, Browser.Histogram[]> getHistograms 1357 (String query, Boolean delta) 1358 { 1359 final int webSocketID = 13010000 + counter++; 1360 final boolean[] optionals = { true, true, }; 1361 1362 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1363 String requestJSON = WriteJSON.get( 1364 parameterTypes.get("getHistograms"), 1365 parameterNames.get("getHistograms"), 1366 optionals, webSocketID, 1367 "Browser.getHistograms", 1368 query, delta 1369 ); 1370 1371 // 'JSON Binding' ... Converts Browser Response-JSON to 'Browser.Histogram[]' 1372 Function<JsonObject, Browser.Histogram[]> responseProcessor = (JsonObject jo) -> 1373 (jo.getJsonArray("histograms") == null) 1374 ? null 1375 : RJArrIntoStream.objArr(jo.getJsonArray("histograms"), null, 0, Browser.Histogram.class).toArray(Browser.Histogram[]::new); 1376 1377 return new Script<>(webSocketID, requestJSON, responseProcessor); 1378 } 1379 1380 /** 1381 * Get a Chrome histogram by name. 1382 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B> 1383 * 1384 * @param name Requested histogram name. 1385 * 1386 * @param delta If true, retrieve delta since last delta call. 1387 * <BR /><B CLASS=Opt>OPTIONAL</B> 1388 * 1389 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1390 * {@link Browser.Histogram}></CODE> 1391 * 1392 * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using 1393 * {@link Script#exec()}, and afterwards, a {@link Promise}<CODE><JsonObject, 1394 * {@link Browser.Histogram}></CODE> will be returned. 1395 * 1396 * <BR /><BR />Finally, the <B>{@code Promise}</B> may be <B STYLE='color: red'>awaited</B>, 1397 * using {@link Promise#await()}, <I>and the returned result of this Browser Function may 1398 * may be retrieved.</I> 1399 * 1400 * <BR /><BR />This Browser Function <B STYLE='color: red'>returns</B> 1401 * <BR /><BR /><UL CLASS=JDUL> 1402 * <LI><CODE>{@link Browser.Histogram} (<B>histogram</B></CODE>) 1403 * <BR />Histogram. 1404 * </LI> 1405 * </UL> */ 1406 public static Script<String, JsonObject, Browser.Histogram> getHistogram 1407 (String name, Boolean delta) 1408 { 1409 // Exception-Check(s) to ensure that if any parameters which are not declared as 1410 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 1411 1412 if (name == null) THROWS.throwNPE("name"); 1413 1414 final int webSocketID = 13011000 + counter++; 1415 final boolean[] optionals = { false, true, }; 1416 1417 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1418 String requestJSON = WriteJSON.get( 1419 parameterTypes.get("getHistogram"), 1420 parameterNames.get("getHistogram"), 1421 optionals, webSocketID, 1422 "Browser.getHistogram", 1423 name, delta 1424 ); 1425 1426 // 'JSON Binding' ... Converts Browser Response-JSON to 'Browser.Histogram' 1427 Function<JsonObject, Browser.Histogram> responseProcessor = (JsonObject jo) -> 1428 ReadJSON.getObject(jo, "histogram", Browser.Histogram.class, false, true); 1429 1430 return new Script<>(webSocketID, requestJSON, responseProcessor); 1431 } 1432 1433 /** 1434 * Get position and size of the browser window. 1435 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B> 1436 * 1437 * @param windowId Browser window id. 1438 * 1439 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1440 * {@link Browser.Bounds}></CODE> 1441 * 1442 * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using 1443 * {@link Script#exec()}, and afterwards, a {@link Promise}<CODE><JsonObject, 1444 * {@link Browser.Bounds}></CODE> will be returned. 1445 * 1446 * <BR /><BR />Finally, the <B>{@code Promise}</B> may be <B STYLE='color: red'>awaited</B>, 1447 * using {@link Promise#await()}, <I>and the returned result of this Browser Function may 1448 * may be retrieved.</I> 1449 * 1450 * <BR /><BR />This Browser Function <B STYLE='color: red'>returns</B> 1451 * <BR /><BR /><UL CLASS=JDUL> 1452 * <LI><CODE>{@link Browser.Bounds} (<B>bounds</B></CODE>) 1453 * <BR />Bounds information of the window. When window state is 'minimized', the restored window 1454 * position and size are returned. 1455 * </LI> 1456 * </UL> */ 1457 public static Script<String, JsonObject, Browser.Bounds> getWindowBounds(int windowId) 1458 { 1459 final int webSocketID = 13012000 + counter++; 1460 final boolean[] optionals = { false, }; 1461 1462 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1463 String requestJSON = WriteJSON.get( 1464 parameterTypes.get("getWindowBounds"), 1465 parameterNames.get("getWindowBounds"), 1466 optionals, webSocketID, 1467 "Browser.getWindowBounds", 1468 windowId 1469 ); 1470 1471 // 'JSON Binding' ... Converts Browser Response-JSON to 'Browser.Bounds' 1472 Function<JsonObject, Browser.Bounds> responseProcessor = (JsonObject jo) -> 1473 ReadJSON.getObject(jo, "bounds", Browser.Bounds.class, false, true); 1474 1475 return new Script<>(webSocketID, requestJSON, responseProcessor); 1476 } 1477 1478 /** 1479 * Get the browser window that contains the devtools target. 1480 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B> 1481 * 1482 * @param targetId Devtools agent host id. If called as a part of the session, associated targetId is used. 1483 * <BR /><B CLASS=Opt>OPTIONAL</B> 1484 * 1485 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1486 * {@link Ret2}></CODE> 1487 * 1488 * <BR /><BR />This {@link Script} may be <B STYLE='color:red'>executed</B> (using 1489 * {@link Script#exec()}), and a {@link Promise} returned. 1490 * 1491 * <BR /><BR />When the {@code Promise} is <B STYLE='color: red'>awaited</B> 1492 * (using {@link Promise#await()}), the {@code Ret2} will subsequently 1493 * be returned from that call. 1494 * 1495 * <BR /><BR />The <B STYLE='color: red'>returned</B> values are encapsulated 1496 * in an instance of <B>{@link Ret2}</B> 1497 * 1498 * <BR /><BR /><UL CLASS=JDUL> 1499 * <LI><CODE><B>Ret2.a:</B> Integer (<B>windowId</B>)</CODE> 1500 * <BR />Browser window id. 1501 * <BR /><BR /></LI> 1502 * <LI><CODE><B>Ret2.b:</B> {@link Browser.Bounds} (<B>bounds</B>)</CODE> 1503 * <BR />Bounds information of the window. When window state is 'minimized', the restored window 1504 * position and size are returned. 1505 * </LI> 1506 * </UL> 1507 */ 1508 public static Script<String, JsonObject, Ret2<Integer, Browser.Bounds>> getWindowForTarget 1509 (String targetId) 1510 { 1511 final int webSocketID = 13013000 + counter++; 1512 final boolean[] optionals = { true, }; 1513 1514 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1515 String requestJSON = WriteJSON.get( 1516 parameterTypes.get("getWindowForTarget"), 1517 parameterNames.get("getWindowForTarget"), 1518 optionals, webSocketID, 1519 "Browser.getWindowForTarget", 1520 targetId 1521 ); 1522 1523 // 'JSON Binding' ... Converts Browser Response-JSON into Java-Type 'Ret2' 1524 Function<JsonObject, Ret2<Integer, Browser.Bounds>> 1525 responseProcessor = (JsonObject jo) -> new Ret2<>( 1526 ReadBoxedJSON.getInteger(jo, "windowId", true), 1527 ReadJSON.getObject(jo, "bounds", Browser.Bounds.class, false, true) 1528 ); 1529 1530 return new Script<>(webSocketID, requestJSON, responseProcessor); 1531 } 1532 1533 /** 1534 * Set position and/or size of the browser window. 1535 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B> 1536 * 1537 * @param windowId Browser window id. 1538 * 1539 * @param bounds 1540 * New window bounds. The 'minimized', 'maximized' and 'fullscreen' states cannot be combined 1541 * with 'left', 'top', 'width' or 'height'. Leaves unspecified fields unchanged. 1542 * 1543 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1544 * {@link Ret0}></CODE> 1545 * 1546 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 1547 * browser receives the invocation-request. 1548 * 1549 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 1550 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 1551 * {@code >} to ensure the Browser Function has run to completion. 1552 */ 1553 public static Script<String, JsonObject, Ret0> setWindowBounds 1554 (int windowId, Browser.Bounds bounds) 1555 { 1556 // Exception-Check(s) to ensure that if any parameters which are not declared as 1557 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 1558 1559 if (bounds == null) THROWS.throwNPE("bounds"); 1560 1561 final int webSocketID = 13014000 + counter++; 1562 final boolean[] optionals = { false, false, }; 1563 1564 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1565 String requestJSON = WriteJSON.get( 1566 parameterTypes.get("setWindowBounds"), 1567 parameterNames.get("setWindowBounds"), 1568 optionals, webSocketID, 1569 "Browser.setWindowBounds", 1570 windowId, bounds 1571 ); 1572 1573 // This Remote Command does not have a Return-Value. 1574 return new Script<> 1575 (webSocketID, requestJSON, VOID_RETURN.NoReturnValues); 1576 } 1577 1578 /** 1579 * Set size of the browser contents resizing browser window as necessary. 1580 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B> 1581 * 1582 * @param windowId Browser window id. 1583 * 1584 * @param width 1585 * The window contents width in DIP. Assumes current width if omitted. 1586 * Must be specified if 'height' is omitted. 1587 * <BR /><B CLASS=Opt>OPTIONAL</B> 1588 * 1589 * @param height 1590 * The window contents height in DIP. Assumes current height if omitted. 1591 * Must be specified if 'width' is omitted. 1592 * <BR /><B CLASS=Opt>OPTIONAL</B> 1593 * 1594 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1595 * {@link Ret0}></CODE> 1596 * 1597 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 1598 * browser receives the invocation-request. 1599 * 1600 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 1601 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 1602 * {@code >} to ensure the Browser Function has run to completion. 1603 */ 1604 public static Script<String, JsonObject, Ret0> setContentsSize 1605 (int windowId, Integer width, Integer height) 1606 { 1607 final int webSocketID = 13015000 + counter++; 1608 final boolean[] optionals = { false, true, true, }; 1609 1610 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1611 String requestJSON = WriteJSON.get( 1612 parameterTypes.get("setContentsSize"), 1613 parameterNames.get("setContentsSize"), 1614 optionals, webSocketID, 1615 "Browser.setContentsSize", 1616 windowId, width, height 1617 ); 1618 1619 // This Remote Command does not have a Return-Value. 1620 return new Script<> 1621 (webSocketID, requestJSON, VOID_RETURN.NoReturnValues); 1622 } 1623 1624 /** 1625 * Set dock tile details, platform-specific. 1626 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B> 1627 * 1628 * @param badgeLabel - 1629 * <BR /><B CLASS=Opt>OPTIONAL</B> 1630 * 1631 * @param image Png encoded image. (Encoded as a base64 string when passed over JSON) 1632 * <BR /><B CLASS=Opt>OPTIONAL</B> 1633 * 1634 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1635 * {@link Ret0}></CODE> 1636 * 1637 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 1638 * browser receives the invocation-request. 1639 * 1640 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 1641 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 1642 * {@code >} to ensure the Browser Function has run to completion. 1643 */ 1644 public static Script<String, JsonObject, Ret0> setDockTile(String badgeLabel, String image) 1645 { 1646 final int webSocketID = 13016000 + counter++; 1647 final boolean[] optionals = { true, true, }; 1648 1649 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1650 String requestJSON = WriteJSON.get( 1651 parameterTypes.get("setDockTile"), 1652 parameterNames.get("setDockTile"), 1653 optionals, webSocketID, 1654 "Browser.setDockTile", 1655 badgeLabel, image 1656 ); 1657 1658 // This Remote Command does not have a Return-Value. 1659 return new Script<> 1660 (webSocketID, requestJSON, VOID_RETURN.NoReturnValues); 1661 } 1662 1663 /** 1664 * Invoke custom browser commands used by telemetry. 1665 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B> 1666 * 1667 * @param commandId - 1668 * 1669 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1670 * {@link Ret0}></CODE> 1671 * 1672 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 1673 * browser receives the invocation-request. 1674 * 1675 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 1676 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 1677 * {@code >} to ensure the Browser Function has run to completion. 1678 */ 1679 public static Script<String, JsonObject, Ret0> executeBrowserCommand(String commandId) 1680 { 1681 // Exception-Check(s) to ensure that if any parameters which are not declared as 1682 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 1683 1684 if (commandId == null) THROWS.throwNPE("commandId"); 1685 1686 // Exception-Check(s) to ensure that if any parameters which must adhere to a 1687 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 1688 1689 THROWS.checkIAE("commandId", commandId, "Browser.BrowserCommandId", Browser.BrowserCommandId); 1690 1691 final int webSocketID = 13017000 + counter++; 1692 final boolean[] optionals = { false, }; 1693 1694 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1695 String requestJSON = WriteJSON.get( 1696 parameterTypes.get("executeBrowserCommand"), 1697 parameterNames.get("executeBrowserCommand"), 1698 optionals, webSocketID, 1699 "Browser.executeBrowserCommand", 1700 commandId 1701 ); 1702 1703 // This Remote Command does not have a Return-Value. 1704 return new Script<> 1705 (webSocketID, requestJSON, VOID_RETURN.NoReturnValues); 1706 } 1707 1708 /** 1709 * Allows a site to use privacy sandbox features that require enrollment 1710 * without the site actually being enrolled. Only supported on page targets. 1711 * 1712 * @param url - 1713 * 1714 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1715 * {@link Ret0}></CODE> 1716 * 1717 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 1718 * browser receives the invocation-request. 1719 * 1720 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 1721 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 1722 * {@code >} to ensure the Browser Function has run to completion. 1723 */ 1724 public static Script<String, JsonObject, Ret0> addPrivacySandboxEnrollmentOverride 1725 (String url) 1726 { 1727 // Exception-Check(s) to ensure that if any parameters which are not declared as 1728 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 1729 1730 if (url == null) THROWS.throwNPE("url"); 1731 1732 final int webSocketID = 13018000 + counter++; 1733 final boolean[] optionals = { false, }; 1734 1735 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1736 String requestJSON = WriteJSON.get( 1737 parameterTypes.get("addPrivacySandboxEnrollmentOverride"), 1738 parameterNames.get("addPrivacySandboxEnrollmentOverride"), 1739 optionals, webSocketID, 1740 "Browser.addPrivacySandboxEnrollmentOverride", 1741 url 1742 ); 1743 1744 // This Remote Command does not have a Return-Value. 1745 return new Script<> 1746 (webSocketID, requestJSON, VOID_RETURN.NoReturnValues); 1747 } 1748 1749 /** 1750 * Configures encryption keys used with a given privacy sandbox API to talk 1751 * to a trusted coordinator. Since this is intended for test automation only, 1752 * coordinatorOrigin must be a .test domain. No existing coordinator 1753 * configuration for the origin may exist. 1754 * 1755 * @param api - 1756 * 1757 * @param coordinatorOrigin - 1758 * 1759 * @param keyConfig - 1760 * 1761 * @param browserContextId 1762 * BrowserContext to perform the action in. When omitted, default browser 1763 * context is used. 1764 * <BR /><B CLASS=Opt>OPTIONAL</B> 1765 * 1766 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1767 * {@link Ret0}></CODE> 1768 * 1769 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 1770 * browser receives the invocation-request. 1771 * 1772 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 1773 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 1774 * {@code >} to ensure the Browser Function has run to completion. 1775 */ 1776 public static Script<String, JsonObject, Ret0> addPrivacySandboxCoordinatorKeyConfig 1777 (String api, String coordinatorOrigin, String keyConfig, String browserContextId) 1778 { 1779 // Exception-Check(s) to ensure that if any parameters which are not declared as 1780 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 1781 1782 if (api == null) THROWS.throwNPE("api"); 1783 if (coordinatorOrigin == null) THROWS.throwNPE("coordinatorOrigin"); 1784 if (keyConfig == null) THROWS.throwNPE("keyConfig"); 1785 1786 // Exception-Check(s) to ensure that if any parameters which must adhere to a 1787 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 1788 1789 THROWS.checkIAE("api", api, "Browser.PrivacySandboxAPI", Browser.PrivacySandboxAPI); 1790 1791 final int webSocketID = 13019000 + counter++; 1792 final boolean[] optionals = { false, false, false, true, }; 1793 1794 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1795 String requestJSON = WriteJSON.get( 1796 parameterTypes.get("addPrivacySandboxCoordinatorKeyConfig"), 1797 parameterNames.get("addPrivacySandboxCoordinatorKeyConfig"), 1798 optionals, webSocketID, 1799 "Browser.addPrivacySandboxCoordinatorKeyConfig", 1800 api, coordinatorOrigin, keyConfig, browserContextId 1801 ); 1802 1803 // This Remote Command does not have a Return-Value. 1804 return new Script<> 1805 (webSocketID, requestJSON, VOID_RETURN.NoReturnValues); 1806 } 1807 1808}