Skip to main content

JSF 2: Ajax Events and Errors

Posted by driscoll on May 15, 2009 at 4:06 PM PDT

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: ";
    if (data.type === "event") {
        text = text +" Event: ""\n";
    } else {  // otherwise, it's an error
        text = text + " Error: ""\n";
    statusArea.value = text;

// Setup the statusUpdate function to hear all events on the page

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 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.


Thank you for that. I found another different documentation ...

Thank you for that. I found another different documentation for the jsf.ajax.addOnError function

AJAX Exceptions on the Server side

Hi and thanks for your great blog. Can you give a hint on how to catch/process Excetions that happen during an AJAX request on the server side? All I get is logging output, like:
com.sun.faces.context.PartialViewContextImpl$PhaseAwareVisitCallback visit
SEVERE: javax.el.ELException: /some.xhtml
Thanks, Steve

The tutorial will be done for Java EE 6, just as for Java EE 5 - at the end of the process. In the meaning, there's javadoc, pdldoc, renderdoc and jsdoc, all available as part of the spec bundle.

I want to ask you if there is a reference documentation for JSF 2.0 as it's for JSF 1.2 (at SUN JEE tutorials) ? Thanks