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>Query and modify DOM storage.</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 DOMStorage 029{ 030 // ******************************************************************************************** 031 // ******************************************************************************************** 032 // Class Header Stuff 033 // ******************************************************************************************** 034 // ******************************************************************************************** 035 036 037 // No Pubic Constructors 038 private DOMStorage () { } 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 : DOMStorage.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 v = new Vector<String>(1); 077 parameterNames.put("clear", v); 078 Collections.addAll(v, new String[] 079 { "storageId", }); 080 081 parameterNames.put("disable", EMPTY_VEC_STR); 082 083 parameterNames.put("enable", EMPTY_VEC_STR); 084 085 v = new Vector<String>(1); 086 parameterNames.put("getDOMStorageItems", v); 087 Collections.addAll(v, new String[] 088 { "storageId", }); 089 090 v = new Vector<String>(2); 091 parameterNames.put("removeDOMStorageItem", v); 092 Collections.addAll(v, new String[] 093 { "storageId", "key", }); 094 095 v = new Vector<String>(3); 096 parameterNames.put("setDOMStorageItem", v); 097 Collections.addAll(v, new String[] 098 { "storageId", "key", "value", }); 099 } 100 101 102 // ******************************************************************************************** 103 // ******************************************************************************************** 104 // Types - Static Inner Classes 105 // ******************************************************************************************** 106 // ******************************************************************************************** 107 108 // public static class Item => String[] 109 110 /** DOM Storage identifier. */ 111 public static class StorageId extends BaseType 112 { 113 /** For Object Serialization. java.io.Serializable */ 114 protected static final long serialVersionUID = 1; 115 116 public boolean[] optionals() 117 { return new boolean[] { false, false, }; } 118 119 /** Security origin for the storage. */ 120 public final String securityOrigin; 121 122 /** Whether the storage is local storage (not session storage). */ 123 public final boolean isLocalStorage; 124 125 /** 126 * Constructor 127 * 128 * @param securityOrigin Security origin for the storage. 129 * 130 * @param isLocalStorage Whether the storage is local storage (not session storage). 131 */ 132 public StorageId(String securityOrigin, boolean isLocalStorage) 133 { 134 // Exception-Check(s) to ensure that if any parameters which are not declared as 135 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 136 137 if (securityOrigin == null) BRDPC.throwNPE("securityOrigin"); 138 139 this.securityOrigin = securityOrigin; 140 this.isLocalStorage = isLocalStorage; 141 } 142 143 /** 144 * JSON Object Constructor 145 * @param jo A Json-Object having data about an instance of {@code 'StorageId'}. 146 */ 147 public StorageId (JsonObject jo) 148 { 149 this.securityOrigin = ReadJSON.getString(jo, "securityOrigin", false, true); 150 this.isLocalStorage = ReadJSON.getBoolean(jo, "isLocalStorage"); 151 } 152 153 } 154 155 /** <CODE>[No Description Provided by Google]</CODE> */ 156 public static class domStorageItemAdded extends BrowserEvent 157 { 158 /** For Object Serialization. java.io.Serializable */ 159 protected static final long serialVersionUID = 1; 160 161 public boolean[] optionals() 162 { return new boolean[] { false, false, false, }; } 163 164 /** <CODE>[No Description Provided by Google]</CODE> */ 165 public final DOMStorage.StorageId storageId; 166 167 /** <CODE>[No Description Provided by Google]</CODE> */ 168 public final String key; 169 170 /** <CODE>[No Description Provided by Google]</CODE> */ 171 public final String newValue; 172 173 /** 174 * Constructor 175 * 176 * @param storageId - 177 * 178 * @param key - 179 * 180 * @param newValue - 181 */ 182 public domStorageItemAdded(DOMStorage.StorageId storageId, String key, String newValue) 183 { 184 super("DOMStorage", "domStorageItemAdded", 3); 185 186 // Exception-Check(s) to ensure that if any parameters which are not declared as 187 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 188 189 if (storageId == null) BRDPC.throwNPE("storageId"); 190 if (key == null) BRDPC.throwNPE("key"); 191 if (newValue == null) BRDPC.throwNPE("newValue"); 192 193 this.storageId = storageId; 194 this.key = key; 195 this.newValue = newValue; 196 } 197 198 /** 199 * JSON Object Constructor 200 * @param jo A Json-Object having data about an instance of {@code 'domStorageItemAdded'}. 201 */ 202 public domStorageItemAdded (JsonObject jo) 203 { 204 super("DOMStorage", "domStorageItemAdded", 3); 205 206 this.storageId = ReadJSON.XL.getObject(jo, "storageId", DOMStorage.StorageId.class, false, true); 207 this.key = ReadJSON.getString(jo, "key", false, true); 208 this.newValue = ReadJSON.getString(jo, "newValue", false, true); 209 } 210 211 } 212 213 /** <CODE>[No Description Provided by Google]</CODE> */ 214 public static class domStorageItemRemoved extends BrowserEvent 215 { 216 /** For Object Serialization. java.io.Serializable */ 217 protected static final long serialVersionUID = 1; 218 219 public boolean[] optionals() 220 { return new boolean[] { false, false, }; } 221 222 /** <CODE>[No Description Provided by Google]</CODE> */ 223 public final DOMStorage.StorageId storageId; 224 225 /** <CODE>[No Description Provided by Google]</CODE> */ 226 public final String key; 227 228 /** 229 * Constructor 230 * 231 * @param storageId - 232 * 233 * @param key - 234 */ 235 public domStorageItemRemoved(DOMStorage.StorageId storageId, String key) 236 { 237 super("DOMStorage", "domStorageItemRemoved", 2); 238 239 // Exception-Check(s) to ensure that if any parameters which are not declared as 240 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 241 242 if (storageId == null) BRDPC.throwNPE("storageId"); 243 if (key == null) BRDPC.throwNPE("key"); 244 245 this.storageId = storageId; 246 this.key = key; 247 } 248 249 /** 250 * JSON Object Constructor 251 * @param jo A Json-Object having data about an instance of {@code 'domStorageItemRemoved'}. 252 */ 253 public domStorageItemRemoved (JsonObject jo) 254 { 255 super("DOMStorage", "domStorageItemRemoved", 2); 256 257 this.storageId = ReadJSON.XL.getObject(jo, "storageId", DOMStorage.StorageId.class, false, true); 258 this.key = ReadJSON.getString(jo, "key", false, true); 259 } 260 261 } 262 263 /** <CODE>[No Description Provided by Google]</CODE> */ 264 public static class domStorageItemUpdated extends BrowserEvent 265 { 266 /** For Object Serialization. java.io.Serializable */ 267 protected static final long serialVersionUID = 1; 268 269 public boolean[] optionals() 270 { return new boolean[] { false, false, false, false, }; } 271 272 /** <CODE>[No Description Provided by Google]</CODE> */ 273 public final DOMStorage.StorageId storageId; 274 275 /** <CODE>[No Description Provided by Google]</CODE> */ 276 public final String key; 277 278 /** <CODE>[No Description Provided by Google]</CODE> */ 279 public final String oldValue; 280 281 /** <CODE>[No Description Provided by Google]</CODE> */ 282 public final String newValue; 283 284 /** 285 * Constructor 286 * 287 * @param storageId - 288 * 289 * @param key - 290 * 291 * @param oldValue - 292 * 293 * @param newValue - 294 */ 295 public domStorageItemUpdated 296 (DOMStorage.StorageId storageId, String key, String oldValue, String newValue) 297 { 298 super("DOMStorage", "domStorageItemUpdated", 4); 299 300 // Exception-Check(s) to ensure that if any parameters which are not declared as 301 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 302 303 if (storageId == null) BRDPC.throwNPE("storageId"); 304 if (key == null) BRDPC.throwNPE("key"); 305 if (oldValue == null) BRDPC.throwNPE("oldValue"); 306 if (newValue == null) BRDPC.throwNPE("newValue"); 307 308 this.storageId = storageId; 309 this.key = key; 310 this.oldValue = oldValue; 311 this.newValue = newValue; 312 } 313 314 /** 315 * JSON Object Constructor 316 * @param jo A Json-Object having data about an instance of {@code 'domStorageItemUpdated'}. 317 */ 318 public domStorageItemUpdated (JsonObject jo) 319 { 320 super("DOMStorage", "domStorageItemUpdated", 4); 321 322 this.storageId = ReadJSON.XL.getObject(jo, "storageId", DOMStorage.StorageId.class, false, true); 323 this.key = ReadJSON.getString(jo, "key", false, true); 324 this.oldValue = ReadJSON.getString(jo, "oldValue", false, true); 325 this.newValue = ReadJSON.getString(jo, "newValue", false, true); 326 } 327 328 } 329 330 /** <CODE>[No Description Provided by Google]</CODE> */ 331 public static class domStorageItemsCleared extends BrowserEvent 332 { 333 /** For Object Serialization. java.io.Serializable */ 334 protected static final long serialVersionUID = 1; 335 336 public boolean[] optionals() 337 { return new boolean[] { false, }; } 338 339 /** <CODE>[No Description Provided by Google]</CODE> */ 340 public final DOMStorage.StorageId storageId; 341 342 /** 343 * Constructor 344 * 345 * @param storageId - 346 */ 347 public domStorageItemsCleared(DOMStorage.StorageId storageId) 348 { 349 super("DOMStorage", "domStorageItemsCleared", 1); 350 351 // Exception-Check(s) to ensure that if any parameters which are not declared as 352 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 353 354 if (storageId == null) BRDPC.throwNPE("storageId"); 355 356 this.storageId = storageId; 357 } 358 359 /** 360 * JSON Object Constructor 361 * @param jo A Json-Object having data about an instance of {@code 'domStorageItemsCleared'}. 362 */ 363 public domStorageItemsCleared (JsonObject jo) 364 { 365 super("DOMStorage", "domStorageItemsCleared", 1); 366 367 this.storageId = ReadJSON.XL.getObject(jo, "storageId", DOMStorage.StorageId.class, false, true); 368 } 369 370 } 371 372 373 // Counter for keeping the WebSocket Request ID's distinct. 374 private static int counter = 1; 375 376 /** 377 * <CODE>[No Description Provided by Google]</CODE> 378 * 379 * @param storageId - 380 * 381 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 382 * {@link Ret0}></CODE> 383 * 384 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 385 * browser receives the invocation-request. 386 * 387 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 388 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 389 * {@code >} to ensure the Browser Function has run to completion. 390 */ 391 public static Script<String, JsonObject, Ret0> clear(DOMStorage.StorageId storageId) 392 { 393 // Exception-Check(s) to ensure that if any parameters which are not declared as 394 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 395 396 if (storageId == null) BRDPC.throwNPE("storageId"); 397 398 final int webSocketID = 18000000 + counter++; 399 final boolean[] optionals = { false, }; 400 401 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 402 String requestJSON = WriteJSON.get( 403 parameterTypes.get("clear"), 404 parameterNames.get("clear"), 405 optionals, webSocketID, 406 "DOMStorage.clear", 407 storageId 408 ); 409 410 // This Remote Command does not have a Return-Value. 411 return new Script<> 412 (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues); 413 } 414 415 /** 416 * Disables storage tracking, prevents storage events from being sent to the client. 417 * 418 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 419 * {@link Ret0}></CODE> 420 * 421 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 422 * browser receives the invocation-request. 423 * 424 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 425 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 426 * {@code >} to ensure the Browser Function has run to completion. 427 */ 428 public static Script<String, JsonObject, Ret0> disable() 429 { 430 final int webSocketID = 18001000 + counter++; 431 final boolean[] optionals = new boolean[0]; 432 433 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 434 String requestJSON = WriteJSON.get( 435 parameterTypes.get("disable"), 436 parameterNames.get("disable"), 437 optionals, webSocketID, 438 "DOMStorage.disable" 439 ); 440 441 // This Remote Command does not have a Return-Value. 442 return new Script<> 443 (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues); 444 } 445 446 /** 447 * Enables storage tracking, storage events will now be delivered to the client. 448 * 449 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 450 * {@link Ret0}></CODE> 451 * 452 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 453 * browser receives the invocation-request. 454 * 455 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 456 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 457 * {@code >} to ensure the Browser Function has run to completion. 458 */ 459 public static Script<String, JsonObject, Ret0> enable() 460 { 461 final int webSocketID = 18002000 + counter++; 462 final boolean[] optionals = new boolean[0]; 463 464 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 465 String requestJSON = WriteJSON.get( 466 parameterTypes.get("enable"), 467 parameterNames.get("enable"), 468 optionals, webSocketID, 469 "DOMStorage.enable" 470 ); 471 472 // This Remote Command does not have a Return-Value. 473 return new Script<> 474 (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues); 475 } 476 477 /** 478 * <CODE>[No Description Provided by Google]</CODE> 479 * 480 * @param storageId - 481 * 482 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 483 * String[][]></CODE> 484 * 485 * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using 486 * {@link Script#exec()}, and afterwards, a {@link Promise}<CODE><JsonObject, 487 * String[][]></CODE> will be returned. 488 * 489 * <BR /><BR />Finally, the <B>{@code Promise}</B> may be <B STYLE='color: red'>awaited</B>, 490 * using {@link Promise#await()}, <I>and the returned result of this Browser Function may 491 * may be retrieved.</I> 492 * 493 * <BR /><BR />This Browser Function <B STYLE='color: red'>returns</B> 494 * <BR /><BR /><UL CLASS=JDUL> 495 * <LI><CODE>String[][] (<B>entries</B></CODE>) 496 * <BR />- 497 * </LI> 498 * </UL> */ 499 public static Script<String, JsonObject, String[][]> getDOMStorageItems 500 (DOMStorage.StorageId storageId) 501 { 502 // Exception-Check(s) to ensure that if any parameters which are not declared as 503 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 504 505 if (storageId == null) BRDPC.throwNPE("storageId"); 506 507 final int webSocketID = 18003000 + counter++; 508 final boolean[] optionals = { false, }; 509 510 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 511 String requestJSON = WriteJSON.get( 512 parameterTypes.get("getDOMStorageItems"), 513 parameterNames.get("getDOMStorageItems"), 514 optionals, webSocketID, 515 "DOMStorage.getDOMStorageItems", 516 storageId 517 ); 518 519 // 'JSON Binding' ... Converts Browser Response-JSON to 'String[][]' 520 Function<JsonObject, String[][]> responseProcessor = (JsonObject jo) -> 521 (jo.getJsonArray("entries") == null) 522 ? null 523 : ReadArrJSON.DimN.strArr(jo.getJsonArray("entries"), null, 0, String[][].class); 524 525 // Pass the 'defaultSender' to Script-Constructor 526 // The sender that is used can be changed before executing script. 527 return new Script<>(BRDPC.defaultSender, webSocketID, requestJSON, responseProcessor); 528 } 529 530 /** 531 * <CODE>[No Description Provided by Google]</CODE> 532 * 533 * @param storageId - 534 * 535 * @param key - 536 * 537 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 538 * {@link Ret0}></CODE> 539 * 540 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 541 * browser receives the invocation-request. 542 * 543 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 544 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 545 * {@code >} to ensure the Browser Function has run to completion. 546 */ 547 public static Script<String, JsonObject, Ret0> removeDOMStorageItem 548 (DOMStorage.StorageId storageId, String key) 549 { 550 // Exception-Check(s) to ensure that if any parameters which are not declared as 551 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 552 553 if (storageId == null) BRDPC.throwNPE("storageId"); 554 if (key == null) BRDPC.throwNPE("key"); 555 556 final int webSocketID = 18004000 + counter++; 557 final boolean[] optionals = { false, false, }; 558 559 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 560 String requestJSON = WriteJSON.get( 561 parameterTypes.get("removeDOMStorageItem"), 562 parameterNames.get("removeDOMStorageItem"), 563 optionals, webSocketID, 564 "DOMStorage.removeDOMStorageItem", 565 storageId, key 566 ); 567 568 // This Remote Command does not have a Return-Value. 569 return new Script<> 570 (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues); 571 } 572 573 /** 574 * <CODE>[No Description Provided by Google]</CODE> 575 * 576 * @param storageId - 577 * 578 * @param key - 579 * 580 * @param value - 581 * 582 * @return An instance of <CODE>{@link Script}<String, {@link JsonObject}, 583 * {@link Ret0}></CODE> 584 * 585 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 586 * browser receives the invocation-request. 587 * 588 * <BR /><BR />This Browser-Function <I>does not have</I> a return-value. You may choose to 589 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0} 590 * {@code >} to ensure the Browser Function has run to completion. 591 */ 592 public static Script<String, JsonObject, Ret0> setDOMStorageItem 593 (DOMStorage.StorageId storageId, String key, String value) 594 { 595 // Exception-Check(s) to ensure that if any parameters which are not declared as 596 // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw. 597 598 if (storageId == null) BRDPC.throwNPE("storageId"); 599 if (key == null) BRDPC.throwNPE("key"); 600 if (value == null) BRDPC.throwNPE("value"); 601 602 final int webSocketID = 18005000 + counter++; 603 final boolean[] optionals = { false, false, false, }; 604 605 // Convert Method Parameters into JSON. Build the JSON Request-Object (as a String) 606 String requestJSON = WriteJSON.get( 607 parameterTypes.get("setDOMStorageItem"), 608 parameterNames.get("setDOMStorageItem"), 609 optionals, webSocketID, 610 "DOMStorage.setDOMStorageItem", 611 storageId, key, value 612 ); 613 614 // This Remote Command does not have a Return-Value. 615 return new Script<> 616 (BRDPC.defaultSender, webSocketID, requestJSON, BRDPC.NoReturnValues); 617 } 618 619}