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