Experienced programmers know that developing a software project that works is only half of their task, if not less. To do a full job, they have to provide procedures and tools that can be used by maintenance and support staff when the project does not work as expected. This lesson is dedicated to features that will assist you with that.
Logging
Application logs are an indispensable part of every serious software project. We saw how they came free with every Spiderwiz application right from the Hello World project of Lesson 1. Spiderwiz logging system can go from basic events as we saw there, to a full log of every transaction that goes over a communication line. With respect to the latter, since the transactions are potentially subject to compression, logging can be configured to show compressed data, uncompressed data or both. For a thorough discussion of the topic see Spiderwiz Logging System in the project’s Javadoc.
Alert messages
Spiderwiz Programming Model is about data communication. It is true that the model is designed to let programmers forget that point, but system administrators must get promptly aware of any communication breach or application malfunction. This is done by sending alerts through email or other means.
The Spiderwiz framework includes full support of system and custom alert notifications. System alerts are triggered when an application detects that a peer application is disconnected. There is also a “back to routine” notification that is triggered when an application that was previously disconnected connects again. The exact condition when and by which service notifications are triggered is specified in application configuration file through the following properties and parameters:
- disconnection alert minutes
- idle alert minutes
alert
parameter ofproducer-
n,consumer-
n,producer server
–n,consumer server
–n andimport-
n.
For details please see Spiderwiz Configuration in the project’s Javadoc.
Every notification is logged in the application’s log system. Additionally you can configure a mail system that is used by the framework to send notification emails. Currently only SMTP mail is supported, but you can implement a mail plugin to support any messaging system that fits. Email sending is configured through the following properties:
mail system
from address
to email
cc email
These are also described in detail in the configuration Javadoc.
Custom alerts are triggered programmatically by calling sendNotificationMail() and are logged and mailed in the same way.
Exception alerts
Code exceptions (i.e. bugs) are another kind of event that require prompt notification. While the addressees of system alerts are usually system administrators, exceptions should go to programmers. As with alerts, Spiderwiz has everything that you need to handle exception notifications efficiently.
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() to trigger a similar notification. In both cases the notification, which includes the exception details and stack trace, is logged in the application’s 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 to exception email
and cc exception email properties.
Note that sendExceptionMail()
has a boolean
parameter called critical
. Every call to sendExceptionMail()
with the parameter set to true
triggers a notification. On the contrary when critical
is set to false
, notifications are not sent more frequently than the value configured by the exception alert rate
property. This lets you avoid email inundation for exceptions that are thrown over and over again.
Mail delegation
It is often the case that production systems are behind a firewall and do not have access to a mail server. It happens to be that this is also the case when getting email alerts about system malfunction is the most important, because programming access to these systems is also limited, and so is the ability of maintenance staff to check what is going on.
This is another case where Spiderwiz offers a simple solution to a thorny problem. The solution is called Mail Delegation, and it requires no more than one line of code in each involved application. The idea is that the application without mail server access delegates the mission to an application that does have it. To make it work, you would need to do the following:
- There is no need to configure mail system properties for the application without mail server access.
- Mail system properties are configured for the application that has mail server access.
- The application without email access includes
ObjectCodes.EventReport
in the list of object types that it produces. - The application that has email access includes
ObjectCodes.EventReport
in the list of object types that it consumes.
That’s it! Let’s give it a try with our chat system. We
assume that we cannot guarantee that every running chat application has access
to a mail server. However, we can assure that My Hub, which all the applications are connected through, has. So
firstly we modify ChatMain
:
package org.spiderwiz.tutorial.lesson13.chat; import java.io.PrintStream; import java.text.ParseException; import java.util.Collection; import java.util.List; import org.spiderwiz.core.DataObject; import org.spiderwiz.tutorial.objectLib.ActiveUserQuery; import org.spiderwiz.tutorial.objectLib.Chat; import org.spiderwiz.tutorial.objectLib.ChatApp; import org.spiderwiz.tutorial.objectLib.ChatHistoryQuery; import org.spiderwiz.tutorial.objectLib.ChatMessage; import org.spiderwiz.tutorial.objectLib.ChatRoom; import org.spiderwiz.tutorial.objectLib.Chatter; import org.spiderwiz.tutorial.objectLib.ConsoleMain; import org.spiderwiz.tutorial.objectLib.LoginQuery; import org.spiderwiz.zutils.ZDate; /** * Provides the entry point of the application. Initializes and executes the Spiderwiz framework. */ public class ChatMain extends ConsoleMain{ private static final String ROOT_DIRECTORY = ""; private static final String APP_NAME = "Chat Room Client"; private static final String APP_VERSION = "Z13.01"; // Version Z13.01: Lesson 13 modifications private static final String JOIN = "!join"; // join a chat room command private static final String LEAVE = "!leave"; // leave current chat room command private static final String LOGIN = "!login"; // start login procedure private static final String LOGOUT = "!logout"; // log the user out private static final String REGISTER = "!register"; // start registration procedure private static final String HISTORY = "!history"; // print my chat history private String myName = null; // The user login name private ZDate birthday = null; // User birth date. Get it when logging in private ChatterConsume chatter = null; // A Chatter object representing the user chatting in a specific room private ChatMessage message = null; // A ChatMessage object for committing chat messages private Chat privateMessage = null; // A Chat object for committing private messages /** * Class constructor with constant parameters. * @param confFileName configuration file name, provided as a command argument */ public ChatMain(String confFileName) { super(ROOT_DIRECTORY, confFileName, APP_NAME, APP_VERSION); } /** * @return the class instance as ChatMain type. */ public static ChatMain getInstance() { return (ChatMain)ConsoleMain.getInstance(); } /** * Application entry point. Instantiate the class and initialize the instance. * * @param args the command line arguments. The first argument is used as the configuration file name. */ /** * @param args the command line arguments */ public static void main(String[] args) { // Don't do anything if there is no configuration file name if (args.length == 0) { System.out.println("Configuration file has not been defined"); return; } new ChatMain(args[0]).init(); } /** * Print user instructions to the console. * @return true */ @Override protected boolean preStart() { System.out.printf( "Welcome to the dynamic chat system.n" + "To log in type !login.n" + "To log out type !logout.n" + "To register type !register.n" + "To join a chat room or change your current chat room, type "!join <room name>".n" + "To leave your chat room, type "!leave".n" + "To send a message in the current chat room just type the message " + "(a message cannot start with either '>' or '!').n" + "To send a private message type '>' followed by name of the user you want to send " + "the private message to, followed by ':' for by the message.n" + "To print the history of your own messages, type "!history <hours>h" or "!history <days>d"n" + "(for instance "!history 3h" to see messages since 3 hours ago and "!history 1d" to see messages since 1 day" + " ago).n" + "or type just "!history" to see all your messages.n" + "To exit type 'exit'.n" ); return true; } /** * @return the list of produced objects - Chatter, Chat, ChatMessage and LoginQuery */ @Override protected String[] getProducedObjects() { return new String[]{ ChatApp.ObjectCode, Chatter.ObjectCode, Chat.ObjectCode, ChatMessage.ObjectCode, LoginQuery.ObjectCode, ChatHistoryQuery.ObjectCode, ObjectCodes.EventReport // Added in Lesson 13 }; } /** * @return the list of consumed objects - ChatRoom, Chatter, Chat, ChatMessage and ActiveUserQuery */ @Override protected String[] getConsumedObjects() { return new String[]{ ChatRoom.ObjectCode, ChatApp.ObjectCode, Chatter.ObjectCode, Chat.ObjectCode, ChatMessage.ObjectCode, ActiveUserQuery.ObjectCode }; } /** * Add implementation classes to the object factory list of this application. * @param factoryList */ @Override protected void populateObjectFactory(List<Class<? extends DataObject>> factoryList) { super.populateObjectFactory(factoryList); factoryList.add(ChatRoomConsume.class); factoryList.add(ChatApp.class); factoryList.add(ChatterConsume.class); factoryList.add(ChatConsume.class); factoryList.add(ChatMessageImp.class); factoryList.add(LoginQuery.class); factoryList.add(ActiveUserQueryReply.class); factoryList.add(ChatHistoryQueryInquire.class); } /** * Process an input line * @param line the line to be broadcast as a chat message. * @return true if processed successfully */ @Override protected boolean processConsoleLine(String line) { try { // If the line starts with '!' this is a command line if (line.startsWith("!")) { String command[] = line.trim().split("s+", 2); switch (command[0].toLowerCase()) { case JOIN: // if room name is provided join the room if (command.length > 1) joinRoom(command[1]); break; case LEAVE: // If the user is in a room, leave it leaveRoom(null); break; case LOGIN: login(); break; case LOGOUT: logout(); break; case REGISTER: register(); break; case HISTORY: if (myName == null) System.out.println("You must log in before requesting history."); else if (!getHistory(command.length < 2 ? null : command[1])) System.out.println("Invalid command argument"); break; } return true; } // If the line starts with '>' split the line on the colon (':') and send the test // after the colon as a private message to the user with the name before the colon. if (line.startsWith(">")) { String cmd[] = line.substring(1).split(":"); if (cmd.length < 2) return true; String destination = findUser(cmd[0]); if (destination == null) return true; // If didn't do yet, create an orphan Chatter object for sending private messages, // then prepare a ChatMessage object for sending private messages if (privateMessage == null) { privateMessage = createTopLevelObject(Chat.class, null); privateMessage.setName(myName); } // Set message and commit to destination privateMessage.setMessage(cmd[1]); privateMessage.setTime(ZDate.now()); privateMessage.commit(destination); return true; } // If this is a normal message, make sure the user is in a room and broadcast the message if (message != null) { message.setMessage(line); message.setTime(ZDate.now()); message.commit(); } } catch (Exception ex) { sendExceptionMail(ex, "Exception when processing an input line", line, true); } return true; } public String getMyName() { return myName; } public ZDate getBirthday() { return birthday; } /** * Get user name and password and log in. * @return a PrintStream object. Not needed by the caller but we use it as a trick to save coding. * @throws NoSuchFieldException If LoginQuery does not define ObjectCode static field. * @throws IllegalAccessException If LoginQuery.ObjectCode is not public. */ private PrintStream login() throws NoSuchFieldException, IllegalAccessException { String username; String password; // Check if already logged in if (myName != null) return System.out.printf("You are already logged in as %s. To log in with another name log out first.n", myName); // Create a login query LoginQuery query = createQuery(LoginQuery.class); while(true) { // Get user name System.out.printf("(type Enter to exit login)n"); username = readConsoleLine("User name:"); if (username.isBlank()) return exitLogin(); do { // Get password password = readConsoleLine("Password:"); if (password.isBlank()) return exitLogin(); // Post the login query query.setNewUser(false); query.setName(username); query.setPassword(password); query.post(5 * ZDate.SECOND); // If the query did not expire check login results, if it did, repeat. if (query.waitForReply()) { switch (query.getResult()) { case OK: myName = query.getName(); birthday = query.getBirthday(); return System.out.printf("Logged in successfully as %s.n", myName); case NOT_EXISTS: System.out.printf("User %s does not exist. Please try again.n", username); break; case WRONG_PASSWORD: System.out.printf("Password did not match, please try again.n"); break; } } else return unavailableUserManager(); } while (query.getResult() == LoginQuery.ResultCode.WRONG_PASSWORD); } } /** * Log out if already logged in */ private void logout() { if (myName == null) { System.out.printf("No user is logged in.n"); return; } leaveRoom(null); System.out.printf("%s is logged out.n", myName); myName = null; birthday = null; } private PrintStream register() throws NoSuchFieldException, IllegalAccessException { String username; String password, password2; // Check if already logged in if (myName != null) return System.out.printf("You are already logged in as %s. To register a new user log out first.n", myName); // Create a registration query LoginQuery query = createQuery(LoginQuery.class); while(true) { // Get user name System.out.printf("(type Enter to exit login)n"); username = readConsoleLine("User name:"); if (username.isBlank()) return exitRegistration(); do { // Get password password = readConsoleLine("Password:"); if (password.isBlank()) return exitRegistration(); // Repeat the password password2 = readConsoleLine("Repeat password:"); if (password2.isBlank()) return exitRegistration(); // Check if passwords are equal if (password.equals(password2)) break; System.out.println("Passwords do not match."); } while (true); // Get and parse birth date do { String s = readConsoleLine("Date of birth (yyyy/mm/dd):"); if (s.isBlank()) return exitRegistration(); try { birthday = ZDate.parseTime(s, "yyyy/MM/dd", null); } catch (ParseException ex) { birthday = null; System.out.printf("Invalid date %s. Please try again.n", s); } } while (birthday == null); // Post the registration query query.setNewUser(true); query.setName(username); query.setPassword(password); query.setBirthday(birthday); query.post(5 * ZDate.SECOND); // If the query did not expire check login results, if it did, repeat. if (query.waitForReply()) { switch (query.getResult()) { case OK: myName = username; return System.out.printf("Registered and logged in successfully as %s.n", myName); case EXISTS: System.out.printf("User %s already exista. Please try again with another name.n", username); break; } } else return unavailableUserManager(); } } /** * Print a message when login existed by typing a blank Enter * @return a PrintStream object. Not needed by the caller but we use it as a trick to save coding. */ private PrintStream exitLogin() { return System.out.printf("Login exitedn"); } /** * Print a message when registration existed by typing a blank Enter * @return a PrintStream object. Not needed by the caller but we use it as a trick to save coding. */ private PrintStream exitRegistration() { return System.out.printf("Registration exitedn"); } /** * Print a message when user management is not available * @return a PrintStream object. Not needed by the caller but we use it as a trick to save coding. */ private PrintStream unavailableUserManager() { return System.out.printf("No user management entity is available to handle this requestn"); } /** * Join a room after checking that the room exists, its adult setting matches user configuration, * and the user is not already there. If the user is in another room leave that room first. * @param room the new room name * @throws NoSuchFieldException If any of the created data objects does not define ObjectCode static field. * @throws IllegalAccessException If ObjectCode is not public. */ private synchronized void joinRoom(String room) throws NoSuchFieldException, IllegalAccessException { // User must be logged in if (myName == null) { System.out.printf("You must log in before joining a room.n"); return; } // Check whether room exists and the user is not already in the room ChatRoomConsume chatRoom = getRootObject().getChild(ChatRoomConsume.class, room); if (chatRoom == null) { System.out.printf("Room %s does not existn", room); return; } if (chatter != null && room.equalsIgnoreCase(chatter.getRoomName())) return; // Check if a young chatters is trying to join an adult room if (!chatRoom.canJoin(birthday)) { System.out.printf("You cannot join room %s because it is only for adultsn", room); return; } // Leave current room if any leaveRoom(null); // Join the application to the room ChatApp chatApp = chatRoom.createChild(ChatApp.class, getAppUUID().toString()); // Create a Chatter object for the user that joins the specified room chatter = chatApp.createChild(ChatterConsume.class, myName); chatter.setName(myName); chatter.setBirthday(birthday); chatter.commit(); // let everybody know I joined the room // Prepare a ChatMessage object for sending messages from now on message = chatter.createChild(ChatMessage.class, null); System.out.printf("Joined room %sn", room); } /** * If the user is in the given room, leave it. * @param room the name of the room to be checked if the user is there. If null, leave the current room without checking */ public synchronized void leaveRoom(String room) { if (isSameRoom(room)) { // Leave the room and let everybody know I did DataObject removed = chatter.remove(); if (removed != null) // can be null if the 'chatter' object has already been removed. removed.commit(); // Disconnect the application from the room and let every application know it did removed = chatter.getParent().remove(); if (removed != null) removed.commit(); System.out.printf("Left room %sn", chatter.getRoomName()); chatter = null; message = null; } } /** * Check if the user is in the same room as the parameter * @param room the name of the room to be checked if the user is there. If null, return true * @return true if the user in 'room' or 'room' is null */ public synchronized boolean isSameRoom(String room) { return chatter != null && (room == null || room.equalsIgnoreCase(chatter.getRoomName())); } /** * Get current room name, if any * @return if the user is currently in a room return the room name, otherwise return null. */ public synchronized String getCurrentRoom() { return chatter == null ? null : chatter.getRoomName(); } /** * Find the user whose name equals the parameter * @param name user name to look for * @return If a Chatter object for this user found then return the object ID of its grandparent, which is the UUID of the * application that the given user runs, otherwise return null. * @throws NoSuchFieldException If any of the referred data objects does not define ObjectCode static field. * @throws IllegalAccessException If ObjectCode is not public. */ private String findUser(String name) throws NoSuchFieldException, IllegalAccessException { FindUserFilter filter = new FindUserFilter(name); Collection<Chatter> users = getRootObject().getFilteredChildren(filter); // If the returned collection is not empty return the object ID (which is a UUID) of the first, // otherwise return null. for (Chatter user : users) { return user.getParent().getObjectID(); } return null; } /** * Execute !history command * @param arg command argument - <n>H or <n>D * @return true if command has been parsed successfully. * @throws NoSuchFieldException If ChatHistoryQuery does not define ObjectCode static field. * @throws IllegalAccessException If ChatHistoryQuery.ObjectCode is not public. */ private boolean getHistory(String arg) throws NoSuchFieldException, IllegalAccessException { // Parse the argument and calculate time ZDate since = null; if (arg != null) { arg = arg.trim().toLowerCase(); int n = Integer.parseInt(arg.substring(0, arg.length() - 1)); if (n <= 0) return false; int unit; switch (arg.substring(arg.length() - 1)) { case "h": unit = ZDate.HOUR; break; case "d": unit = ZDate.DAY; break; default: return false; } since = ZDate.now().add(-n * unit); } // create a query and post it ChatHistoryQuery query = createQuery(ChatHistoryQuery.class); query.setUsername(myName); query.setSince(since); query.post(5 * ZDate.SECOND); return true; } }
In line 110 we add ObjectCodes.EventReport to the list returned by getProducedObjects().
In order to easily test an exception, we change the parsing
of the !history
command to use Integer.parseInt() instead of ZUtilities.parseInt() (line 504). We do it
because the former throws an exception if its parameter is not a valid integer
number, while the latter does not.
And finally, in line 215, we catch every Exception type and call sendExceptionMail() to send an appropriate message.
Back to My Hub, we
modify HubMain
:
package org.spiderwiz.tutorial.lesson3; import org.spiderwiz.core.Main; /** * Main class for MyHub. As a hub, we neither produce nor consume any object. */ public class HubMain extends Main{ private static final String ROOT_DIRECTORY = "/tests/MyHub"; private static final String CONFIG_FILE_NAME = "hub.conf"; private static final String APP_NAME = "My Hub"; private static final String APP_VERSION = "Z13.01"; // Version Z13.01: Amend for lesson 13 public HubMain() { super(ROOT_DIRECTORY, CONFIG_FILE_NAME, APP_NAME, APP_VERSION); } /** * @return an empty list as we produce nothing */ @Override protected String[] getProducedObjects() { return new String[]{}; } /** * @return a list containing ObjectCodes.EventReport because this application can send mails. */ @Override protected String[] getConsumedObjects() { return new String[]{ObjectCodes.EventReport}; } }
Just add ObjectCodes.EventReport
to the list returned by getConsumedObjects().
We also need to configure the mail system in hub.conf
:
[log folder]Logs [consumer server-1]websocket;ping-rate=30 [producer server-1]websocket;ping-rate=30 [consumer server-2]port=10001 [spideradmin]iciDtSTUFzuD6+kno9TmiZtaFNlQ [hub mode]yes [mail system]smtp;server=smtp.gmail.com;user=tester@spiderwiz.org;pwd=dumptrump;port=465;ssl=true [from address]My Hub Alerts<alert@spiderwiz.org> [to email]Spiderwiz Administrator<spiderwiz.admin@gmail.com> [to exception email]Spiderwiz Programmer<spiderwiz.geek@gmail.com>
Of course, use your own parameters instead of the ones used here.
Now run all the services (or at least My Hub, User Manager and one chat application), login from a chat application and try to type:
!history 1od
(“by mistake” you typed the letter ‘o’ instead of zero in ”1od”
).
You get an exception, you see it on your console, and you will also get an email like this:
From: My Hub Alerts[alert@spiderwiz.org]
Sent: Wednesday, August 19, 2020 8:19
To: Spiderwiz Programmer[spiderwiz.geek@gmail.com]
Subject: An application exception in Chat 1 running at 192.168.1.5
An application exception in Chat 1 running at 192.168.1.5
Exception when processing an input line
Event time: 20/08/20-10:36:04:000
Sent by My Hub running at 192.168.1.5
Additional information:
!history 1od
Exception details:
java.lang.NumberFormatException: For input string: “1o”
at java.base/java.lang.NumberFormatException.forInputString(NumberFormatException.java:68)
at java.base/java.lang.Integer.parseInt(Integer.java:658)
at java.base/java.lang.Integer.parseInt(Integer.java:776)
at org.spiderwiz.tutorial.lesson13.chat.ChatMain.getHistory(ChatMain.java:504)
at org.spiderwiz.tutorial.lesson13.chat.ChatMain.processConsoleLine(ChatMain.java:180)
at org.spiderwiz.tutorial.objectLib.ConsoleMain.postStart(ConsoleMain.java:50)
at org.spiderwiz.core.Main.init(Main.java:411)
at org.spiderwiz.tutorial.lesson13.chat.ChatMain.main(ChatMain.java:69)
You get this email even though you did not define mail server parameters in the chat application. As you can see in the email, it was tunneled through My Hub.
Having done with the essentials of programming and debugging Spiderwiz applications, we will delve in the next lesson into SpiderAdmin – the powerful management service that comes free with every Spiderwiz-based project.