Message - Server to User Communications

What happens when a user fills in a form and presses the submit button? If all goes well he will move on as expected. But what if the data in the form is not adequate to the task? Perhaps a field was not filled in, or business logic dictates that the answers do not match. The server code needs to stay on the same form and give meaningful messages.

Enter the Messages class. It is designed to be used by the SOA tier, although in truth it can be used at whichever layer knows enough to be able to give the user meaningful feedback. The user does not want to be confused by being told that idxdb43a has a duplicate entry. They want to be told that they have already registered and should type in their password.

Generally messages are created by the validation code and business logic. Sometimes, as above, the business tier creates a message based on an error reported by a more technical tier.

Retrieving the Message List

Messages that relate directly to the converstation between user and machine can be retrieved with the getThreadInstance() method. A conversation interchange between browser and server runs on a single thread. The thread message instance is cleared as soon as the browser communicates to the server. Messages are collected here during server processing. Once complete the messages are sent to the browser as part of the response.

Messages can also be held in the session and retrieved with getSessionInstance(). Used to collate messages from non-interactive threads with information for the user. A classic example is an alarm or countdown timer.

The Message Structure

Because I designed the message system for thin-client browser/server applications, messages needed a text based structure. Consequently a message consists of key and display parts separated by double colons (::).

key::this is the message portion to display

 

In the most basic form, you can add a message without a key. It is saved under the special global key of start (*). The following three add() statements are identical:

Messages messages = Messages.getThreadInstance();
messages.add( "This is a global message");
messages.add( "*::This is a global message");
messages.add( "*", "This is a global message");

 

Reporting Programming Errors

In many environments I have worked in it was common practice for programming errors and system problems to throw an exception that was then passed all the way back to the client. Said client then gets an generic error page and the thrown exception is written to the log. I do not consider this acceptable. All complex systems will generate unexpected errors and attempt to pass them back to the user. If these message are processed like any other, the user has the opportunity to work around the issue. Message in these curcumstances should include a key to be used by support staff to investigate the log. Messages does this with overloaded add() methods that take a Throwable argument. Since exception messages are less likely to be understood by a user, it includes an automatically generated reference to the log that support staff can use to track down the issue.

Device /dev/hd1 out of space (see log reference 20050722-21:44:53.531)

 

When to Generate a Message List

The Service or business tier needs to process a user request and send back the results for the user to read. If exceptions were to be used in their basic form, the user would get a single problem reported. Once this is fixed and the request submitted again the next problem is found and reported again. We have all worked with systems such as this - when we have to. They are very frustrating. It is far better to find and report on as many problems together. The user can then fix them in one pass also.

With Messages the code continues to work until it finds a problem that stops further processings. It then passes the menu structure back to the GUI tier for display. Actually it does not need to pass it since the GUI tier can also retrieve a reference using the static method getThreadInstance().

A typical service may work as follows:

Messages problems = Messages.getThreadInstance();
validateData( data):
if (! problems.none()) return;
applyBusinessRules( data);
if (! problems.none()) return;
writeResults( data);
if (! problems.none()) return;
commitAllProcessing();

 

Why Do Messages Have Keys?

When the messages are retrieved, they are sorted in key order with the message for a key being stored in a multi-line string in the order they were generated. The use for multiple keys is implementation dependant. It can be used to ensure that messages are sorted by priority, associated with fields, or both. The GUI, for example can cycle through the messages. Those with a key the same as an input field can be displayed beside that field while others can be listed in a special messages region. Since the general messages are sorted alphabetically, they can be given a numeric key with the highest priority having the lowest number. It would even be possible to assign different colours for different priority messages:

0: Urgent error message (typically system failure) - displayed in bright red.
1: Validation or similar error message - displayed in dark red.
2: Warnings - displayed in orange.
3: Informational messages - displayed in blue.

 

Note that these are examples only. Implementation is dependant on the user of the Message class.

How Messages are Retrieved

If keys are not used at all in the application, getGeneral() can be used to retrieve all the messages. Otherwise, firstKey() and nextKey() are used to retrieve each message group, with get() for retrieving the messages for the group.

for (String key = messages.first();  key != null;  key = messages.next())
  displayMessages( key, messages.get( key);

 

The messages retrieved by get() are an array of the messages. The array is in the order the messages were generated by the application.