The upcoming version 1.5 of qooxdoo will ship with a new IO stack. The old stack will still be included, but we recommend you take a look and consider using the new stack, especially when beginning a new project.

Why change?

The old IO stack has served well. It is powering many complex AJAX applications and proved to be very reliable. However, it failed to keep up with recent developments of browser vendors and the framework itself. For example, it is not possible to request cross-origin domains with XMLHttpRequest without resorting to dirty hacks, and no integration to data binding is provided at a lower level. Moreover, back when the old layer was implemented qooxdoo’s testing framework was not as complete as it is today which resulted in a rather rudimentary test coverage.

We decided to rewrite the IO layer from scratch, in a test-driven manner. On our way, we’ve revisited some of the key design decisions, always considering recent browser developments. In some cases this resulted in fundamentally new approaches.

Design decisions

Maybe the biggest change from the user’s point of view is that the underlying transport is chosen explicitly by using an appropriate class. In other words, we removed the abstraction that was choosing a transport based on requirements given by the user. While this abstraction seems very user-friendly, we noticed many were confused that changing a single property could result in a totally different behavior. Also, it is hard to get the most out of each transport when you always have to think of the abstraction layer above, both in terms of implementation and documentation. The downside of letting the user choose, of course, is that we demand a little bit more background knowledge. In what we consider a good sign of an active community, it was no surprise that some controversy was raised.

Another change reduced a considerable amount of complexity. Not very widely known, the old transport queued each request before actually sending it. This queue was mostly introduced to work around an obscure bug found in legacy versions of IE running on old platforms. It turned out this bug was fixed on all relevant versions of Windows. Keeping unnecessary features out for the sake of simplicity, there is no queue in the new transport.

Quick overview

Going from lowest to highest level, let’s quickly walk through the whole new IO stack.

Classes found in qx.bom.request (API) deal with low-level transport. Xhr is a wrapper of the HTTP client API offered by the browser. Its purpose is to hide inconsistencies and to work around bugs found in popular implementations. Script is a script loader. Internally, the class deals with adding and removing script tags to the document and keeping track of the load status. Jsonp builds on the script loader and adds functionality needed to receive JSONP responses. All transports share an interface similar to XMLHttpRequest as specified by the W3C (spec, interface).

Higher level classes found in qx.io.request (API) build on the groundwork laid by the low-level transports. Xhr interfaces the low-level Xhr transport, likewise Jsonp. They add more convenience to handling requests. For example, properties allow to conveniently setup a request, and fine-grained events facilitate handling changes of the request’s status or response.

At an even higher level, stores in qx.data.store (API) were changed to use the new transport layer. If you use the stores, there is usually nothing for you to do. The transport is an implementation detail you don’t have to take care of. Except if you’re configuring the request with a delegate, but please refer to the API documentation in that case.

Some highlights

In the life-cycle of a request many things can happen. For example, a request can be invalid, time out or be aborted by the user. The server can respond with either a success or error status. To keep track of the phase your request is in and make your application respond to it, a request provides a number of getters (e.g. getPhase()) and fires many events you can listen to. The list of events is quite extensive and goes beyond what the W3C has specified.

  req.addListener("statusError", function() {
    // Unexpected response
  }, this);

The following state diagram shows the phases (states) a request can be in, together with the methods or events that trigger state transitions.

Most of the time, the whole point to making requests is to fetch a representation of a resource, say a JSON file. When following best-practices on the server side, the response is parsed automagically thanks to response content type handling. If this does not work for you, the parser can of course be explicitly set. Or, as a last resort, you can write your own parser.

  req.setParser("json");

Dealing with authentication subsystems is a frequent requirement. We streamlined the implementation of authentication by introducing a property that can be passed a delegate. This delegate only needs to implement a single method – the rest is up to your special requirements. To get an idea how a real world implementation may look like, we added a ready to use delegate handling HTTP basic authentication.

  var authentication = new qx.io.request.authentication.Basic("user", "password");
  req.setAuthentication(authentication);

JSONP is an increasingly popular transport method offered by many web services. However, handling callbacks and wiring them with the rest of your system can be tricky. With the new implementation, the hard work is done behind the scenes and even works for services that do not allow setting a custom callback name.

  // Handle fixed Flickr callback
  req.setCallbackName("jsonFlickr");

Data binding is a core concept of qooxdoo. With the new higher level transport layer, you can easily bind the response of a request to other objects.

  req.bind("response", label, "value");

Modularity is a key principle of the new implementation. For instance, low-level transports are loosely coupled and have a well defined interface. This allows alternative transports to be used interchangeably by higher level layers.

Further reading

You can read more about the new IO stack in the manual and the API docs (qx.bom.request, qx.io.request). If you know qooxdoo’s testing framework you might also want to take a look at the unit tests, as they include many examples (qx.test.bom.request, qx.test.io.request).

The bottom line

The new IO classes (qx.bom.request.*, qx.io.request.*) are not a drop-in replacement of the old ones (qx.io.remote.*). For one thing, you choose a transport by selecting an appropriate class. Also, events and properties are named differently and even if the events have the same name, they don’t necessarily need to have the same semantics.

With the new IO stack you get some added convenience, fine-grained events, integration to data binding and generally more freedom to explore new browser features.

You think something does not fit quite right? Found a bug? You happen to like the new implementation? Please tell us, your feedback is very welcome!