001package Torello.Browser.BrowserAPI; 002 003// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 004// Java-HTML Imports 005// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 006 007import Torello.Browser.*; 008import Torello.Browser.helper.*; 009import Torello.Browser.JavaScriptAPI.*; 010import Torello.JSON.*; 011 012import Torello.Java.ReadOnly.ReadOnlyList; 013import Torello.Java.ReadOnly.ReadOnlyArrayList; 014 015import Torello.JavaDoc.Annotations.StaticFunctional; 016import Torello.JavaDoc.Annotations.JDHeaderBackgroundImg; 017 018import Torello.Browser.BrowserAPI.NestedHelpers.Commands.DOMDebugger$$Commands; 019 020 021// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 022// JDK Imports 023// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 024 025import javax.json.JsonObject; 026import javax.json.JsonValue; 027 028/** 029 * <SPAN CLASS=COPIEDJDK><B>DOM debugging allows setting breakpoints on particular DOM operations and events. JavaScript 030 * execution will stop on these operations as if there was a regular breakpoint set.</B></SPAN> 031 * <EMBED CLASS='external-html' DATA-FILE-ID=CDP.CODE_GEN_NOTE> 032 */ 033@StaticFunctional@JDHeaderBackgroundImg(EmbedTagFileID="CDP.WOOD_PLANK_NOTE") 034public class DOMDebugger 035{ 036 // No Pubic Constructors 037 private DOMDebugger() { } 038 039 040 // ******************************************************************************************** 041 // ******************************************************************************************** 042 // Enumerated String Constants Lists 043 // ******************************************************************************************** 044 // ******************************************************************************************** 045 046 047 /** 048 * CSP Violation type. 049 * 050 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B> 051 * <BR /><BR /><B CLASS=StrEnumType>String-Enumeration Type</B> 052 */ 053 public static final ReadOnlyList<String> CSPViolationType = new ReadOnlyArrayList<> 054 (String.class, "trustedtype-policy-violation", "trustedtype-sink-violation"); 055 056 /** 057 * DOM breakpoint type. 058 * <BR /><BR /><B CLASS=StrEnumType>String-Enumeration Type</B> 059 */ 060 public static final ReadOnlyList<String> DOMBreakpointType = new ReadOnlyArrayList<> 061 (String.class, "attribute-modified", "node-removed", "subtree-modified"); 062 063 064 065 // ******************************************************************************************** 066 // ******************************************************************************************** 067 // Basic Types 068 // ******************************************************************************************** 069 // ******************************************************************************************** 070 071 072 /** 073 * Object event listener. 074 * 075 * <EMBED CLASS=globalDefs DATA-DOMAIN=DOMDebugger DATA-API=BrowserAPI> 076 */ 077 @JDHeaderBackgroundImg(EmbedTagFileID="CDP.NESTED_TYPE_JDHBI") 078 public static class EventListener 079 extends BaseType<EventListener> 080 implements java.io.Serializable 081 { 082 /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */ 083 protected static final long serialVersionUID = 1; 084 085 private static final NestedHelper<DOMDebugger.EventListener> singleton = 086 Torello.Browser.BrowserAPI.NestedHelpers.Types. 087 DOMDebugger$$EventListener$$.singleton; 088 089 /** <CODE>EventListener</CODE>'s type. */ 090 public final String type; 091 092 /** <CODE>EventListener</CODE>'s useCapture. */ 093 public final boolean useCapture; 094 095 /** <CODE>EventListener</CODE>'s passive flag. */ 096 public final boolean passive; 097 098 /** <CODE>EventListener</CODE>'s once flag. */ 099 public final boolean once; 100 101 /** Script id of the handler code. */ 102 public final String scriptId; 103 104 /** Line number in the script (0-based). */ 105 public final int lineNumber; 106 107 /** Column number in the script (0-based). */ 108 public final int columnNumber; 109 110 /** 111 * Event handler function value. 112 * <BR /><B CLASS=Opt-Top>OPTIONAL</B> 113 */ 114 public final RunTime.RemoteObject handler; 115 116 /** 117 * Event original handler function value. 118 * <BR /><B CLASS=Opt-Top>OPTIONAL</B> 119 */ 120 public final RunTime.RemoteObject originalHandler; 121 122 /** 123 * Node the listener is added to (if any). 124 * <BR /><B CLASS=Opt-Top>OPTIONAL</B> 125 */ 126 public final Integer backendNodeId; 127 128 /** Constructor. Please review this class' fields for documentation. */ 129 public EventListener( 130 ReadOnlyList<Boolean> isPresent, String type, boolean useCapture, boolean passive, 131 boolean once, String scriptId, int lineNumber, int columnNumber, 132 RunTime.RemoteObject handler, RunTime.RemoteObject originalHandler, 133 Integer backendNodeId 134 ) 135 { 136 super(singleton, Domains.DOMDebugger, "EventListener", 10); 137 138 this.type = type; 139 this.useCapture = useCapture; 140 this.passive = passive; 141 this.once = once; 142 this.scriptId = scriptId; 143 this.lineNumber = lineNumber; 144 this.columnNumber = columnNumber; 145 this.handler = handler; 146 this.originalHandler = originalHandler; 147 this.backendNodeId = backendNodeId; 148 149 this.isPresent = (isPresent == null) 150 ? singleton.generateIsPresentList(this) 151 : THROWS.check(isPresent, 10, "DOMDebugger.EventListener"); 152 } 153 154 /** Creates an instance of this class from a {@link JsonObject}.*/ 155 public static EventListener fromJSON(JsonObject jo) 156 { return singleton.fromJSON(jo); } 157 158 /** Returns this class's {@link NestedDescriptor} singleton-instance. class / type.*/ 159 public static NestedDescriptor<EventListener> descriptor() 160 { return singleton.descriptor(); } 161 } 162 163 164 165 166 // ******************************************************************************************** 167 // ******************************************************************************************** 168 // Commands 169 // ******************************************************************************************** 170 // ******************************************************************************************** 171 172 173 /** 174 * Returns event listeners of the given object. 175 * 176 * @param objectId Identifier of the object to return listeners for. 177 * 178 * @param depth 179 * The maximum depth at which Node children should be retrieved, defaults to 1. Use -1 for the 180 * entire subtree or provide an integer larger than 0. 181 * <BR /><B CLASS=Opt-Top>OPTIONAL</B> 182 * 183 * @param pierce 184 * Whether or not iframes and shadow roots should be traversed when returning the subtree 185 * (default is false). Reports listeners for all contexts if pierce is enabled. 186 * <BR /><B CLASS=Opt-Top>OPTIONAL</B> 187 * 188 * @return An instance of <CODE>{@link Script}<{@link DOMDebugger.EventListener}[]></CODE> 189 * 190 * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using 191 * {@link Script#exec(WebSocketSender) Script.exec}, and afterwards, a {@link Promise} 192 * <CODE><{@link DOMDebugger.EventListener}[]></CODE> will be returned 193 * 194 * <BR /><BR />Finally, the <B>{@code Promise}</B> may be <B STYLE='color: red'>awaited</B>, 195 * using {@link Promise#await()}, <I>and the returned result of this Browser Function may 196 * be retrieved.</I> 197 * 198 * <BR /><BR /><DIV CLASS=JDHint> 199 * This Browser Function's {@code Promise} returns: 200 * <CODE>{@link DOMDebugger.EventListener}[] (<B>listeners</B>)</CODE> 201 * <BR /> 202 * Array of relevant listeners. 203 * </DIV> 204 */ 205 public static Script<DOMDebugger.EventListener[]> getEventListeners 206 (String objectId, Integer depth, Boolean pierce) 207 { 208 // Convert all Method Parameters into a JSON Request-Object (as a String) 209 final String requestJSON = WriteJSON.get( 210 DOMDebugger$$Commands.getEventListeners$$, "DOMDebugger.getEventListeners", 211 objectId, depth, pierce 212 ); 213 214 return new Script<>( 215 Domains.DOMDebugger, "getEventListeners", requestJSON, 216 DOMDebugger$$Commands::getEventListeners, 217 DOMDebugger.EventListener[].class 218 ); 219 } 220 221 /** 222 * Removes DOM breakpoint that was set using <CODE>setDOMBreakpoint</CODE>. 223 * 224 * @param nodeId Identifier of the node to remove breakpoint from. 225 * 226 * @param type Type of the breakpoint to remove. 227 * 228 * @return An instance of <CODE>{@link Script}<Void></CODE> 229 * 230 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 231 * browser receives the invocation-request. 232 * 233 * <BR /><BR /><DIV CLASS=JDHint> 234 * This Browser-Function <I>does not have</I> a return-value. You may choose to 235 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <Void>} to ensure that 236 * the Browser Function has run to completion. 237 * </DIV> 238 */ 239 public static Script<Void> removeDOMBreakpoint(int nodeId, String type) 240 { 241 // Convert all Method Parameters into a JSON Request-Object (as a String) 242 final String requestJSON = WriteJSON.get( 243 DOMDebugger$$Commands.removeDOMBreakpoint$$, "DOMDebugger.removeDOMBreakpoint", 244 nodeId, type 245 ); 246 247 return Script.NO_RET(Domains.DOMDebugger, "removeDOMBreakpoint", requestJSON); 248 } 249 250 /** 251 * Removes breakpoint on particular DOM event. 252 * 253 * @param eventName Event name. 254 * 255 * @param targetName EventTarget interface name. 256 * <BR /><B CLASS=Opt-Top>OPTIONAL</B><B CLASS=Exp-Top>EXPERIMENTAL</B> 257 * 258 * @return An instance of <CODE>{@link Script}<Void></CODE> 259 * 260 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 261 * browser receives the invocation-request. 262 * 263 * <BR /><BR /><DIV CLASS=JDHint> 264 * This Browser-Function <I>does not have</I> a return-value. You may choose to 265 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <Void>} to ensure that 266 * the Browser Function has run to completion. 267 * </DIV> 268 */ 269 public static Script<Void> removeEventListenerBreakpoint(String eventName, String targetName) 270 { 271 // Convert all Method Parameters into a JSON Request-Object (as a String) 272 final String requestJSON = WriteJSON.get( 273 DOMDebugger$$Commands.removeEventListenerBreakpoint$$, 274 "DOMDebugger.removeEventListenerBreakpoint", 275 eventName, targetName 276 ); 277 278 return Script.NO_RET(Domains.DOMDebugger, "removeEventListenerBreakpoint", requestJSON); 279 } 280 281 /** 282 * Removes breakpoint on particular native event. 283 * 284 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B><B CLASS=Dep-Top>DEPRECATED</B> 285 * 286 * @param eventName Instrumentation name to stop on. 287 * 288 * @return An instance of <CODE>{@link Script}<Void></CODE> 289 * 290 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 291 * browser receives the invocation-request. 292 * 293 * <BR /><BR /><DIV CLASS=JDHint> 294 * This Browser-Function <I>does not have</I> a return-value. You may choose to 295 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <Void>} to ensure that 296 * the Browser Function has run to completion. 297 * </DIV> 298 */ 299 public static Script<Void> removeInstrumentationBreakpoint(String eventName) 300 { 301 // Build the JSON Request-Object (as a String); only 1 Parameter is passed 302 final String requestJSON = WriteJSON.get( 303 CDPTypes.STRING, "eventName", false, "DOMDebugger.removeInstrumentationBreakpoint", 304 eventName 305 ); 306 307 return Script.NO_RET(Domains.DOMDebugger, "removeInstrumentationBreakpoint", requestJSON); 308 } 309 310 /** 311 * Removes breakpoint from XMLHttpRequest. 312 * 313 * @param url Resource URL substring. 314 * 315 * @return An instance of <CODE>{@link Script}<Void></CODE> 316 * 317 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 318 * browser receives the invocation-request. 319 * 320 * <BR /><BR /><DIV CLASS=JDHint> 321 * This Browser-Function <I>does not have</I> a return-value. You may choose to 322 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <Void>} to ensure that 323 * the Browser Function has run to completion. 324 * </DIV> 325 */ 326 public static Script<Void> removeXHRBreakpoint(String url) 327 { 328 // Build the JSON Request-Object (as a String); only 1 Parameter is passed 329 final String requestJSON = WriteJSON.get 330 (CDPTypes.STRING, "url", false, "DOMDebugger.removeXHRBreakpoint", url); 331 332 return Script.NO_RET(Domains.DOMDebugger, "removeXHRBreakpoint", requestJSON); 333 } 334 335 /** 336 * Sets breakpoint on particular CSP violations. 337 * 338 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B> 339 * 340 * @param violationTypes CSP Violations to stop upon. 341 * 342 * @return An instance of <CODE>{@link Script}<Void></CODE> 343 * 344 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 345 * browser receives the invocation-request. 346 * 347 * <BR /><BR /><DIV CLASS=JDHint> 348 * This Browser-Function <I>does not have</I> a return-value. You may choose to 349 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <Void>} to ensure that 350 * the Browser Function has run to completion. 351 * </DIV> 352 */ 353 public static Script<Void> setBreakOnCSPViolation(String[] violationTypes) 354 { 355 // Build the JSON Request-Object (as a String); only 1 Parameter is passed 356 final String requestJSON = WriteJSON.get( 357 CDPTypes.STRING_ARRAY_1D, "violationTypes", false, 358 "DOMDebugger.setBreakOnCSPViolation", (Object) violationTypes 359 ); 360 361 return Script.NO_RET(Domains.DOMDebugger, "setBreakOnCSPViolation", requestJSON); 362 } 363 364 /** 365 * Sets breakpoint on particular operation with DOM. 366 * 367 * @param nodeId Identifier of the node to set breakpoint on. 368 * 369 * @param type Type of the operation to stop upon. 370 * 371 * @return An instance of <CODE>{@link Script}<Void></CODE> 372 * 373 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 374 * browser receives the invocation-request. 375 * 376 * <BR /><BR /><DIV CLASS=JDHint> 377 * This Browser-Function <I>does not have</I> a return-value. You may choose to 378 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <Void>} to ensure that 379 * the Browser Function has run to completion. 380 * </DIV> 381 */ 382 public static Script<Void> setDOMBreakpoint(int nodeId, String type) 383 { 384 // Convert all Method Parameters into a JSON Request-Object (as a String) 385 final String requestJSON = WriteJSON.get( 386 DOMDebugger$$Commands.setDOMBreakpoint$$, "DOMDebugger.setDOMBreakpoint", 387 nodeId, type 388 ); 389 390 return Script.NO_RET(Domains.DOMDebugger, "setDOMBreakpoint", requestJSON); 391 } 392 393 /** 394 * Sets breakpoint on particular DOM event. 395 * 396 * @param eventName DOM Event name to stop on (any DOM event will do). 397 * 398 * @param targetName 399 * EventTarget interface name to stop on. If equal to <CODE>"*"</CODE> or not provided, will stop on any 400 * EventTarget. 401 * <BR /><B CLASS=Opt-Top>OPTIONAL</B><B CLASS=Exp-Top>EXPERIMENTAL</B> 402 * 403 * @return An instance of <CODE>{@link Script}<Void></CODE> 404 * 405 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 406 * browser receives the invocation-request. 407 * 408 * <BR /><BR /><DIV CLASS=JDHint> 409 * This Browser-Function <I>does not have</I> a return-value. You may choose to 410 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <Void>} to ensure that 411 * the Browser Function has run to completion. 412 * </DIV> 413 */ 414 public static Script<Void> setEventListenerBreakpoint(String eventName, String targetName) 415 { 416 // Convert all Method Parameters into a JSON Request-Object (as a String) 417 final String requestJSON = WriteJSON.get( 418 DOMDebugger$$Commands.setEventListenerBreakpoint$$, 419 "DOMDebugger.setEventListenerBreakpoint", 420 eventName, targetName 421 ); 422 423 return Script.NO_RET(Domains.DOMDebugger, "setEventListenerBreakpoint", requestJSON); 424 } 425 426 /** 427 * Sets breakpoint on particular native event. 428 * 429 * <BR /><B CLASS=Exp-Top>EXPERIMENTAL</B><B CLASS=Dep-Top>DEPRECATED</B> 430 * 431 * @param eventName Instrumentation name to stop on. 432 * 433 * @return An instance of <CODE>{@link Script}<Void></CODE> 434 * 435 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 436 * browser receives the invocation-request. 437 * 438 * <BR /><BR /><DIV CLASS=JDHint> 439 * This Browser-Function <I>does not have</I> a return-value. You may choose to 440 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <Void>} to ensure that 441 * the Browser Function has run to completion. 442 * </DIV> 443 */ 444 public static Script<Void> setInstrumentationBreakpoint(String eventName) 445 { 446 // Build the JSON Request-Object (as a String); only 1 Parameter is passed 447 final String requestJSON = WriteJSON.get( 448 CDPTypes.STRING, "eventName", false, "DOMDebugger.setInstrumentationBreakpoint", 449 eventName 450 ); 451 452 return Script.NO_RET(Domains.DOMDebugger, "setInstrumentationBreakpoint", requestJSON); 453 } 454 455 /** 456 * Sets breakpoint on XMLHttpRequest. 457 * 458 * @param url Resource URL substring. All XHRs having this substring in the URL will get stopped upon. 459 * 460 * @return An instance of <CODE>{@link Script}<Void></CODE> 461 * 462 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 463 * browser receives the invocation-request. 464 * 465 * <BR /><BR /><DIV CLASS=JDHint> 466 * This Browser-Function <I>does not have</I> a return-value. You may choose to 467 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <Void>} to ensure that 468 * the Browser Function has run to completion. 469 * </DIV> 470 */ 471 public static Script<Void> setXHRBreakpoint(String url) 472 { 473 // Build the JSON Request-Object (as a String); only 1 Parameter is passed 474 final String requestJSON = WriteJSON.get 475 (CDPTypes.STRING, "url", false, "DOMDebugger.setXHRBreakpoint", url); 476 477 return Script.NO_RET(Domains.DOMDebugger, "setXHRBreakpoint", requestJSON); 478 } 479 480 481}