The 15-minute Qworum tutorial

Introduction

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

Providing a Qworum-based service

The simplest possible Qworum-based 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 result message should not contain any element with the namespace http://www.qworum.com/, and its content type should be application/x-qworum+xml. If a message that has this content type is stored in a file, then the suggested filename extension is .qrm, as in result.qrm. Here is the same call in more detail (some HTTP headers are missing or simplified for convenience):

Note that the Accept request header contains application/x-qworum+xml;version=1.2 in its value: this indicates that the latest version of the Qworum specification implemented by the user agent is 1.2. Also note that the User-Agent request header contains Qworum/1.2.0.0.

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 contain (X)HTML web pages, HTTP redirections or 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-based service

Qworum-based services are called by websites, rather than client computers.

The calling website initiates the 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. The user agent uses an internal call stack for handling composition and result messages.

Here is how the service at http://www.asoftware.com/latest_release would be called:

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

Composition messages may include a call parameter. Call parameters must not contain any element with the namespace http://www.qworum.com/. 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. Additionaly, it trivially supports RPC-style services. Qworum-based services may span several servers, and they may in turn call other services during their execution.