JSF 2: Ajax Events and Errors

Today I want to look at how to handle Ajax events and errors in JSF 2.

JSF 2’s Ajax support includes a very basic facility to listen for events and errors within JSF’s client side processing code. It’s envisioned that this will primarily be used by component developers that wish to monitor events – for instance, turning an image yellow when there’s an outstanding Ajax request, and black when there isn’t.

So, without further ado, here’s a few snips of code from Mojarra’s ajax-queue demo:

In a page with some Ajax calls, we have the following field:

<h3> Status:</h3>
<textarea id="statusArea" cols="40" rows="10" readonly="readonly" />

A simple textarea, not even hooked into the backend server data model.

Then in our javascript (for the demo, in a separately loaded file, though it could just as easily be in page) we have:

var statusUpdate = function statusUpdate(data) {
    var statusArea = document.getElementById("statusArea");
    var text = statusArea.value;
    text = text + "Name: "+data.source.id;
    if (data.type === "event") {
        text = text +" Event: "+data.name+"\n";
    } else {  // otherwise, it's an error
        text = text + " Error: "+data.name+"\n";
    }
    statusArea.value = text;
};

// Setup the statusUpdate function to hear all events on the page
jsf.ajax.addOnEvent(statusUpdate);
jsf.ajax.addOnError(statusUpdate);

When run, you'll see a stream of data going through the textarea as ajax events happen elsewhere in the page. Try out the demo to see more. (Again, it's in the Mojarra codebase, under jsf-demo/ajax-queue)

What's happening: first we define a JavaScript function, place it in a variable, and then call two JSF ajax api functions: addOnEvent and addOnError. These functions use the statusUpdate function as their callback, passing the data object as it's first parameter.

That data object, along with the functions themselves, are defined in Section 14.4 of the JSF 2 specification. I'll outline a little of what's in there here, but be sure to check it out for the full scoop - it's a pretty easy to read and understand part of the spec.

For Events, there are three named events: begin, complete, and success.

• begin - happens before the request is sent.
• complete - happens once the request has completed, before javax.faces.response is called.
• success - happens after the response method finishes.

This means that for a normal request, all three will be called, while if there is some sort of error, then only begin and complete will be called.

For Errors, there are four named errors possible.

• httpError - happens if the client receives any HTTP status other than something between 200 and 299, inclusive.
• emptyResponse - happens when the connection is dropped without a response.
• malformedXML - means that the XML that was received couldn't be parsed correctly.
• serverError - what happens when an error is generated on the server and transmitted back to the client.

The data payload consists of:

• type - one of event or error
• name - the name of the error or event, as above.
• source - the DOM element that triggered the event (which is why you can see a data.source.id access in there, to get the id of the element)
• for errors named serverError, there's also an errorName and errorMessage field, for passing through server errors.
• plus responseCode, responseXML, and responseTxt, as in the XMLHttpResponse object.

So, when to you need to use this functionality? Probably not very often. But since it's not really documented anywhere else yet, I wanted to get some description out there for what it does.

(This article originally published on my java.net blog on May 15, 2009.)