001package Torello.Browser.JavaScriptAPI;
002
003import java.util.*;
004import javax.json.*;
005import javax.json.stream.*;
006import java.io.*;
007
008import java.lang.reflect.Method;
009import java.lang.reflect.Parameter;
010import java.util.function.Function;
011
012import Torello.Browser.BrowserEvent;
013import Torello.Browser.BrowserAPI.*;
014import Torello.Browser.helper.*;
015
016import Torello.Java.Additional.*;
017import Torello.Java.JSON.*;
018
019import static Torello.Java.JSON.JFlag.*;
020
021import Torello.Java.StrCmpr;
022import Torello.JavaDoc.StaticFunctional;
023import Torello.JavaDoc.JDHeaderBackgroundImg;
024import Torello.JavaDoc.Excuse;
025
026/**
027 * <SPAN CLASS=COPIEDJDK><B>This domain is deprecated - use RunTime or Log instead.</B></SPAN>
028 * 
029 * <EMBED CLASS='external-html' DATA-FILE-ID=CODE_GEN_NOTE>
030 */
031@StaticFunctional(Excused={"counter"}, Excuses={Excuse.CONFIGURATION})
032@JDHeaderBackgroundImg(EmbedTagFileID="WOOD_PLANK_NOTE")
033public class Console
034{
035    // ********************************************************************************************
036    // ********************************************************************************************
037    // Class Header Stuff
038    // ********************************************************************************************
039    // ********************************************************************************************
040
041
042    // No Pubic Constructors
043    private Console () { }
044
045    // These two Vector's are used by all the "Methods" exported by this class.  java.lang.reflect
046    // is used to generate the JSON String's.  It saves thousands of lines of Auto-Generated Code.
047    private static final Map<String, Vector<String>>    parameterNames = new HashMap<>();
048    private static final Map<String, Vector<Class<?>>>  parameterTypes = new HashMap<>();
049
050    // Some Methods do not take any parameters - for instance all the "enable()" and "disable()"
051    // I simply could not get ride of RAW-TYPES and UNCHECKED warnings... so there are now,
052    // offically, two empty-vectors.  One for String's, and the other for Classes.
053
054    private static final Vector<String>     EMPTY_VEC_STR = new Vector<>();
055    private static final Vector<Class<?>>   EMPTY_VEC_CLASS = new Vector<>();
056
057    static
058    {
059        for (Method m : Console.class.getMethods())
060        {
061            // This doesn't work!  The parameter names are all "arg0" ... "argN"
062            // It works for java.lang.reflect.Field, BUT NOT java.lang.reflect.Parameter!
063            //
064            // Vector<String> parameterNamesList = new Vector<>(); -- NOPE!
065
066            Vector<Class<?>> parameterTypesList = new Vector<>();
067        
068            for (Parameter p : m.getParameters()) parameterTypesList.add(p.getType());
069
070            parameterTypes.put(
071                m.getName(),
072                (parameterTypesList.size() > 0) ? parameterTypesList : EMPTY_VEC_CLASS
073            );
074        }
075    }
076
077    static
078    {
079        Vector<String> v = null;
080
081        parameterNames.put("clearMessages", EMPTY_VEC_STR);
082
083        parameterNames.put("disable", EMPTY_VEC_STR);
084
085        parameterNames.put("enable", EMPTY_VEC_STR);
086    }
087
088
089    // ********************************************************************************************
090    // ********************************************************************************************
091    // Types - Static Inner Classes
092    // ********************************************************************************************
093    // ********************************************************************************************
094
095    /** Console message. */
096    public static class ConsoleMessage
097        extends BaseType
098        implements java.io.Serializable
099    {
100        /** For Object Serialization.  java.io.Serializable */
101        protected static final long serialVersionUID = 1;
102        
103        public boolean[] optionals()
104        { return new boolean[] { false, false, false, true, true, true, }; }
105        
106        /** Message source. */
107        public final String source;
108        
109        /** Message severity. */
110        public final String level;
111        
112        /** Message text. */
113        public final String text;
114        
115        /**
116         * URL of the message origin.
117         * <BR /><B CLASS=Opt>OPTIONAL</B>
118         */
119        public final String url;
120        
121        /**
122         * Line number in the resource that generated this message (1-based).
123         * <BR /><B CLASS=Opt>OPTIONAL</B>
124         */
125        public final Integer line;
126        
127        /**
128         * Column number in the resource that generated this message (1-based).
129         * <BR /><B CLASS=Opt>OPTIONAL</B>
130         */
131        public final Integer column;
132        
133        /**
134         * Constructor
135         *
136         * @param source Message source.
137         * <BR />Acceptable Values: ["xml", "javascript", "network", "console-api", "storage", "appcache", "rendering", "security", "other", "deprecation", "worker"]
138         * 
139         * @param level Message severity.
140         * <BR />Acceptable Values: ["log", "warning", "error", "debug", "info"]
141         * 
142         * @param text Message text.
143         * 
144         * @param url URL of the message origin.
145         * <BR /><B CLASS=Opt>OPTIONAL</B>
146         * 
147         * @param line Line number in the resource that generated this message (1-based).
148         * <BR /><B CLASS=Opt>OPTIONAL</B>
149         * 
150         * @param column Column number in the resource that generated this message (1-based).
151         * <BR /><B CLASS=Opt>OPTIONAL</B>
152         */
153        public ConsoleMessage
154            (String source, String level, String text, String url, Integer line, Integer column)
155        {
156            // Exception-Check(s) to ensure that if any parameters which are not declared as
157            // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
158            
159            if (source == null) THROWS.throwNPE("source");
160            if (level == null)  THROWS.throwNPE("level");
161            if (text == null)   THROWS.throwNPE("text");
162            
163            // Exception-Check(s) to ensure that if any parameters which must adhere to a
164            // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw.
165            
166            THROWS.checkIAE(
167                "source", source,
168                "xml", "javascript", "network", "console-api", "storage", "appcache", "rendering", "security", "other", "deprecation", "worker"
169            );
170            THROWS.checkIAE(
171                "level", level,
172                "log", "warning", "error", "debug", "info"
173            );
174            
175            this.source  = source;
176            this.level   = level;
177            this.text    = text;
178            this.url     = url;
179            this.line    = line;
180            this.column  = column;
181        }
182        
183        /**
184         * JSON Object Constructor
185         * @param jo A Json-Object having data about an instance of {@code 'ConsoleMessage'}.
186         */
187        public ConsoleMessage (JsonObject jo)
188        {
189            this.source  = ReadJSON.getString(jo, "source", false, true);
190            this.level   = ReadJSON.getString(jo, "level", false, true);
191            this.text    = ReadJSON.getString(jo, "text", false, true);
192            this.url     = ReadJSON.getString(jo, "url", true, false);
193            this.line    = ReadBoxedJSON.getInteger(jo, "line", true);
194            this.column  = ReadBoxedJSON.getInteger(jo, "column", true);
195        }
196        
197        
198        /** Checks whether {@code 'this'} equals an input Java-{@code Object} */
199        public boolean equals(Object other)
200        {
201            if (this == other)                       return true;
202            if (other == null)                       return false;
203            if (other.getClass() != this.getClass()) return false;
204        
205            ConsoleMessage o = (ConsoleMessage) other;
206        
207            return
208                    Objects.equals(this.source, o.source)
209                &&  Objects.equals(this.level, o.level)
210                &&  Objects.equals(this.text, o.text)
211                &&  Objects.equals(this.url, o.url)
212                &&  Objects.equals(this.line, o.line)
213                &&  Objects.equals(this.column, o.column);
214        }
215        
216        /** Generates a Hash-Code for {@code 'this'} instance */
217        public int hashCode()
218        {
219            return
220                    Objects.hashCode(this.source)
221                +   Objects.hashCode(this.level)
222                +   Objects.hashCode(this.text)
223                +   Objects.hashCode(this.url)
224                +   Objects.hashCode(this.line)
225                +   Objects.hashCode(this.column);
226        }
227    }
228    
229    /** Issued when new console message is added. */
230    public static class messageAdded
231        extends BrowserEvent
232        implements java.io.Serializable
233    {
234        /** For Object Serialization.  java.io.Serializable */
235        protected static final long serialVersionUID = 1;
236        
237        public boolean[] optionals()
238        { return new boolean[] { false, }; }
239        
240        /** Console message that has been added. */
241        public final Console.ConsoleMessage message;
242        
243        /**
244         * Constructor
245         *
246         * @param message Console message that has been added.
247         */
248        public messageAdded(Console.ConsoleMessage message)
249        {
250            super("Console", "messageAdded", 1);
251            
252            // Exception-Check(s) to ensure that if any parameters which are not declared as
253            // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
254            
255            if (message == null) THROWS.throwNPE("message");
256            
257            this.message  = message;
258        }
259        
260        /**
261         * JSON Object Constructor
262         * @param jo A Json-Object having data about an instance of {@code 'messageAdded'}.
263         */
264        public messageAdded (JsonObject jo)
265        {
266            super("Console", "messageAdded", 1);
267        
268            this.message  = ReadJSON.getObject(jo, "message", Console.ConsoleMessage.class, false, true);
269        }
270        
271        
272        /** Checks whether {@code 'this'} equals an input Java-{@code Object} */
273        public boolean equals(Object other)
274        {
275            if (this == other)                       return true;
276            if (other == null)                       return false;
277            if (other.getClass() != this.getClass()) return false;
278        
279            messageAdded o = (messageAdded) other;
280        
281            return
282                    Objects.equals(this.message, o.message);
283        }
284        
285        /** Generates a Hash-Code for {@code 'this'} instance */
286        public int hashCode()
287        {
288            return
289                    this.message.hashCode();
290        }
291    }
292    
293    
294    // Counter for keeping the WebSocket Request ID's distinct.
295    private static int counter = 1;
296    
297    /**
298     * Does nothing.
299     * 
300     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
301     * {@link Ret0}&gt;</CODE>
302     *
303     * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the
304     * browser receives the invocation-request.
305     *
306     * <BR /><BR />This Browser-Function <I>does not have</I> a return-value.  You may choose to
307     * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0}
308     * {@code >} to ensure the Browser Function has run to completion.
309     */
310    public static Script<String, JsonObject, Ret0> clearMessages()
311    {
312        final int          webSocketID = 1000000 + counter++;
313        final boolean[]    optionals   = new boolean[0];
314        
315        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
316        String requestJSON = WriteJSON.get(
317            parameterTypes.get("clearMessages"),
318            parameterNames.get("clearMessages"),
319            optionals, webSocketID,
320            "Console.clearMessages"
321        );
322        
323        // This Remote Command does not have a Return-Value.
324        return new Script<>
325            (webSocketID, requestJSON, VOID_RETURN.NoReturnValues);
326    }
327    
328    /**
329     * Disables console domain, prevents further console messages from being reported to the client.
330     * 
331     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
332     * {@link Ret0}&gt;</CODE>
333     *
334     * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the
335     * browser receives the invocation-request.
336     *
337     * <BR /><BR />This Browser-Function <I>does not have</I> a return-value.  You may choose to
338     * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0}
339     * {@code >} to ensure the Browser Function has run to completion.
340     */
341    public static Script<String, JsonObject, Ret0> disable()
342    {
343        final int          webSocketID = 1001000 + counter++;
344        final boolean[]    optionals   = new boolean[0];
345        
346        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
347        String requestJSON = WriteJSON.get(
348            parameterTypes.get("disable"),
349            parameterNames.get("disable"),
350            optionals, webSocketID,
351            "Console.disable"
352        );
353        
354        // This Remote Command does not have a Return-Value.
355        return new Script<>
356            (webSocketID, requestJSON, VOID_RETURN.NoReturnValues);
357    }
358    
359    /**
360     * Enables console domain, sends the messages collected so far to the client by means of the
361     * {@code messageAdded} notification.
362     * 
363     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
364     * {@link Ret0}&gt;</CODE>
365     *
366     * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the
367     * browser receives the invocation-request.
368     *
369     * <BR /><BR />This Browser-Function <I>does not have</I> a return-value.  You may choose to
370     * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0}
371     * {@code >} to ensure the Browser Function has run to completion.
372     */
373    public static Script<String, JsonObject, Ret0> enable()
374    {
375        final int          webSocketID = 1002000 + counter++;
376        final boolean[]    optionals   = new boolean[0];
377        
378        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
379        String requestJSON = WriteJSON.get(
380            parameterTypes.get("enable"),
381            parameterNames.get("enable"),
382            optionals, webSocketID,
383            "Console.enable"
384        );
385        
386        // This Remote Command does not have a Return-Value.
387        return new Script<>
388            (webSocketID, requestJSON, VOID_RETURN.NoReturnValues);
389    }
390    
391}