Handling Exceptions

Shown below is a meta capsule marked with the errorPage attribute. This attribute tells the WebRocketX framework that this content was produced by a server side exception and that the developer's successful callback should be skipped and instead the developer's failure callback should be called (failure callbacks are rarely needed actually). The contents of the capsule will still be displayed according to the capsule type. So, the developer is free to display server side exceptions anyway they choose. In this case, the exception is being displayed as a modal popup. The divs wrapping the table are stylings that float and center the content.

The errorPage attribute could have also been combined with a capsuleType of "inline" and maybe a message to call support could have been displayed in the header every time. Another option is the errorPage attribute could have been combined with a capsuleType of "data" and a jsOnload could have been used to execute some browser side logic. The clearing of a server side error message written to the header is usually done when the user navigates to other parts of the application. The globally defined dtNavigationCallback function can be overridden by the developer to do this. See the Calling The API page for more details.

Web application frameworks such as Spring, Struts, and JSF already provide mechanisms for channeling all unhandled server side exceptions to a single page. When using WebRocketX this page should be one rendering our capsule marked with the errorPage attribute. Often the content inside this capsule will contain a toll free number for the user to call for support along with an error number that support can look up in their server logs. It is a good idea to branch the logic of your error page to behave differently in development and QA vs. production. In a non-production environment it is nice to have a full stack trace displayed so that tracking down errors can be done efficiently.

Communication errors are caused when either the browser cannot successfully communicate with server or receives a response it cannot understand. Since the server cannot be reliably reached, WebRocketX solves this problem by requiring a specialized modal dialog layout be present in the welcome page of the SPA application. For more details on this go to the Welcome Page part of this tutorial. Below are listed the most common communication errors that can occur. The will all be handled automatically by WebRocketX as long as the communication error modal dialog is formatted correctly.

• Metacapsule missing - The framework could not find the Metacapsule in the content returned from the server. This is actually a very powerful mechanism because many modes of failure on the internet return a blank page or a garbled response, and by expecting a predictable format the WebRocketX framework will not:
  1. Hang
  2. Mysteriously "do nothing"
  3. Display a bunch of weird symbols in your web page
  4. Feed something to a javascript function that causes it to throw an incomprehensible error
  
  
• Async call timed out - The call took too long to come back and the browser gave up on it.
  
  
• HTTP Error Codes - Any call that resulted in a code other than 200 or 202, which are both types of successful.
  
  

Session timeouts are tricky in an Ajax SPA (Single Page Application) because servers typically are configured to return the sign in page when a users session is no longer valid. In an Ajax SPA, this by default will result in the sign in page suddenly appearing as a subsection of the users current page or being unexpectedly fed as input to a javascript call and blowing up. WebRocketX handles this situation by requiring that the sign in page be marked, so that when it comes back unexpectedly from a call, the framework can then send the user the full page refresh version of the sign in page. WebRocketX expects that the sign page for a SPA web application be a stand alone page and that the welcome page, after authentication, is the actual entry point to the SPA. For more information on how to mark your sign page and tell the framework where to go when it is encountered see the Welcome Page tutorial.

If the application is well coded the user should never see a javascript error. Regardless WebRocketX attempts to make javascript produced errors as intelligible and meaningful as possible. For example, exceptions that occur in callbacks will be displayed in javascript alerts and designated as coming from a callback. Also, bad input to WebApi calls will produce meaningful alerts that instruct the developer on where they went wrong.