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.*; 013 014import static Torello.Java.Additional.JFlag.*; 015 016import Torello.Java.StrCmpr; 017import Torello.JavaDoc.StaticFunctional; 018import Torello.JavaDoc.JDHeaderBackgroundImg; 019import Torello.JavaDoc.Excuse; 020 021/** 022 * <SPAN CLASS=CopiedJDK><B>A domain for letting clients substitute browser's network layer with client code.</B></SPAN> 023 * 024 * <EMBED CLASS='external-html' DATA-FILE-ID=CODE_GEN_NOTE> 025 */ 026@StaticFunctional(Excused={"counter"}, Excuses={Excuse.CONFIGURATION}) 027@JDHeaderBackgroundImg(EmbedTagFileID="WOOD_PLANK_NOTE") 028public class Fetch 029{ 030 // ******************************************************************************************** 031 // ******************************************************************************************** 032 // Class Header Stuff 033 // ******************************************************************************************** 034 // ******************************************************************************************** 035 036 037 // No Pubic Constructors 038 private Fetch () { } 039 040 // These two Vector's are used by all the "Methods" exported by this class. java.lang.reflect 041 // is used to generate the JSON String's. It saves thousands of lines of Auto-Generated Code. 042 private static final Map<String, Vector<String>> parameterNames = new HashMap<>(); 043 private static final Map<String, Vector<Class<?>>> parameterTypes = new HashMap<>(); 044 045 // Some Methods do not take any parameters - for instance all the "enable()" and "disable()" 046 // I simply could not get ride of RAW-TYPES and UNCHECKED warnings... so there are now, 047 // offically, two empty-vectors. One for String's, and the other for Classes. 048 049 private static final Vector<String> EMPTY_VEC_STR = new Vector<>(); 050 private static final Vector<Class<?>> EMPTY_VEC_CLASS = new Vector<>(); 051 052 static 053 { 054 for (Method m : Fetch.class.getMethods()) 055 { 056 // This doesn't work! The parameter names are all "arg0" ... "argN" 057 // It works for java.lang.reflect.Field, BUT NOT java.lang.reflect.Parameter! 058 // 059 // Vector<String> parameterNamesList = new Vector<>(); -- NOPE! 060 061 Vector<Class<?>> parameterTypesList = new Vector<>(); 062 063 for (Parameter p : m.getParameters()) parameterTypesList.add(p.getType()); 064 065 parameterTypes.put( 066 m.getName(), 067 (parameterTypesList.size() > 0) ? parameterTypesList : EMPTY_VEC_CLASS 068 ); 069 } 070 } 071 072 static 073 { 074 Vector<String> v = null; 075 076 parameterNames.put("disable", EMPTY_VEC_STR); 077 078 v = new Vector<String>(2); 079 parameterNames.put("enable", v); 080 Collections.addAll(v, new String[] 081 { "patterns", "handleAuthRequests", }); 082 083 v = new Vector<String>(2); 084 parameterNames.put("failRequest", v); 085 Collections.addAll(v, new String[] 086 { "requestId", "errorReason", }); 087 088 v = new Vector<String>(6); 089 parameterNames.put("fulfillRequest", v); 090 Collections.addAll(v, new String[] 091 { "requestId", "responseCode", "responseHeaders", "binaryResponseHeaders", "body", "responsePhrase", }); 092 093 v = new Vector<String>(6); 094 parameterNames.put("continueRequest", v); 095 Collections.addAll(v, new String[] 096 { "requestId", "url", "method", "postData", "headers", "interceptResponse", }); 097 098 v = new Vector<String>(2); 099 parameterNames.put("continueWithAuth", v); 100 Collections.addAll(v, new String[] 101 { "requestId", "authChallengeResponse", }); 102 103 v = new Vector<String>(5); 104 parameterNames.put("continueResponse", v); 105 Collections.addAll(v, new String[] 106 { "requestId", "responseCode", "responsePhrase", "responseHeaders", "binaryResponseHeaders", }); 107 108 v = new Vector<String>(1); 109 parameterNames.put("getResponseBody", v); 110 Collections.addAll(v, new String[] 111 { "requestId", }); 112 113 v = new Vector<String>(1); 114 parameterNames.put("takeResponseBodyAsStream", v); 115 Collections.addAll(v, new String[] 116 { "requestId", }); 117 } 118 119 120 // ******************************************************************************************** 121 // ******************************************************************************************** 122 // Types - Static Inner Classes 123 // ******************************************************************************************** 124 // ******************************************************************************************** 125 126 // public static class RequestId => String 127 128 /** 129 * Stages of the request to handle. Request will intercept before the request is 130 * sent. Response will intercept after the response is received (but before response 131 * body is received). 132 */ 133 public static final String[] RequestStage = 134 { "Request", "Response", }; 135 136 /** <CODE>[No Description Provided by Google]</CODE> */ 137 public static class RequestPattern extends BaseType 138 { 139 /** For Object Serialization. java.io.Serializable */ 140 protected static final long serialVersionUID = 1; 141 142 public boolean[] optionals() 143 { return new boolean[] { true, true, true, }; } 144 145 /** 146 * Wildcards (<CODE>'*'</CODE> -> zero or more, <CODE>'?'</CODE> -> exactly one) are allowed. Escape character is 147 * backslash. Omitting is equivalent to <CODE>"*"</CODE>. 148 * <BR /> 149 * <BR /><B>OPTIONAL</B> 150 */ 151 public final String urlPattern; 152 153 /** 154 * If set, only requests for matching resource types will be intercepted. 155 * <BR /> 156 * <BR /><B>OPTIONAL</B> 157 */ 158 public final String resourceType; 159 160 /** 161 * Stage at which to begin intercepting requests. Default is Request. 162 * <BR /> 163 * <BR /><B>OPTIONAL</B> 164 */ 165 public final String requestStage; 166 167 /** 168 * Constructor 169 * 170 * @param urlPattern 171 * Wildcards (<CODE>'*'</CODE> -> zero or more, <CODE>'?'</CODE> -> exactly one) are allowed. Escape character is 172 * backslash. Omitting is equivalent to <CODE>"*"</CODE>. 173 * <BR /><B>OPTIONAL</B> 174 * 175 * @param resourceType If set, only requests for matching resource types will be intercepted. 176 * <BR /><B>OPTIONAL</B> 177 * 178 * @param requestStage Stage at which to begin intercepting requests. Default is Request. 179 * <BR /><B>OPTIONAL</B> 180 */ 181 public RequestPattern(String urlPattern, String resourceType, String requestStage) 182 { 183 // Exception-Check(s) to ensure that if any parameters which must adhere to a 184 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 185 186 BRDPC.checkIAE("resourceType", resourceType, "Network.ResourceType", Network.ResourceType); 187 BRDPC.checkIAE("requestStage", requestStage, "Fetch.RequestStage", Fetch.RequestStage); 188 189 this.urlPattern = urlPattern; 190 this.resourceType = resourceType; 191 this.requestStage = requestStage; 192 } 193 194 /** 195 * JSON Object Constructor 196 * @param jo A Json-Object having data about an instance of {@code 'RequestPattern'}. 197 */ 198 public RequestPattern (JsonObject jo) 199 { 200 this.urlPattern = ReadJSON.getString(jo, "urlPattern", true, false); 201 this.resourceType = ReadJSON.getString(jo, "resourceType", true, false); 202 this.requestStage = ReadJSON.getString(jo, "requestStage", true, false); 203 } 204 205 } 206 207 /** Response HTTP header entry */ 208 public static class HeaderEntry extends BaseType 209 { 210 /** For Object Serialization. java.io.Serializable */ 211 protected static final long serialVersionUID = 1; 212 213 public boolean[] optionals() 214 { return new boolean[] { false, false, }; } 215 216 /** <CODE>[No Description Provided by Google]</CODE> */ 217 public final String name; 218 219 /** <CODE>[No Description Provided by Google]</CODE> */ 220 public final String value; 221 222 /** 223 * Constructor 224 * 225 * @param name - 226 * 227 * @param value - 228 */ 229 public HeaderEntry(String name, String value) 230 { 231 // Exception-Check(s) to ensure that if any parameters which are not declared as 232 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 233 234 if (name == null) BRDPC.throwNPE("name"); 235 if (value == null) BRDPC.throwNPE("value"); 236 237 this.name = name; 238 this.value = value; 239 } 240 241 /** 242 * JSON Object Constructor 243 * @param jo A Json-Object having data about an instance of {@code 'HeaderEntry'}. 244 */ 245 public HeaderEntry (JsonObject jo) 246 { 247 this.name = ReadJSON.getString(jo, "name", false, true); 248 this.value = ReadJSON.getString(jo, "value", false, true); 249 } 250 251 } 252 253 /** Authorization challenge for HTTP status code 401 or 407. */ 254 public static class AuthChallenge extends BaseType 255 { 256 /** For Object Serialization. java.io.Serializable */ 257 protected static final long serialVersionUID = 1; 258 259 public boolean[] optionals() 260 { return new boolean[] { true, false, false, false, }; } 261 262 /** 263 * Source of the authentication challenge. 264 * <BR /> 265 * <BR /><B>OPTIONAL</B> 266 */ 267 public final String source; 268 269 /** Origin of the challenger. */ 270 public final String origin; 271 272 /** The authentication scheme used, such as basic or digest */ 273 public final String scheme; 274 275 /** The realm of the challenge. May be empty. */ 276 public final String realm; 277 278 /** 279 * Constructor 280 * 281 * @param source Source of the authentication challenge. 282 * <BR />Acceptable Values: ["Server", "Proxy"] 283 * <BR /><B>OPTIONAL</B> 284 * 285 * @param origin Origin of the challenger. 286 * 287 * @param scheme The authentication scheme used, such as basic or digest 288 * 289 * @param realm The realm of the challenge. May be empty. 290 */ 291 public AuthChallenge(String source, String origin, String scheme, String realm) 292 { 293 // Exception-Check(s) to ensure that if any parameters which are not declared as 294 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 295 296 if (origin == null) BRDPC.throwNPE("origin"); 297 if (scheme == null) BRDPC.throwNPE("scheme"); 298 if (realm == null) BRDPC.throwNPE("realm"); 299 300 // Exception-Check(s) to ensure that if any parameters which must adhere to a 301 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 302 303 BRDPC.checkIAE( 304 "source", source, 305 "Server", "Proxy" 306 ); 307 308 this.source = source; 309 this.origin = origin; 310 this.scheme = scheme; 311 this.realm = realm; 312 } 313 314 /** 315 * JSON Object Constructor 316 * @param jo A Json-Object having data about an instance of {@code 'AuthChallenge'}. 317 */ 318 public AuthChallenge (JsonObject jo) 319 { 320 this.source = ReadJSON.getString(jo, "source", true, false); 321 this.origin = ReadJSON.getString(jo, "origin", false, true); 322 this.scheme = ReadJSON.getString(jo, "scheme", false, true); 323 this.realm = ReadJSON.getString(jo, "realm", false, true); 324 } 325 326 } 327 328 /** Response to an AuthChallenge. */ 329 public static class AuthChallengeResponse extends BaseType 330 { 331 /** For Object Serialization. java.io.Serializable */ 332 protected static final long serialVersionUID = 1; 333 334 public boolean[] optionals() 335 { return new boolean[] { false, true, true, }; } 336 337 /** 338 * The decision on what to do in response to the authorization challenge. Default means 339 * deferring to the default behavior of the net stack, which will likely either the Cancel 340 * authentication or display a popup dialog box. 341 */ 342 public final String response; 343 344 /** 345 * The username to provide, possibly empty. Should only be set if response is 346 * ProvideCredentials. 347 * <BR /> 348 * <BR /><B>OPTIONAL</B> 349 */ 350 public final String username; 351 352 /** 353 * The password to provide, possibly empty. Should only be set if response is 354 * ProvideCredentials. 355 * <BR /> 356 * <BR /><B>OPTIONAL</B> 357 */ 358 public final String password; 359 360 /** 361 * Constructor 362 * 363 * @param response 364 * The decision on what to do in response to the authorization challenge. Default means 365 * deferring to the default behavior of the net stack, which will likely either the Cancel 366 * authentication or display a popup dialog box. 367 * <BR />Acceptable Values: ["Default", "CancelAuth", "ProvideCredentials"] 368 * 369 * @param username 370 * The username to provide, possibly empty. Should only be set if response is 371 * ProvideCredentials. 372 * <BR /><B>OPTIONAL</B> 373 * 374 * @param password 375 * The password to provide, possibly empty. Should only be set if response is 376 * ProvideCredentials. 377 * <BR /><B>OPTIONAL</B> 378 */ 379 public AuthChallengeResponse(String response, String username, String password) 380 { 381 // Exception-Check(s) to ensure that if any parameters which are not declared as 382 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 383 384 if (response == null) BRDPC.throwNPE("response"); 385 386 // Exception-Check(s) to ensure that if any parameters which must adhere to a 387 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 388 389 BRDPC.checkIAE( 390 "response", response, 391 "Default", "CancelAuth", "ProvideCredentials" 392 ); 393 394 this.response = response; 395 this.username = username; 396 this.password = password; 397 } 398 399 /** 400 * JSON Object Constructor 401 * @param jo A Json-Object having data about an instance of {@code 'AuthChallengeResponse'}. 402 */ 403 public AuthChallengeResponse (JsonObject jo) 404 { 405 this.response = ReadJSON.getString(jo, "response", false, true); 406 this.username = ReadJSON.getString(jo, "username", true, false); 407 this.password = ReadJSON.getString(jo, "password", true, false); 408 } 409 410 } 411 412 /** 413 * Issued when the domain is enabled and the request URL matches the 414 * specified filter. The request is paused until the client responds 415 * with one of continueRequest, failRequest or fulfillRequest. 416 * The stage of the request can be determined by presence of responseErrorReason 417 * and responseStatusCode -- the request is at the response stage if either 418 * of these fields is present and in the request stage otherwise. 419 */ 420 public static class requestPaused extends BrowserEvent 421 { 422 /** For Object Serialization. java.io.Serializable */ 423 protected static final long serialVersionUID = 1; 424 425 public boolean[] optionals() 426 { return new boolean[] { false, false, false, false, true, true, true, true, true, }; } 427 428 /** Each request the page makes will have a unique id. */ 429 public final String requestId; 430 431 /** The details of the request. */ 432 public final Network.Request request; 433 434 /** The id of the frame that initiated the request. */ 435 public final String frameId; 436 437 /** How the requested resource will be used. */ 438 public final String resourceType; 439 440 /** 441 * Response error if intercepted at response stage. 442 * <BR /> 443 * <BR /><B>OPTIONAL</B> 444 */ 445 public final String responseErrorReason; 446 447 /** 448 * Response code if intercepted at response stage. 449 * <BR /> 450 * <BR /><B>OPTIONAL</B> 451 */ 452 public final Integer responseStatusCode; 453 454 /** 455 * Response status text if intercepted at response stage. 456 * <BR /> 457 * <BR /><B>OPTIONAL</B> 458 */ 459 public final String responseStatusText; 460 461 /** 462 * Response headers if intercepted at the response stage. 463 * <BR /> 464 * <BR /><B>OPTIONAL</B> 465 */ 466 public final Fetch.HeaderEntry[] responseHeaders; 467 468 /** 469 * If the intercepted request had a corresponding Network.requestWillBeSent event fired for it, 470 * then this networkId will be the same as the requestId present in the requestWillBeSent event. 471 * <BR /> 472 * <BR /><B>OPTIONAL</B> 473 */ 474 public final String networkId; 475 476 /** 477 * Constructor 478 * 479 * @param requestId Each request the page makes will have a unique id. 480 * 481 * @param request The details of the request. 482 * 483 * @param frameId The id of the frame that initiated the request. 484 * 485 * @param resourceType How the requested resource will be used. 486 * 487 * @param responseErrorReason Response error if intercepted at response stage. 488 * <BR /><B>OPTIONAL</B> 489 * 490 * @param responseStatusCode Response code if intercepted at response stage. 491 * <BR /><B>OPTIONAL</B> 492 * 493 * @param responseStatusText Response status text if intercepted at response stage. 494 * <BR /><B>OPTIONAL</B> 495 * 496 * @param responseHeaders Response headers if intercepted at the response stage. 497 * <BR /><B>OPTIONAL</B> 498 * 499 * @param networkId 500 * If the intercepted request had a corresponding Network.requestWillBeSent event fired for it, 501 * then this networkId will be the same as the requestId present in the requestWillBeSent event. 502 * <BR /><B>OPTIONAL</B> 503 */ 504 public requestPaused( 505 String requestId, Network.Request request, String frameId, String resourceType, 506 String responseErrorReason, Integer responseStatusCode, String responseStatusText, 507 Fetch.HeaderEntry[] responseHeaders, String networkId 508 ) 509 { 510 super("Fetch", "requestPaused", 9); 511 512 // Exception-Check(s) to ensure that if any parameters which are not declared as 513 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 514 515 if (requestId == null) BRDPC.throwNPE("requestId"); 516 if (request == null) BRDPC.throwNPE("request"); 517 if (frameId == null) BRDPC.throwNPE("frameId"); 518 if (resourceType == null) BRDPC.throwNPE("resourceType"); 519 520 // Exception-Check(s) to ensure that if any parameters which must adhere to a 521 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 522 523 BRDPC.checkIAE("resourceType", resourceType, "Network.ResourceType", Network.ResourceType); 524 BRDPC.checkIAE("responseErrorReason", responseErrorReason, "Network.ErrorReason", Network.ErrorReason); 525 526 this.requestId = requestId; 527 this.request = request; 528 this.frameId = frameId; 529 this.resourceType = resourceType; 530 this.responseErrorReason = responseErrorReason; 531 this.responseStatusCode = responseStatusCode; 532 this.responseStatusText = responseStatusText; 533 this.responseHeaders = responseHeaders; 534 this.networkId = networkId; 535 } 536 537 /** 538 * JSON Object Constructor 539 * @param jo A Json-Object having data about an instance of {@code 'requestPaused'}. 540 */ 541 public requestPaused (JsonObject jo) 542 { 543 super("Fetch", "requestPaused", 9); 544 545 this.requestId = ReadJSON.getString(jo, "requestId", false, true); 546 this.request = ReadJSON.XL.getObject(jo, "request", Network.Request.class, false, true); 547 this.frameId = ReadJSON.getString(jo, "frameId", false, true); 548 this.resourceType = ReadJSON.getString(jo, "resourceType", false, true); 549 this.responseErrorReason = ReadJSON.getString(jo, "responseErrorReason", true, false); 550 this.responseStatusCode = ReadJSON.getINTEGER(jo, "responseStatusCode", true); 551 this.responseStatusText = ReadJSON.getString(jo, "responseStatusText", true, false); 552 this.responseHeaders = (jo.getJsonArray("responseHeaders") == null) 553 ? null 554 : ReadArrJSON.DimN.objArr(jo.getJsonArray("responseHeaders"), null, 0, Fetch.HeaderEntry[].class); 555 this.networkId = ReadJSON.getString(jo, "networkId", true, false); 556 } 557 558 } 559 560 /** 561 * Issued when the domain is enabled with handleAuthRequests set to true. 562 * The request is paused until client responds with continueWithAuth. 563 */ 564 public static class authRequired extends BrowserEvent 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, false, }; } 571 572 /** Each request the page makes will have a unique id. */ 573 public final String requestId; 574 575 /** The details of the request. */ 576 public final Network.Request request; 577 578 /** The id of the frame that initiated the request. */ 579 public final String frameId; 580 581 /** How the requested resource will be used. */ 582 public final String resourceType; 583 584 /** 585 * Details of the Authorization Challenge encountered. 586 * If this is set, client should respond with continueRequest that 587 * contains AuthChallengeResponse. 588 */ 589 public final Fetch.AuthChallenge authChallenge; 590 591 /** 592 * Constructor 593 * 594 * @param requestId Each request the page makes will have a unique id. 595 * 596 * @param request The details of the request. 597 * 598 * @param frameId The id of the frame that initiated the request. 599 * 600 * @param resourceType How the requested resource will be used. 601 * 602 * @param authChallenge 603 * Details of the Authorization Challenge encountered. 604 * If this is set, client should respond with continueRequest that 605 * contains AuthChallengeResponse. 606 */ 607 public authRequired( 608 String requestId, Network.Request request, String frameId, String resourceType, 609 Fetch.AuthChallenge authChallenge 610 ) 611 { 612 super("Fetch", "authRequired", 5); 613 614 // Exception-Check(s) to ensure that if any parameters which are not declared as 615 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 616 617 if (requestId == null) BRDPC.throwNPE("requestId"); 618 if (request == null) BRDPC.throwNPE("request"); 619 if (frameId == null) BRDPC.throwNPE("frameId"); 620 if (resourceType == null) BRDPC.throwNPE("resourceType"); 621 if (authChallenge == null) BRDPC.throwNPE("authChallenge"); 622 623 // Exception-Check(s) to ensure that if any parameters which must adhere to a 624 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 625 626 BRDPC.checkIAE("resourceType", resourceType, "Network.ResourceType", Network.ResourceType); 627 628 this.requestId = requestId; 629 this.request = request; 630 this.frameId = frameId; 631 this.resourceType = resourceType; 632 this.authChallenge = authChallenge; 633 } 634 635 /** 636 * JSON Object Constructor 637 * @param jo A Json-Object having data about an instance of {@code 'authRequired'}. 638 */ 639 public authRequired (JsonObject jo) 640 { 641 super("Fetch", "authRequired", 5); 642 643 this.requestId = ReadJSON.getString(jo, "requestId", false, true); 644 this.request = ReadJSON.XL.getObject(jo, "request", Network.Request.class, false, true); 645 this.frameId = ReadJSON.getString(jo, "frameId", false, true); 646 this.resourceType = ReadJSON.getString(jo, "resourceType", false, true); 647 this.authChallenge = ReadJSON.XL.getObject(jo, "authChallenge", Fetch.AuthChallenge.class, false, true); 648 } 649 650 } 651 652 653 // Counter for keeping the WebSocket Request ID's distinct. 654 private static int counter = 1; 655 656 /** 657 * Disables the fetch domain. 658 * 659 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 660 * {@link Ret0}></CODE> 661 * 662 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 663 * browser receives the invocation-request. 664 * 665 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 666 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 667 * {@code >} to ensure the Browser Function has run to completion. 668 */ 669 public static Script<String, JsonObject, Ret0> disable() 670 { 671 final int webSocketID = 42000000 + counter++; 672 final boolean[] optionals = new boolean[0]; 673 674 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 675 String requestJSON = WriteJSON.get( 676 parameterTypes.get("disable"), 677 parameterNames.get("disable"), 678 optionals, webSocketID, 679 "Fetch.disable" 680 ); 681 682 // This Remote Command does not have a Return-Value. 683 return new Script<> 684 (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues); 685 } 686 687 /** 688 * Enables issuing of requestPaused events. A request will be paused until client 689 * calls one of failRequest, fulfillRequest or continueRequest/continueWithAuth. 690 * 691 * @param patterns 692 * If specified, only requests matching any of these patterns will produce 693 * fetchRequested event and will be paused until clients response. If not set, 694 * all requests will be affected. 695 * <BR /><B>OPTIONAL</B> 696 * 697 * @param handleAuthRequests 698 * If true, authRequired events will be issued and requests will be paused 699 * expecting a call to continueWithAuth. 700 * <BR /><B>OPTIONAL</B> 701 * 702 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 703 * {@link Ret0}></CODE> 704 * 705 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 706 * browser receives the invocation-request. 707 * 708 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 709 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 710 * {@code >} to ensure the Browser Function has run to completion. 711 */ 712 public static Script<String, JsonObject, Ret0> enable 713 (Fetch.RequestPattern[] patterns, Boolean handleAuthRequests) 714 { 715 final int webSocketID = 42001000 + counter++; 716 final boolean[] optionals = { true, true, }; 717 718 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 719 String requestJSON = WriteJSON.get( 720 parameterTypes.get("enable"), 721 parameterNames.get("enable"), 722 optionals, webSocketID, 723 "Fetch.enable", 724 patterns, handleAuthRequests 725 ); 726 727 // This Remote Command does not have a Return-Value. 728 return new Script<> 729 (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues); 730 } 731 732 /** 733 * Causes the request to fail with specified reason. 734 * 735 * @param requestId An id the client received in requestPaused event. 736 * 737 * @param errorReason Causes the request to fail with the given reason. 738 * 739 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 740 * {@link Ret0}></CODE> 741 * 742 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 743 * browser receives the invocation-request. 744 * 745 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 746 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 747 * {@code >} to ensure the Browser Function has run to completion. 748 */ 749 public static Script<String, JsonObject, Ret0> failRequest 750 (String requestId, String errorReason) 751 { 752 // Exception-Check(s) to ensure that if any parameters which are not declared as 753 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 754 755 if (requestId == null) BRDPC.throwNPE("requestId"); 756 if (errorReason == null) BRDPC.throwNPE("errorReason"); 757 758 // Exception-Check(s) to ensure that if any parameters which must adhere to a 759 // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw. 760 761 BRDPC.checkIAE("errorReason", errorReason, "Network.ErrorReason", Network.ErrorReason); 762 763 final int webSocketID = 42002000 + counter++; 764 final boolean[] optionals = { false, false, }; 765 766 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 767 String requestJSON = WriteJSON.get( 768 parameterTypes.get("failRequest"), 769 parameterNames.get("failRequest"), 770 optionals, webSocketID, 771 "Fetch.failRequest", 772 requestId, errorReason 773 ); 774 775 // This Remote Command does not have a Return-Value. 776 return new Script<> 777 (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues); 778 } 779 780 /** 781 * Provides response to the request. 782 * 783 * @param requestId An id the client received in requestPaused event. 784 * 785 * @param responseCode An HTTP response code. 786 * 787 * @param responseHeaders Response headers. 788 * <BR /><B>OPTIONAL</B> 789 * 790 * @param binaryResponseHeaders 791 * Alternative way of specifying response headers as a \0-separated 792 * series of name: value pairs. Prefer the above method unless you 793 * need to represent some non-UTF8 values that can't be transmitted 794 * over the protocol as text. (Encoded as a base64 string when passed over JSON) 795 * <BR /><B>OPTIONAL</B> 796 * 797 * @param body 798 * A response body. If absent, original response body will be used if 799 * the request is intercepted at the response stage and empty body 800 * will be used if the request is intercepted at the request stage. (Encoded as a base64 string when passed over JSON) 801 * <BR /><B>OPTIONAL</B> 802 * 803 * @param responsePhrase 804 * A textual representation of responseCode. 805 * If absent, a standard phrase matching responseCode is used. 806 * <BR /><B>OPTIONAL</B> 807 * 808 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 809 * {@link Ret0}></CODE> 810 * 811 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 812 * browser receives the invocation-request. 813 * 814 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 815 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 816 * {@code >} to ensure the Browser Function has run to completion. 817 */ 818 public static Script<String, JsonObject, Ret0> fulfillRequest( 819 String requestId, int responseCode, Fetch.HeaderEntry[] responseHeaders, 820 String binaryResponseHeaders, String body, String responsePhrase 821 ) 822 { 823 // Exception-Check(s) to ensure that if any parameters which are not declared as 824 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 825 826 if (requestId == null) BRDPC.throwNPE("requestId"); 827 828 final int webSocketID = 42003000 + counter++; 829 final boolean[] optionals = { false, false, true, true, true, true, }; 830 831 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 832 String requestJSON = WriteJSON.get( 833 parameterTypes.get("fulfillRequest"), 834 parameterNames.get("fulfillRequest"), 835 optionals, webSocketID, 836 "Fetch.fulfillRequest", 837 requestId, responseCode, responseHeaders, binaryResponseHeaders, body, responsePhrase 838 ); 839 840 // This Remote Command does not have a Return-Value. 841 return new Script<> 842 (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues); 843 } 844 845 /** 846 * Continues the request, optionally modifying some of its parameters. 847 * 848 * @param requestId An id the client received in requestPaused event. 849 * 850 * @param url If set, the request url will be modified in a way that's not observable by page. 851 * <BR /><B>OPTIONAL</B> 852 * 853 * @param method If set, the request method is overridden. 854 * <BR /><B>OPTIONAL</B> 855 * 856 * @param postData If set, overrides the post data in the request. (Encoded as a base64 string when passed over JSON) 857 * <BR /><B>OPTIONAL</B> 858 * 859 * @param headers If set, overrides the request headers. 860 * <BR /><B>OPTIONAL</B> 861 * 862 * @param interceptResponse If set, overrides response interception behavior for this request. 863 * <BR /><B>OPTIONAL</B> 864 * <BR /><B>EXPERIMENTAL</B> 865 * 866 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 867 * {@link Ret0}></CODE> 868 * 869 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 870 * browser receives the invocation-request. 871 * 872 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 873 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 874 * {@code >} to ensure the Browser Function has run to completion. 875 */ 876 public static Script<String, JsonObject, Ret0> continueRequest( 877 String requestId, String url, String method, String postData, 878 Fetch.HeaderEntry[] headers, Boolean interceptResponse 879 ) 880 { 881 // Exception-Check(s) to ensure that if any parameters which are not declared as 882 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 883 884 if (requestId == null) BRDPC.throwNPE("requestId"); 885 886 final int webSocketID = 42004000 + counter++; 887 final boolean[] optionals = { false, true, true, true, true, true, }; 888 889 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 890 String requestJSON = WriteJSON.get( 891 parameterTypes.get("continueRequest"), 892 parameterNames.get("continueRequest"), 893 optionals, webSocketID, 894 "Fetch.continueRequest", 895 requestId, url, method, postData, headers, interceptResponse 896 ); 897 898 // This Remote Command does not have a Return-Value. 899 return new Script<> 900 (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues); 901 } 902 903 /** 904 * Continues a request supplying authChallengeResponse following authRequired event. 905 * 906 * @param requestId An id the client received in authRequired event. 907 * 908 * @param authChallengeResponse Response to with an authChallenge. 909 * 910 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 911 * {@link Ret0}></CODE> 912 * 913 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 914 * browser receives the invocation-request. 915 * 916 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 917 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 918 * {@code >} to ensure the Browser Function has run to completion. 919 */ 920 public static Script<String, JsonObject, Ret0> continueWithAuth 921 (String requestId, Fetch.AuthChallengeResponse authChallengeResponse) 922 { 923 // Exception-Check(s) to ensure that if any parameters which are not declared as 924 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 925 926 if (requestId == null) BRDPC.throwNPE("requestId"); 927 if (authChallengeResponse == null) BRDPC.throwNPE("authChallengeResponse"); 928 929 final int webSocketID = 42005000 + counter++; 930 final boolean[] optionals = { false, false, }; 931 932 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 933 String requestJSON = WriteJSON.get( 934 parameterTypes.get("continueWithAuth"), 935 parameterNames.get("continueWithAuth"), 936 optionals, webSocketID, 937 "Fetch.continueWithAuth", 938 requestId, authChallengeResponse 939 ); 940 941 // This Remote Command does not have a Return-Value. 942 return new Script<> 943 (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues); 944 } 945 946 /** 947 * Continues loading of the paused response, optionally modifying the 948 * response headers. If either responseCode or headers are modified, all of them 949 * must be present. 950 * <BR /><B>EXPERIMENTAL</B> 951 * 952 * @param requestId An id the client received in requestPaused event. 953 * 954 * @param responseCode An HTTP response code. If absent, original response code will be used. 955 * <BR /><B>OPTIONAL</B> 956 * 957 * @param responsePhrase 958 * A textual representation of responseCode. 959 * If absent, a standard phrase matching responseCode is used. 960 * <BR /><B>OPTIONAL</B> 961 * 962 * @param responseHeaders Response headers. If absent, original response headers will be used. 963 * <BR /><B>OPTIONAL</B> 964 * 965 * @param binaryResponseHeaders 966 * Alternative way of specifying response headers as a \0-separated 967 * series of name: value pairs. Prefer the above method unless you 968 * need to represent some non-UTF8 values that can't be transmitted 969 * over the protocol as text. (Encoded as a base64 string when passed over JSON) 970 * <BR /><B>OPTIONAL</B> 971 * 972 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 973 * {@link Ret0}></CODE> 974 * 975 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 976 * browser receives the invocation-request. 977 * 978 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 979 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 980 * {@code >} to ensure the Browser Function has run to completion. 981 */ 982 public static Script<String, JsonObject, Ret0> continueResponse( 983 String requestId, Integer responseCode, String responsePhrase, 984 Fetch.HeaderEntry[] responseHeaders, String binaryResponseHeaders 985 ) 986 { 987 // Exception-Check(s) to ensure that if any parameters which are not declared as 988 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 989 990 if (requestId == null) BRDPC.throwNPE("requestId"); 991 992 final int webSocketID = 42006000 + counter++; 993 final boolean[] optionals = { false, true, true, true, true, }; 994 995 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 996 String requestJSON = WriteJSON.get( 997 parameterTypes.get("continueResponse"), 998 parameterNames.get("continueResponse"), 999 optionals, webSocketID, 1000 "Fetch.continueResponse", 1001 requestId, responseCode, responsePhrase, responseHeaders, binaryResponseHeaders 1002 ); 1003 1004 // This Remote Command does not have a Return-Value. 1005 return new Script<> 1006 (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues); 1007 } 1008 1009 /** 1010 * Causes the body of the response to be received from the server and 1011 * returned as a single string. May only be issued for a request that 1012 * is paused in the Response stage and is mutually exclusive with 1013 * takeResponseBodyForInterceptionAsStream. Calling other methods that 1014 * affect the request or disabling fetch domain before body is received 1015 * results in an undefined behavior. 1016 * 1017 * @param requestId Identifier for the intercepted request to get body for. 1018 * 1019 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1020 * {@link Ret2}></CODE> 1021 * 1022 * <BR /><BR />This {@link Script} may be <B STYLE='color:red'>executed</B> (using 1023 * {@link Script#exec()}), and a {@link Promise} returned. 1024 * 1025 * <BR /><BR />When the {@code Promise} is <B STYLE='color: red'>awaited</B> 1026 * (using {@link Promise#await()}), the {@code Ret2} will subsequently 1027 * be returned from that call. 1028 * 1029 * <BR /><BR />The <B STYLE='color: red'>returned</B> values are encapsulated 1030 * in an instance of <B>{@link Ret2}</B> 1031 * 1032 * <BR /><BR /><UL CLASS=JDUL> 1033 * <LI><CODE><B>Ret2.a:</B> String (<B>body</B>)</CODE> 1034 * <BR />Response body. 1035 * <BR /><BR /></LI> 1036 * <LI><CODE><B>Ret2.b:</B> Boolean (<B>base64Encoded</B>)</CODE> 1037 * <BR />True, if content was sent as base64. 1038 * </LI> 1039 * </UL> 1040 */ 1041 public static Script<String, JsonObject, Ret2<String, Boolean>> getResponseBody 1042 (String requestId) 1043 { 1044 // Exception-Check(s) to ensure that if any parameters which are not declared as 1045 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 1046 1047 if (requestId == null) BRDPC.throwNPE("requestId"); 1048 1049 final int webSocketID = 42007000 + counter++; 1050 final boolean[] optionals = { false, }; 1051 1052 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1053 String requestJSON = WriteJSON.get( 1054 parameterTypes.get("getResponseBody"), 1055 parameterNames.get("getResponseBody"), 1056 optionals, webSocketID, 1057 "Fetch.getResponseBody", 1058 requestId 1059 ); 1060 1061 // 'JSON Binding' ... Converts Browser Response-JSON into Java-Type 'Ret2' 1062 Function<JsonObject, Ret2<String, Boolean>> 1063 responseProcessor = (JsonObject jo) -> new Ret2<>( 1064 ReadJSON.getString(jo, "body", false, true), 1065 ReadJSON.getBOOLEAN(jo, "base64Encoded", true) 1066 ); 1067 1068 // Pass the 'defaultSender' to Script-Constructor 1069 // The sender that is used can be changed before executing script. 1070 return new Script<>(BRDPC.defaultSender, webSocketID, requestJSON, responseProcessor); 1071 } 1072 1073 /** 1074 * Returns a handle to the stream representing the response body. 1075 * The request must be paused in the HeadersReceived stage. 1076 * Note that after this command the request can't be continued 1077 * as is -- client either needs to cancel it or to provide the 1078 * response body. 1079 * The stream only supports sequential read, IO.read will fail if the position 1080 * is specified. 1081 * This method is mutually exclusive with getResponseBody. 1082 * Calling other methods that affect the request or disabling fetch 1083 * domain before body is received results in an undefined behavior. 1084 * 1085 * @param requestId - 1086 * 1087 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 1088 * String></CODE> 1089 * 1090 * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using 1091 * {@link Script#exec()}, and afterwards, a {@link Promise}<CODE><JsonObject, 1092 * String></CODE> will be returned. 1093 * 1094 * <BR /><BR />Finally, the <B>{@code Promise}</B> may be <B STYLE='color: red'>awaited</B>, 1095 * using {@link Promise#await()}, <I>and the returned result of this Browser Function may 1096 * may be retrieved.</I> 1097 * 1098 * <BR /><BR />This Browser Function <B STYLE='color: red'>returns</B> 1099 * <BR /><BR /><UL CLASS=JDUL> 1100 * <LI><CODE>String (<B>stream</B></CODE>) 1101 * <BR />- 1102 * </LI> 1103 * </UL> */ 1104 public static Script<String, JsonObject, String> takeResponseBodyAsStream(String requestId) 1105 { 1106 // Exception-Check(s) to ensure that if any parameters which are not declared as 1107 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 1108 1109 if (requestId == null) BRDPC.throwNPE("requestId"); 1110 1111 final int webSocketID = 42008000 + counter++; 1112 final boolean[] optionals = { false, }; 1113 1114 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 1115 String requestJSON = WriteJSON.get( 1116 parameterTypes.get("takeResponseBodyAsStream"), 1117 parameterNames.get("takeResponseBodyAsStream"), 1118 optionals, webSocketID, 1119 "Fetch.takeResponseBodyAsStream", 1120 requestId 1121 ); 1122 1123 // 'JSON Binding' ... Converts Browser Response-JSON to 'String' 1124 Function<JsonObject, String> responseProcessor = (JsonObject jo) -> 1125 ReadJSON.getString(jo, "stream", false, true); 1126 1127 // Pass the 'defaultSender' to Script-Constructor 1128 // The sender that is used can be changed before executing script. 1129 return new Script<>(BRDPC.defaultSender, webSocketID, requestJSON, responseProcessor); 1130 } 1131 1132}