Experienced programmers know that developing a software\nproject that works is only half of their task, if not less. To do a full job,\nthey have to provide procedures and tools that can be used by maintenance and\nsupport staff when the project does not work as expected. This lesson is\ndedicated to features that will assist you with that.<\/p>\n\n\n\n
Application logs are an indispensable part of every serious\nsoftware project. We saw how they came free with every Spiderwiz application\nright from the Hello World<\/em> project of\nLesson\n1<\/a>. Spiderwiz logging system can go from basic events as we saw\nthere, to a full log of every transaction that goes over a communication line.\nWith respect to the latter, since the transactions are potentially subject to compression<\/a>, logging can be configured\nto show compressed data, uncompressed data or both. For a thorough discussion\nof the topic see Spiderwiz Logging System<\/a> in the project\u2019s\nJavadoc.<\/p>\n\n\n\n Spiderwiz Programming Model is about data communication. It\nis true that the model is designed to let programmers forget that point, but\nsystem administrators must get promptly aware of any communication breach or\napplication malfunction. This is done by sending alerts through email or other\nmeans.<\/p>\n\n\n\n The Spiderwiz framework includes full support of system and\ncustom alert notifications. System alerts are triggered when an application\ndetects that a peer application is disconnected. There is also a \u201cback to\nroutine\u201d notification that is triggered when an application that was previously\ndisconnected connects again. The exact condition when and by which service\nnotifications are triggered is specified in application configuration file\nthrough the following properties and parameters:<\/p>\n\n\n\n For details please see Spiderwiz Configuration<\/a> in the project\u2019s Javadoc.<\/p>\n\n\n\n Every notification is logged in the application\u2019s log\nsystem. Additionally you can configure a mail system that is used by the\nframework to send notification emails. Currently only SMTP mail is supported,\nbut you can implement a mail plugin<\/a> to support any messaging system that\nfits. Email sending is configured through the following properties:<\/p>\n\n\n\n These are also described in detail in the configuration Javadoc<\/a>.<\/p>\n\n\n\n Custom alerts are triggered programmatically by calling sendNotificationMail()<\/a> and are logged and mailed\nin the same way.<\/p>\n\n\n\n Code exceptions (i.e. bugs) are another kind of event that\nrequire prompt notification. While the addressees of system alerts are usually\nsystem administrators, exceptions should go to programmers. As with alerts,\nSpiderwiz has everything that you need to handle exception notifications\nefficiently.<\/p>\n\n\n\n Some exceptions are caught by the framework while others occur in your code or when you call a framework method that throws exceptions. In the first case, a notification is triggered by the framework. In the second case you can call Main.sendExceptionMail()<\/a> to trigger a similar notification. In both cases the notification, which includes the exception details and stack trace, is logged in the application\u2019s logging system and is also sent by email if a mail system is configured. The addressees for such emails in the case of exceptions are configured by the Note that It is often the case that production systems are behind a\nfirewall and do not have access to a mail server. It happens to be that this is\nalso the case when getting email alerts about system malfunction is the most\nimportant, because programming access to these systems is also limited, and so\nis the ability of maintenance staff to check what is going on.<\/p>\n\n\n\n This is another case where Spiderwiz offers a simple\nsolution to a thorny problem. The solution is called Mail Delegation<\/em>, and it requires no more than one line of code in\neach involved application. The idea is that the application without mail server\naccess delegates the mission to an application that does have it. To make it\nwork, you would need to do the following:<\/p>\n\n\n\n That\u2019s it! Let\u2019s give it a try with our chat system. We\nassume that we cannot guarantee that every running chat application has access\nto a mail server. However, we can assure that My Hub<\/em>, which all the applications are connected through, has. So\nfirstly we modify In line 110 we add ObjectCodes.EventReport<\/a> to the list returned by getProducedObjects()<\/a>.<\/p>\n\n\n\n In order to easily test an exception, we change the parsing\nof the And finally, in line 215, we catch every Exception type and\ncall sendExceptionMail()<\/a> to send an appropriate\nmessage.<\/p>\n\n\n\n Back to My Hub<\/em>, we\nmodify Alert messages<\/h2>\n\n\n\n
alert<\/code> parameter of producer-<\/code>n<\/em>, consumer-<\/code>n<\/em>, producer server<\/code>–n<\/em>, consumer server<\/code>–n<\/em>\nand import-<\/code>n<\/em>.<\/li><\/ul>\n\n\n\nmail system<\/code><\/li>from address<\/code><\/li>to email<\/code><\/li>cc email<\/code><\/li><\/ul>\n\n\n\nException alerts<\/h2>\n\n\n\n
to exception email<\/code> and cc exception email<\/em> properties.<\/p>\n\n\n\nsendExceptionMail()<\/code> has a boolean<\/code> parameter called critical<\/code>. Every call to sendExceptionMail()<\/code> with the parameter set to true<\/code> triggers a notification. On the contrary when critical<\/code> is set to false<\/code>, notifications are not sent more frequently than the value configured by the exception alert rate<\/code> property. This lets you avoid email inundation for exceptions that are thrown over and over again.<\/p>\n\n\n\nMail delegation<\/h2>\n\n\n\n
ObjectCodes.EventReport<\/code> in the list of\nobject types that it produces.<\/li>ObjectCodes.EventReport<\/code> in the list of object types that it consumes.<\/li><\/ul>\n\n\n\nChatMain<\/code>:<\/p>\n\n\n\npackage org.spiderwiz.tutorial.lesson13.chat;\n\nimport java.io.PrintStream;\nimport java.text.ParseException;\nimport java.util.Collection;\nimport java.util.List;\nimport org.spiderwiz.core.DataObject;\nimport org.spiderwiz.tutorial.objectLib.ActiveUserQuery;\nimport org.spiderwiz.tutorial.objectLib.Chat;\nimport org.spiderwiz.tutorial.objectLib.ChatApp;\nimport org.spiderwiz.tutorial.objectLib.ChatHistoryQuery;\nimport org.spiderwiz.tutorial.objectLib.ChatMessage;\nimport org.spiderwiz.tutorial.objectLib.ChatRoom;\nimport org.spiderwiz.tutorial.objectLib.Chatter;\nimport org.spiderwiz.tutorial.objectLib.ConsoleMain;\nimport org.spiderwiz.tutorial.objectLib.LoginQuery;\nimport org.spiderwiz.zutils.ZDate;\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 Room Client";\n private static final String APP_VERSION = "Z13.01"; \/\/ Version Z13.01: Lesson 13 modifications\n\n private static final String JOIN = "!join"; \/\/ join a chat room command\n private static final String LEAVE = "!leave"; \/\/ leave current chat room command\n private static final String LOGIN = "!login"; \/\/ start login procedure\n private static final String LOGOUT = "!logout"; \/\/ log the user out\n private static final String REGISTER = "!register"; \/\/ start registration procedure\n private static final String HISTORY = "!history"; \/\/ print my chat history\n \n private String myName = null; \/\/ The user login name\n private ZDate birthday = null; \/\/ User birth date. Get it when logging in\n private ChatterConsume chatter = null; \/\/ A Chatter object representing the user chatting in a specific room\n private ChatMessage message = null; \/\/ A ChatMessage object for committing chat messages\n private Chat privateMessage = null; \/\/ A Chat object for committing private 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 * @return the class instance as ChatMain type.\n *\/\n public static ChatMain getInstance() {\n return (ChatMain)ConsoleMain.getInstance();\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 * Print user instructions to the console.\n * @return true\n *\/\n @Override\n protected boolean preStart() {\n System.out.printf(\n "Welcome to the dynamic chat system.n"\n + "To log in type !login.n"\n + "To log out type !logout.n"\n + "To register type !register.n"\n + "To join a chat room or change your current chat room, type "!join <room name>".n"\n + "To leave your chat room, type "!leave".n"\n + "To send a message in the current chat room just type the message "\n + "(a message cannot start with either '>' or '!').n"\n + "To send a private message type '>' followed by name of the user you want to send "\n + "the private message to, followed by ':' for by the message.n"\n + "To print the history of your own messages, type "!history <hours>h" or "!history <days>d"n"\n + "(for instance "!history 3h" to see messages since 3 hours ago and "!history 1d" to see messages since 1 day"\n + " ago).n"\n + "or type just "!history" to see all your messages.n"\n + "To exit type 'exit'.n"\n );\n return true;\n }\n \n \/**\n * @return the list of produced objects - Chatter, Chat, ChatMessage and LoginQuery\n *\/\n @Override\n protected String[] getProducedObjects() {\n return new String[]{\n ChatApp.ObjectCode,\n Chatter.ObjectCode,\n Chat.ObjectCode,\n ChatMessage.ObjectCode,\n LoginQuery.ObjectCode,\n ChatHistoryQuery.ObjectCode,\n ObjectCodes.EventReport \/\/ Added in Lesson 13\n };\n }\n\n \/**\n * @return the list of consumed objects - ChatRoom, Chatter, Chat, ChatMessage and ActiveUserQuery\n *\/\n @Override\n protected String[] getConsumedObjects() {\n return new String[]{\n ChatRoom.ObjectCode,\n ChatApp.ObjectCode,\n Chatter.ObjectCode,\n Chat.ObjectCode,\n ChatMessage.ObjectCode,\n ActiveUserQuery.ObjectCode\n };\n }\n\n \/**\n * Add implementation classes 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(ChatRoomConsume.class);\n factoryList.add(ChatApp.class);\n factoryList.add(ChatterConsume.class);\n factoryList.add(ChatConsume.class);\n factoryList.add(ChatMessageImp.class);\n factoryList.add(LoginQuery.class);\n factoryList.add(ActiveUserQueryReply.class);\n factoryList.add(ChatHistoryQueryInquire.class);\n }\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 the line starts with '!' this is a command line\n if (line.startsWith("!")) {\n String command[] = line.trim().split("s+", 2);\n switch (command[0].toLowerCase()) {\n case JOIN:\n \/\/ if room name is provided join the room\n if (command.length > 1)\n joinRoom(command[1]);\n break;\n case LEAVE:\n \/\/ If the user is in a room, leave it\n leaveRoom(null);\n break;\n case LOGIN:\n login();\n break;\n case LOGOUT:\n logout();\n break;\n case REGISTER:\n register();\n break;\n case HISTORY:\n if (myName == null)\n System.out.println("You must log in before requesting history.");\n else if (!getHistory(command.length < 2 ? null : command[1]))\n System.out.println("Invalid command argument");\n break;\n }\n return true;\n }\n \n \/\/ If the line starts with '>' split the line on the colon (':') and send the test\n \/\/ after the colon as a private message to the user with the name before the colon.\n if (line.startsWith(">")) {\n String cmd[] = line.substring(1).split(":");\n if (cmd.length < 2)\n return true;\n String destination = findUser(cmd[0]);\n if (destination == null)\n return true;\n \/\/ If didn't do yet, create an orphan Chatter object for sending private messages,\n \/\/ then prepare a ChatMessage object for sending private messages\n if (privateMessage == null) {\n privateMessage = createTopLevelObject(Chat.class, null);\n privateMessage.setName(myName);\n }\n \/\/ Set message and commit to destination\n privateMessage.setMessage(cmd[1]);\n privateMessage.setTime(ZDate.now());\n privateMessage.commit(destination);\n return true;\n }\n \n \/\/ If this is a normal message, make sure the user is in a room and broadcast the message\n if (message != null) {\n message.setMessage(line);\n message.setTime(ZDate.now());\n message.commit();\n }\n } catch (Exception ex) {\n sendExceptionMail(ex, "Exception when processing an input line", line, true);\n }\n return true;\n }\n public String getMyName() {\n return myName;\n }\n\n public ZDate getBirthday() {\n return birthday;\n }\n \n \/**\n * Get user name and password and log in.\n * @return a PrintStream object. Not needed by the caller but we use it as a trick to save coding.\n * @throws NoSuchFieldException If LoginQuery does not define ObjectCode static field.\n * @throws IllegalAccessException If LoginQuery.ObjectCode is not public.\n *\/\n private PrintStream login() throws NoSuchFieldException, IllegalAccessException {\n String username;\n String password;\n\n \/\/ Check if already logged in\n if (myName != null)\n return System.out.printf("You are already logged in as %s. To log in with another name log out first.n", myName);\n \n \/\/ Create a login query\n LoginQuery query = createQuery(LoginQuery.class);\n while(true) {\n \/\/ Get user name\n System.out.printf("(type Enter to exit login)n");\n username = readConsoleLine("User name:");\n if (username.isBlank())\n return exitLogin();\n do {\n \/\/ Get password\n password = readConsoleLine("Password:");\n if (password.isBlank())\n return exitLogin();\n\n \/\/ Post the login query\n query.setNewUser(false);\n query.setName(username);\n query.setPassword(password);\n query.post(5 * ZDate.SECOND);\n \n \/\/ If the query did not expire check login results, if it did, repeat.\n if (query.waitForReply()) {\n switch (query.getResult()) {\n case OK:\n myName = query.getName();\n birthday = query.getBirthday();\n return System.out.printf("Logged in successfully as %s.n", myName);\n case NOT_EXISTS:\n System.out.printf("User %s does not exist. Please try again.n", username);\n break;\n case WRONG_PASSWORD:\n System.out.printf("Password did not match, please try again.n");\n break;\n }\n } else\n return unavailableUserManager();\n } while (query.getResult() == LoginQuery.ResultCode.WRONG_PASSWORD);\n }\n }\n \n \/**\n * Log out if already logged in\n *\/\n private void logout() {\n if (myName == null) {\n System.out.printf("No user is logged in.n");\n return;\n }\n leaveRoom(null);\n System.out.printf("%s is logged out.n", myName);\n myName = null;\n birthday = null;\n }\n\n private PrintStream register() throws NoSuchFieldException, IllegalAccessException {\n String username;\n String password, password2;\n\n \/\/ Check if already logged in\n if (myName != null)\n return System.out.printf("You are already logged in as %s. To register a new user log out first.n", myName);\n \n \/\/ Create a registration query\n LoginQuery query = createQuery(LoginQuery.class);\n while(true) {\n \/\/ Get user name\n System.out.printf("(type Enter to exit login)n");\n username = readConsoleLine("User name:");\n if (username.isBlank())\n return exitRegistration();\n do {\n \/\/ Get password\n password = readConsoleLine("Password:");\n if (password.isBlank())\n return exitRegistration();\n\n \/\/ Repeat the password\n password2 = readConsoleLine("Repeat password:");\n if (password2.isBlank())\n return exitRegistration();\n \n \/\/ Check if passwords are equal\n if (password.equals(password2))\n break;\n System.out.println("Passwords do not match.");\n } while (true);\n \n \/\/ Get and parse birth date\n do {\n String s = readConsoleLine("Date of birth (yyyy\/mm\/dd):");\n if (s.isBlank())\n return exitRegistration();\n try {\n birthday = ZDate.parseTime(s, "yyyy\/MM\/dd", null);\n } catch (ParseException ex) {\n birthday = null;\n System.out.printf("Invalid date %s. Please try again.n", s);\n }\n } while (birthday == null);\n\n \/\/ Post the registration query\n query.setNewUser(true);\n query.setName(username);\n query.setPassword(password);\n query.setBirthday(birthday);\n query.post(5 * ZDate.SECOND);\n\n \/\/ If the query did not expire check login results, if it did, repeat.\n if (query.waitForReply()) {\n switch (query.getResult()) {\n case OK:\n myName = username;\n return System.out.printf("Registered and logged in successfully as %s.n", myName);\n case EXISTS:\n System.out.printf("User %s already exista. Please try again with another name.n", username);\n break;\n }\n } else\n return unavailableUserManager();\n }\n }\n \n \/**\n * Print a message when login existed by typing a blank Enter\n * @return a PrintStream object. Not needed by the caller but we use it as a trick to save coding.\n *\/\n private PrintStream exitLogin() {\n return System.out.printf("Login exitedn");\n }\n \n \/**\n * Print a message when registration existed by typing a blank Enter\n * @return a PrintStream object. Not needed by the caller but we use it as a trick to save coding.\n *\/\n private PrintStream exitRegistration() {\n return System.out.printf("Registration exitedn");\n }\n \n \/**\n * Print a message when user management is not available\n * @return a PrintStream object. Not needed by the caller but we use it as a trick to save coding.\n *\/\n private PrintStream unavailableUserManager() {\n return System.out.printf("No user management entity is available to handle this requestn");\n }\n \n \/**\n * Join a room after checking that the room exists, its adult setting matches user configuration,\n * and the user is not already there. If the user is in another room leave that room first.\n * @param room the new room name\n * @throws NoSuchFieldException If any of the created data objects does not define ObjectCode static field.\n * @throws IllegalAccessException If ObjectCode is not public.\n *\/\n private synchronized void joinRoom(String room) throws NoSuchFieldException, IllegalAccessException {\n \/\/ User must be logged in\n if (myName == null) {\n System.out.printf("You must log in before joining a room.n");\n return;\n }\n \n \/\/ Check whether room exists and the user is not already in the room\n ChatRoomConsume chatRoom = getRootObject().getChild(ChatRoomConsume.class, room);\n if (chatRoom == null) {\n System.out.printf("Room %s does not existn", room);\n return;\n }\n\n if (chatter != null && room.equalsIgnoreCase(chatter.getRoomName()))\n return;\n \n \/\/ Check if a young chatters is trying to join an adult room\n if (!chatRoom.canJoin(birthday)) {\n System.out.printf("You cannot join room %s because it is only for adultsn", room);\n return;\n }\n \n \/\/ Leave current room if any\n leaveRoom(null);\n \n \/\/ Join the application to the room\n ChatApp chatApp = chatRoom.createChild(ChatApp.class, getAppUUID().toString());\n \n \/\/ Create a Chatter object for the user that joins the specified room\n chatter = chatApp.createChild(ChatterConsume.class, myName);\n chatter.setName(myName);\n chatter.setBirthday(birthday);\n chatter.commit(); \/\/ let everybody know I joined the room\n \/\/ Prepare a ChatMessage object for sending messages from now on\n message = chatter.createChild(ChatMessage.class, null);\n System.out.printf("Joined room %sn", room);\n }\n \n \/**\n * If the user is in the given room, leave it.\n * @param room the name of the room to be checked if the user is there. If null, leave the current room without checking\n *\/\n public synchronized void leaveRoom(String room) {\n if (isSameRoom(room)) {\n \/\/ Leave the room and let everybody know I did\n DataObject removed = chatter.remove();\n if (removed != null) \/\/ can be null if the 'chatter' object has already been removed.\n removed.commit();\n \n \/\/ Disconnect the application from the room and let every application know it did\n removed = chatter.getParent().remove();\n if (removed != null)\n removed.commit();\n System.out.printf("Left room %sn", chatter.getRoomName());\n chatter = null;\n message = null;\n }\n }\n \n \/**\n * Check if the user is in the same room as the parameter\n * @param room the name of the room to be checked if the user is there. If null, return true\n * @return true if the user in 'room' or 'room' is null\n *\/\n public synchronized boolean isSameRoom(String room) {\n return chatter != null &&\n (room == null || room.equalsIgnoreCase(chatter.getRoomName()));\n }\n \n \/**\n * Get current room name, if any\n * @return if the user is currently in a room return the room name, otherwise return null.\n *\/\n public synchronized String getCurrentRoom() {\n return chatter == null ? null : chatter.getRoomName();\n }\n \n \/**\n * Find the user whose name equals the parameter\n * @param name user name to look for\n * @return If a Chatter object for this user found then return the object ID of its grandparent, which is the UUID of the\n * application that the given user runs, otherwise return null.\n * @throws NoSuchFieldException If any of the referred data objects does not define ObjectCode static field.\n * @throws IllegalAccessException If ObjectCode is not public.\n *\/\n private String findUser(String name) throws NoSuchFieldException, IllegalAccessException {\n FindUserFilter filter = new FindUserFilter(name);\n Collection<Chatter> users = getRootObject().getFilteredChildren(filter);\n \/\/ If the returned collection is not empty return the object ID (which is a UUID) of the first,\n \/\/ otherwise return null.\n for (Chatter user : users) {\n return user.getParent().getObjectID();\n }\n return null;\n }\n \n \/**\n * Execute !history command\n * @param arg command argument - <n>H or <n>D\n * @return true if command has been parsed successfully.\n * @throws NoSuchFieldException If ChatHistoryQuery does not define ObjectCode static field.\n * @throws IllegalAccessException If ChatHistoryQuery.ObjectCode is not public.\n *\/\n private boolean getHistory(String arg) throws NoSuchFieldException, IllegalAccessException {\n \/\/ Parse the argument and calculate time\n ZDate since = null;\n if (arg != null) {\n arg = arg.trim().toLowerCase();\n int n = Integer.parseInt(arg.substring(0, arg.length() - 1));\n if (n <= 0)\n return false;\n int unit;\n switch (arg.substring(arg.length() - 1)) {\n case "h":\n unit = ZDate.HOUR;\n break;\n case "d":\n unit = ZDate.DAY;\n break;\n default:\n return false;\n }\n since = ZDate.now().add(-n * unit);\n }\n \n \/\/ create a query and post it\n ChatHistoryQuery query = createQuery(ChatHistoryQuery.class);\n query.setUsername(myName);\n query.setSince(since);\n query.post(5 * ZDate.SECOND);\n return true;\n }\n}<\/pre><\/div>\n\n\n\n!history<\/code> command to use Integer.parseInt()<\/a> instead of ZUtilities.parseInt()<\/a> (line 504). We do it\nbecause the former throws an exception if its parameter is not a valid integer\nnumber, while the latter does not.<\/p>\n\n\n\nHubMain<\/code>:<\/p>\n\n\n\npackage 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 = "Z13.01"; \/\/ Version Z13.01: Amend for lesson 13\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 a list containing ObjectCodes.EventReport because this application can send mails.\n *\/\n @Override\n protected String[] getConsumedObjects() {\n return new String[]{ObjectCodes.EventReport};\n }\n}<\/pre><\/div>\n\n\n\n