{"id":398,"date":"2020-05-25T10:18:44","date_gmt":"2020-05-25T10:18:44","guid":{"rendered":"http:\/\/spiderwiz.org\/project\/?page_id=398"},"modified":"2025-04-09T06:15:57","modified_gmt":"2025-04-09T06:15:57","slug":"lesson-3","status":"publish","type":"page","link":"https:\/\/spiderwiz.org\/project\/tutorial\/lesson-3\/","title":{"rendered":"Lesson 3: Going World Wide with a WebSocket Hub"},"content":{"rendered":"\n

In the previous lessons we saw how Spiderwiz worked with a command line application. We connected a producer and a consumer directly over TCP\/IP. In this lesson we will create a web application and use it as a hub to connect client producers and consumers over WebSockets. We will use the implementation to demonstrate a simple chat service.<\/p>\n\n\n\n

We start by using the IDE to create a Java Web Application project. We call it MyHub<\/code>. Since it will act as a WebSocket server we need to add the following dependency, as mentioned in Getting Spiderwiz<\/a>:<\/p>\n\n\n\n

<dependency>\n  \t<groupId>org.spiderwiz<\/groupId>\n  \t<artifactId>spiderwiz-websocket-server<\/artifactId>\n  \t<version>1.2<\/version>\n<\/dependency><\/pre><\/div>\n\n\n\n
Our first class, HubMain<\/code>, is an extension of Spiderwiz Main<\/code> class. Here it goes:<\/p>\n\n\n\n
package org.spiderwiz.tutorial.lesson3;\n\nimport org.spiderwiz.core.Main;\n\n\/**\n * Main class for MyHub. As a hub, we neither produce nor consume any object.\n *\/\npublic class HubMain extends Main{\n    private static final String ROOT_DIRECTORY = "\/tests\/MyHub";\n    private static final String CONFIG_FILE_NAME = "hub.conf";\n    private static final String APP_NAME = "My Hub";\n    private static final String APP_VERSION = "Z2.01";  \/\/ Version Z2.01: First working version\n\n    public HubMain() {\n        super(ROOT_DIRECTORY, CONFIG_FILE_NAME, APP_NAME, APP_VERSION);\n    }\n\n    \/**\n     * @return an empty list as we produce nothing\n     *\/\n    @Override\n    protected String[] getProducedObjects() {\n        return new String[]{};\n    }\n\n    \/**\n     * @@return an empty list as we consume nothing\n     *\/\n    @Override\n    protected String[] getConsumedObjects() {\n        return new String[]{};\n    }\n}<\/pre><\/div>\n\n\n\n
As you see, not much. We define a root directory, a configuration file name, application name and version, and return empty lists in getProducedObjects()<\/a> and getConsumedObjects()<\/a>. <\/p>\n\n\n\n
To run the application on our website we need to initialize it from a servlet. Here is RootServlet<\/code> class: <\/p>\n\n\n\n
package org.spiderwiz.tutorial.lesson3;\n\nimport javax.servlet.ServletException;\nimport javax.servlet.annotation.WebServlet;\nimport javax.servlet.http.HttpServlet;\n\n\/**\n * A root servlet for spawning a Spiderwiz application\n *\/\n@WebServlet(name = "RootServlet", urlPatterns = {"\/RootServlet"}, loadOnStartup = 1)\npublic class RootServlet extends HttpServlet {\n\n    \/**\n     * Instantiate and initialize the Spiderwiz runtime\n     * @throws ServletException\n     *\/\n    @Override\n    public void init() throws ServletException {\n        super.init();\n        new HubMain().init();\n    }\n\n    \/**\n     * Do Spiderwiz cleanup on application termination\n     *\/\n    @Override\n    public void destroy() {\n        HubMain.getInstance().cleanup();\n        super.destroy();\n    }\n}<\/pre><\/div>\n\n\n\n
RootServlet<\/code> implements a servlet that loads on startup, initializes HubMain<\/code> and calls its cleanup()<\/a> method when the servlet is destroyed. <\/p>\n\n\n\n
Actually we are done! If you wonder where all the WebSocket server stuff is, recall that we still have to provide a hub.conf<\/code> file. There, in one line (two actually), is where we define our hub as a WebSocket server: <\/p>\n\n\n\n
<\/p>\n\n\n\n
[log folder]Logs\n[consumer server-1]websocket;ping-rate=30\n[producer server-1]websocket;ping-rate=30\n[hub mode]yes<\/pre><\/div>\n\n\n\n
Everything is in the definitions of the server as websocket<\/code>. There are two property lines that do that, because our hub can be connected by both Producer<\/em> and Consumer<\/em> applications, so we define it as a consumer server<\/code> for the first and producer server<\/code> for the latter. <\/p>\n\n\n\n
Note that besides defining each server as \u201cwebsocket\u201d, we add the parameter \u201cping-rate=30<\/code>\u201d. This is done because many web servers drop WebSocket connections that are idle for too long. The parameter tells the Spiderwiz engine to ping these connections every 30 seconds, therefore keeping them busy so they would not be dropped even if there is no activity for a while. <\/p>\n\n\n\n
The last configuration line sets hub mode<\/code> to yes<\/code>. This is needed because, since the application neither produces nor consumes anything, without it it will neither get nor send any data. The definition as hub mode<\/code> tells the system to pass objects of any type through the hub, which routes them between producers and consumers similarly to an IP router. <\/p>\n\n\n\n
Go ahead and deploy the project. You will see the following in your web server\u2019s log file: <\/p>\n\n\n\n
My Hub ver. Z2.01 (core version Z2.42) has been initiated\nsuccessfully\nProducer is listening to consumers on WebSockets\nConsumer is listening to producers on WebSockets\n<\/pre>\n\n\n\n
We are done with the hub server, now to the clients. <\/p>\n\n\n\n
The main ingredient of our chat application is the Chat<\/code> data object: <\/p>\n\n\n\n
package org.spiderwiz.tutorial.objectLib;\n\nimport org.spiderwiz.annotation.WizField;\nimport org.spiderwiz.core.DataObject;\n\n\/**\n * Chat class for Spiderwiz tutorial's lesson 2.\n *\/\npublic class Chat extends DataObject {\n    \/**\n     * Mandatory public static field for all data objects.\n     *\/\n    public final static String ObjectCode = "CHAT";\n    \n    @WizField private String name;              \/\/ Contains the name of the chatter\n    @WizField private String message;           \/\/ Contains a chat message\n\n    public String getName() {\n        return name;\n    }\n\n    public void setName(String name) {\n        this.name = name;\n    }\n\n    public String getMessage() {\n        return message;\n    }\n\n    public void setMessage(String message) {\n        this.message = message;\n    }\n\n    \/**\n     * @return null as this is a root object.\n     *\/\n    @Override\n    protected String getParentCode() {\n        return null;\n    }\n\n    \/**\n     * @return true as this object is disposable.\n     *\/\n    @Override\n    protected boolean isDisposable() {\n        return true;\n    }\n\n    @Override\n    protected boolean isUrgent() {\n        return true;\n    }\n}<\/pre><\/div>\n\n\n\n
We define the mandatory ObjectCode<\/code>, make objects of this class disposable top-level objects (because we can dispose a message after it has been sent), and define two properties annotated as @WizField<\/code>: name<\/code> and message<\/code> \u2013 the first is the name of the chatter and the latter, well, is the chat message. We also mark that this is an urgent object<\/a> (line 51) because we want chat messages to reach their destination promptly. We place the class in the objectLib<\/code> package. <\/p>\n\n\n\n
Let\u2019s build now the chat client application. We will implement it as a command line application. We need to start by extending class Main<\/code>. But before doing that there is a twist. We want our client to read lines from the console, exit if an input line is \u201cexit\u201d, and do something else if not. Since this mechanism will repeat in many of the next lessons we should make it reusable. To do that, we create a Main<\/code> class extension called ConsoleMain<\/code> that does the work and place it in the objectLib<\/code> package: <\/p>\n\n\n\n
package org.spiderwiz.tutorial.objectLib;\n\nimport java.io.BufferedReader;\nimport java.io.IOException;\nimport java.io.InputStreamReader;\nimport org.spiderwiz.core.Main;\n\n\/**\n * Extend Spiderwiz Main class to handle reading input lines from the console by a command line application.\n *\/\npublic abstract class ConsoleMain extends Main{\n    BufferedReader br;\n\n    \/**\n     * Pass parameters to super constructor\n     * @param rootDirectory     the application root directory.\n     * @param configFileName    the application configuration file.\n     * @param appName           the default application name\n     * @param appVersion        the default application version number\n     *\/\n    public ConsoleMain(String rootDirectory, String configFileName, String appName, String appVersion) {\n        super(rootDirectory, configFileName, appName, appVersion);\n    }\n\n    \/**\n     * Called after framework initialization. Install a shutdown hook, then loop on reading messages from the console\n     * until "exit" is typed.\n     *\/\n    @Override\n    protected void postStart() {\n        \/\/ Install a shutdown hook that cleans resources up on termination.\n        Runtime.getRuntime().addShutdownHook(new Thread() {\n            @Override\n            public void run() {\n                cleanup();\n            }\n        });\n        \n        \/\/ Do post init processing\n        if (!postInit())\n            return;\n\n        \/\/ Read console lines and process them until "exit" is typed\n        br = new BufferedReader(new InputStreamReader(System.in));\n        String line;\n        do {\n            line = readConsoleLine(getConsolePrompt());\n            if ("exit".equalsIgnoreCase(line))\n                break;\n        } while (processConsoleLine(line));\n        System.exit(0);\n    }\n\n    \/**\n     * Override this method to return the prompt text to display on the console before reading a line.\n     * @return an empty string by default.\n     *\/\n    protected String getConsolePrompt() {return "";}\n    \n    \/**\n     * Implement this method to provide console input line processing\n     * @param line  a console input line\n     * @return true if program shall continue to process next input line, false if it shall terminate\n     *\/\n    protected abstract boolean processConsoleLine(String line);\n    \n    \/**\n     * Provides a formatted prompt, then reads a single line of text from the console.\n     * @param fmt   A format string as described in Format string syntax.\n     * @param args  Arguments referenced by the format specifiers in the format string\n     * @return      A string containing the line read from the console\n     *\/\n    protected String readConsoleLine(String fmt, Object ... args) {\n        try {\n            System.out.printf(fmt, args);\n            return br.readLine();\n        } catch (IOException ex) {\n            return null;\n        }\n    }\n    \n    \/**\n     * Override this to do something after calling Main.init() and before starting to read console lines\n     * @return true if processing shat continue, false if program shall be aborted.\n     *\/\n    protected boolean postInit() {\n        return true;\n    }\n}<\/pre><\/div>\n\n\n\n
ConsoleMain<\/code> is an abstract extension of Main<\/code>. It defines four protected methods that can be overridden \u2013 getConsolePrompt()<\/code> (line 58) returns the  prompt text that shall be printed to the  console before reading each line. If not overridden, it returns an empty string. The abstract method processConsoleLine()<\/code> (line 65) must be implemented to tell what to do with each input line. Additionally readConsoleLine()<\/code> (line 73) prints a formatted prompt, then reads a single line of text from the console. The method is called internally from ConsoleMain<\/code> and can also be called from derived classes if they need to do their own command line processing. Another method that can be optionally overridden is postInit()<\/code> (line 86). It is called after calling Main.init()<\/a> and before starting to read console lines, therefore extension classes can call it to do something before processing them.<\/p>\n\n\n\n
ConsoleMain<\/code> overrides Main.postStart()<\/a> (line 30) to install a shutdown hook, call postInit()<\/code> and loop on reading messages from the console and calling processConsoleLine<\/code>() to process them until “exit” is typed (or processConsoleLine()<\/code> returns false).<\/p>\n\n\n\n
Now everything is ready for ChatMain<\/code>:<\/p>\n\n\n\n
package org.spiderwiz.tutorial.lesson3;\n\nimport java.util.List;\nimport org.spiderwiz.core.DataObject;\nimport org.spiderwiz.tutorial.objectLib.Chat;\nimport org.spiderwiz.tutorial.objectLib.ConsoleMain;\n\n\/**\n * Provides the entry point of the application. Initializes and executes the Spiderwiz framework.\n *\/\npublic class ChatMain extends ConsoleMain{\n    private static final String ROOT_DIRECTORY = "";\n    private static final String APP_NAME = "Chat Client";\n    private static final String APP_VERSION = "Z1.01";  \/\/ Version Z1.01: Initial version\n    \n    private String myName;      \/\/ Get this from the configuration file\n    private Chat chat = null;   \/\/ A Chat object for committing chat messages\n\n    \/**\n     * Class constructor with constant parameters.\n     * @param confFileName  configuration file name, provided as a command argument\n     *\/\n    public ChatMain(String confFileName) {\n        super(ROOT_DIRECTORY, confFileName, APP_NAME, APP_VERSION);\n    }\n\n    \/**\n     * Application entry point. Instantiate the class and initialize the instance.\n     * \n     * @param args the command line arguments. The first argument is used as the configuration file name.\n     *\/\n    \/**\n     * @param args the command line arguments\n     *\/\n    public static void main(String[] args) {\n        \/\/ Don't do anything if there is no configuration file name\n        if (args.length == 0) {\n            System.out.println("Configuration file has not been defined");\n            return;\n        }\n        new ChatMain(args[0]).init();\n    }\n\n    \/**\n     * Before starting Spiderwiz engine (but after reading program configuration) get the chatter name.\n     * @return true if a chatter name is provided, false if not.\n     *\/\n    @Override\n    protected boolean preStart() {\n        myName = getConfig().getProperty("my name");\n        if (myName == null || myName.isBlank()) {\n            System.out.println("Chatter name has not been defined");\n            return false;\n        }\n        System.out.println("You are chatting as " + myName + ". Go ahead and type your messages");\n        return true;\n    }\n    \n    \/**\n     * @return the list of produced objects, in this case Chat is the only one.\n     *\/\n    @Override\n    protected String[] getProducedObjects() {\n        return new String[]{Chat.ObjectCode};\n    }\n\n    \/**\n     * @return the list of consumed objects, in this case Chat is the only one.\n     *\/\n    @Override\n    protected String[] getConsumedObjects() {\n        return new String[]{Chat.ObjectCode};\n    }\n\n    \/**\n     * Add ChatConsume implementation class to the object factory list of this application.\n     * @param factoryList\n     *\/\n    @Override\n    protected void populateObjectFactory(List<Class<? extends DataObject>> factoryList) {\n        super.populateObjectFactory(factoryList);\n        factoryList.add(ChatConsume.class);\n    }\n\n    \/**\n     * Process an input line\n     * @param line      the line to be broadcast as a chat message.\n     * @return true if processed successfully\n     *\/\n    @Override\n    protected boolean processConsoleLine(String line) {\n        try {\n            \/\/ If not yet done, instantiate a Chat object and set its 'name' field.\n            if (chat == null) {\n                chat = ChatMain.createTopLevelObject(Chat.class, null);\n                chat.setName(myName);\n            }\n            \/\/ Set chat message and commit\n            chat.setMessage(line);\n            chat.commit();\n            return true;\n        } catch (NoSuchFieldException | IllegalAccessException ex) {\n            \/\/ Theoretically arriving here if the Chat object does not contain ObjectCode static field or the field is not public.\n            \/\/ In this case, send a command exception message.\n            sendExceptionMail(ex, "Cannot instantiate Chat class", null, false);\n            return false;\n        }\n    }\n}<\/pre><\/div>\n\n\n\n
ChatMain<\/code> extends ConsoleMain<\/code>. This time the configuration file name that is passed to ChatMain<\/code> (and Main<\/code>) constructor is entered as a command line argument. This is because we may want to have few instances of the chat client on the same machine, and we don\u2019t want to mix log folders and other properties.<\/p>\n\n\n\n
We introduce here (line 49) the usage of Main.preStart()<\/code><\/a> \u2013 a method that is called after the configuration file is loaded and log folders are set, but before Spiderwiz engine is started. Here we get [my name<\/code>] property from the configuration file (line 50) and use it as the chatter (owner of the instance) name.<\/p>\n\n\n\n
Our application is both a Producer and a Consumer of the Chat<\/code> object described above, so both getProducedObjects()<\/a> and getConsumedObjects()<\/a> return a list that contains one element \u2013 Chat.ObjectCode<\/code>.<\/p>\n\n\n\n
To handle incoming messages we implement an extension of Chat<\/code> called ChatConsume<\/code>. We register it in populateObjectFactory()<\/code> (line 81).<\/p>\n\n\n\n
Lastly, we implement processConsoleLine()<\/code> that we inherited from ConsoleMain<\/code> (line 91). The argument to this method is the message that shall be sent to the chat group. It works as follows:<\/p>\n\n\n\n