SoftArchDoc:Web2.0 CVRG Exception Handling Guidelines

Introduction

J2EE developers have found the try-catch paradigm in Java useful for gracefully reacting to errors. This enhances the user experience since many of these errors are infrastructure-related and should be abstracted from the user. Traditionally, the mindset is: user submits a request to the server, the server may or may not encounter errors, and the errors are presented to the user – sometimes in an unflattering way (think Microsoft’s Blue Screen of Death). In a Web 2.0 world an AJAX layer is typically employed. This means that the software engineer has to provide exception handling at the atomic level as well as the overall business domain.

Purpose

The purpose of this document is to provide some guidelines on how to plan and best use exception processing on a Web 2.0 platform. By adopting these guidelines the software that is engineered cannot only be re-used but easily modified as well. They will ultimately provide clarity and discipline in Web 2.0 software engineering effort.

Scope

The scope of this document is limited to the use of Google’s Google Web Toolkit. Although there are alternatives to Google’s GWT, such as ExtJS and ExtGWT, they will not be covered in this document.

Acronyms/Abbreviations & Definitions

References

Application Layers

To handle various processing exceptions it is a good idea to breakdown the application into its various layers. After all, it makes no sense to trap for invalid business logic when dealing with data object messaging. The most practical approach is detailed in Figure 2-1:

Figure 2-1 Application Layers

Presentation Layer Exception Handling

Figure 3-1 Presentation Layer

The above image in Figure 3-1 shows an error message that advises the user that the input was invalid. Presentation layer exceptions include invalid data formats, types, and missing required data. When encountering these types of exceptions consider the following guidelines:

1. Highlight the messages in red.
2. Display the message above the associated control (textbox, text area, date, etc).
3. To reduce confusion and enhance readability, use a slightly smaller font.
4. If applicable, highlight the background color of the control to provide emphasis
5. Once the exception has been addressed, remove the message.

Business Layer Exception Handling

Figure 4-1 provides an example of handling an exception that occurs in the business layer. Although the exception that is trapped in the sample code is a “catch all”, you can fine-tune the message based on the granularity on different exception types. When encountering these types of exceptions consider the following guidelines:

1. When encountering exceptions at the business layer trap for unexpected infrastructure issues.
2. For each exception encountered, append the description to an exceptions array.
3. Regardless of the size of the exceptions array, pass the array as a message element to the presentation layer

Figure 4-1 Sample Business Layer Exception Handling source code

When passing the message to the presentation layer as a result of the remote procedure call callback, the GWT automatically invokes an onFailure (Throwable caught) method (Figure 4-2):

Figure 4-2 Presentation Layer exception method invocation

Data Access Layer Exception Handling

Even though your application has detected clean input and valid business logic there are situations where you cannot satisfy a user’s request due to infrastructure issues. Databases can go offline, a network connection can be interrupted, an XSLT file can be removed/relocated/corrupted. When these types of issues occur it is best to encapsulate these conditions in a message. Figure 5-1 provides an example.

Figure 5-1 Sample Data Access Layer Exception Handling source code

If exceptions occur in this layer, again, append it to an array of exceptions and pass the message back to the presentation layer if necessary. The GWT framework will automatically invoke the onFailure method. In that method you can provide the user with any message that you deem informative. Please see Figure 5-2 (and Figure3-1.)

Figure 5-2 Sample Controller source code

Conclusion

Taking a systematic approach to handling unexpected (and expected) errors can help in engineering a bullet-proof and user-friendly application. No one wants to use buggy software that is riddled with ugly error messages. Also, when an application encounters a retrieval problem and the user is not advised as such, the user may interpret this as being unresponsive.

Of course, business analysis must be conducted to derive helpful exception messaging based on use cases. After all, the user doesn’t need to know that an underlying related table has encountered a unique key constraint violation. It is much more palatable to inform the user that, “a database error has occurred – please try again later”. This exception message can be issued to the user while the on-call staff is notified and engaged in reviewing the logs.

For more information:

• GWT Exception Handling tips
• Centralized messages (under section: Messages interface)