Providing meaningful errors in dojo.xhr calls

I've been working with Dojo lately, and one problem is the useless error messages one gets back from the server, especially when using dojo.xhr. The problem is that the response body from the server is generally some large HTML message that may not be useful for display purposes in an AJAX-based calling environment.

To remedy this, I made some modifications to the server-side (implemented in Java servlets) to capture exceptions and return a JSON structure if the request is an AJAX request. This makes it easier for the Javascript code to process error text more easily.

On the client-side, I have some basic utility functions to facilitate capturing/reporting errors from dojo.xhr calls.

First, the server-side:

Before I Start:

Before providing detail, I should note that I've created a base servlet
class that all my servlets sub-class. This allows me to centralize
operations and services for all my servlets. In the context of this post,
this becomes useful for the purposes of exception handling. The base
class checks all exceptions from sub-classes allowing centralization
of error handling based upon the type of exception that occurred.

I also have a custom request object to encapsulate the HttpServletRequest
and HttpServletResponse objects. This encapsulation allows me to add
support for additional capabilities beyond the standard servlet API
related to request/response. For example, I provide file-upload support
and still provide a single consistent interface for servlets to access
request parameters.

Some of the code provided here may contain references to custom classes I
use, but I believe they are self-explanatory.

How to detect an AJAX request:

  public boolean isAjaxRequest() {
    String reqwith = req.getHeader("x-requested-with");
    if (StringUtil.isBlank(reqwith)) return false;
    if (reqwith.toLowerCase().equals("xmlhttprequest")) return true;
    return false;
  }

The above works for most cases, and wrt Dojo, definitely works
since Dojo sets the proper request headers.

Capturing Servlet Exceptions:

In my base servlet class, I catch all exceptions:

    } catch (Exception e) {
      if (r.isAjaxRequest()) {
        log.error("Exception caught for AJAX request: "+e, e);
        sendJSONError(resp, HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
                      e.getMessage());
      } else {
        if (e instanceof ServletException) {
          throw (ServletException)e;
      }
       throw new ServletException(e.getMessage(), e);
      }
    }

I check if the request in an AJAX request, and if so, utilize the sendJSONError() method to do what I want. sendJSONError() looks like the following:

  private void sendJSONError(
      HttpServletResponse resp,
      int status,
      String message
  ) throws IOException {
    Writer w = resp.getWriter();
    resp.setStatus(status);
    resp.setContentType("application/json");
    w.write("{");
    w.write("\"status\":");
    w.write(Integer.toString(status));
    w.write(",");
    w.write("\"message\":");
    w.write(JSONObject.quote(message));
    w.write("}");
  }

Capturing/display Errors in Dojo:

On the client-side, I have two utility functions. One is a generic error handling function for dojo.xhr that will popup an alert displaying the error message received from the server. The other is a function to extract the error message from the servlet response, mainly for use by custom error functions that need to do more than display an alert dialog:

mylib.xhrErrorAlert = function(
    /*Object*/response,
    /*Object*/ioArgs
)
{
  var prefix = "Error: ";
  if (ioArgs.args.myAlertPrefix) {
    prefix = ioArgs.args.myAlertPrefix;
  }
  alert(prefix + mylib.getXhrResponseMessage(response));
}

mylib.getXhrResponseMessage = function(
    /*Object*/response
)
{
  var msg = response.message;
  if (response.responseText != undefined &&
      response.responseText.charAt(0) == '{') {
    try {
      var o = dojo.fromJson(response.responseText);
      if (o.message != undefined) {
        msg = o.message;
      }
    } catch (err) {
    }
  }
  return msg;
}

The following is an example of how to use the alert function:

dojo.xhrPost({
  url: url,
  handleAs: 'json',
  load: function(response, ioArgs) {
    ...
  },
  myAlertPrefix: 'Error doing something: ',
  error: mylib.xhrErrorAlert
});

Note, there is a reliance that the message text is meaningful in the exception thrown on the server-side. Regardless, this provides a better error message than what is normally available in response.message, which normally contains the canned message the server defines for the given HTTP response code versus the message text from the underlying exception.