Source code

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}&lt;String, {@link JsonObject},
382     * {@link Ret0}&gt;</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}&lt;String, {@link JsonObject},
419     * {@link Ret0}&gt;</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}&lt;String, {@link JsonObject},
450     * {@link Ret0}&gt;</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}&lt;String, {@link JsonObject},
483     * String[][]&gt;</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>&lt;JsonObject,
487     * String[][]&gt;</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}&lt;String, {@link JsonObject},
538     * {@link Ret0}&gt;</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}&lt;String, {@link JsonObject},
583     * {@link Ret0}&gt;</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}