The 15-minute Qworum tutorial

Introduction

At the end of this short tutorial, you will learn enough to start providing Qworum services from your website. You will also learn how to call the services of other websites. This tutorial requires basic XML and HTTP knowledge.

Note: This tutorial is somewhat out of date, because it makes intensive use of XML messaging which needlessly increase the traffic between web browsers and servers.
Instead, we recommend the use of JavaScript and HTML bindings for implementing and calling interactive services. Also, XML capability is not available on all Qworum browser add-ons.

Providing a Qworum service

The simplest possible Qworum service immediately returns an XML result message when it is called. Here is a call to a simple service, available at http://www.asoftware.com/latest_release, that returns information about the latest release of a software product:

The content type of Qworum messages is application/xml. Here is the same call in more detail (some HTTP headers are missing or simplified for convenience):

A more advanced service call may involve two or more request/response pairs. In that case, only the last response contains a result message: previous responses may contain (X)HTML web pages, HTTP redirections or Qworum composition messages (as described in the next section). Here is a call to a secure payment processing service, available at https://www.apaymentprocessingsite.com/process_payment, which interacts with the end-user through web pages (for credit card details, etc):

Note that this service receives the payment details in an XML document with the content type application/xml.

Qworum imposes the following requirement on (X)HTML pages sent by services to user agents: if the page generates a request (for exemple when the end-user clicks on a link or submits a form) that is part of the service call, then it should be displayed in the same tab/window as the page issuing the request. Otherwise a new tab/window should be assigned to the request by using the _blank target for hyperlinks and forms, as shown in the example above.

Qworum only handles top-level frames of tabs/windows; the contents of frames or iframes are simply ignored.

Calling a Qworum service

In a typical scenario, a website initiates a service call by sending a composition message to the user agent. The user agent then performs the call on behalf of the website, based on the instructions contained in the message. Later, when the user agent receives a result message, it sends the result to the caller, as specified in the composition message.

Here is how a website would call the Qworum service http://www.asoftware.com/latest_release:

The end-user would experience this call as two consecutive redirections:

Composition messages may include a call parameter that will be sent to the called service. For example, an e-commerce site may call the payment processing service (mentioned before) as follows:

The end-user would experience two redirections, one at the beginning of the call, and one at the end of the call:

Conclusion

The power of Qworum resides in its support of interactive services. Additionally, it trivially supports RPC-style services.