Qworum core specification, version 1.0 Draft

Abstract

Qworum brings modularity to web applications by allowing them to be composed of interactive services called Qworum services. Websites and Qworum services may call services located on the same site or on other sites. Qworum services may also be called directly by RPC clients that do not support interactivity. Qworum defines a web format called the Qworum message which needs to be supported by user agents (i.e. web browsers and RPC clients).

Introduction

Purpose
Requirements

Service composition

Multi-phase service calls
Special case: the World Wide Web
Special case: RPC
The user agent as mediator for service calls

Messages

Message format
Message evaluation by the user agent
The http://qworum.net/ XML namespace
The application/x-qworum+xml media type
The .qrm file extension

Statements

The call statement
The data statement
The fault statement
The goto statement
The if statement
The nil statement
The return statement
The select statement
The sequence statement
The transform statement
The transient statement
The try statement
The variable statement

Implementations

Additional specifications

The configure statement

Appendices

References
Revision history
Copyright and disclaimer

1. Introduction

1.1. Purpose

The World Wide Web is a system of interlinked hypertext documents accessed via the Internet. Although its initial purpose was to provide an infrastructure for information, the World Wide Web is increasingly being used for web applications, which arguably have additional infrastructure needs.

In this context, Qworum defines a standard for decomposing web applications into reusable services. The services that make up a web application do not need to reside all on one single server. With Qworum, the barriers that exist between websites are largely overcome, so that websites can provide services to each other much more easily. In particular, websites can provide interactive services that seamlessly integrate into other websites.

For service providers, the advantage of using Qworum is that services can be interactive as a regular website, or non-interactive as a remote procedure call. In fact, the same service may be interactive during one call, and non-interactive during the next one. In other words, Qworum unifies the World Wide Web and remote procedure call concepts.

Qworum makes use of a specific web message format, which offers functionality that is orthogonal to that of existing web formats such as HTML. As a result, the Qworum specification is expected to evolve independently from those standards.

The present specification provides relevant information for the following groups:

Developers of Qworum services, and
Developers of user agents.

1.2. Requirements

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [Keywords].

2. Service composition

Qworum is based on the concept of multi-phase services. The service composition mechanism used by Qworum is directly derived from this concept, and explains the design choices made by Qworum. This and related concepts are described below.

The term phase refers to the following three consecutive steps:

a user agent sends a request to a server,
the server performs an operation based on the request and produces a response,
the user agent receives the response from the server.

A phase

According to this definition, conventional remote procedure calls (based on XML-RPC for instance) always consist of a single phase.

The term service refers to a software functionality available on a computer, and used by programs on other computers through network connections. In the context of Qworum, a service is available at a URL that has an http or https scheme, and services are identified by their URL.

2.1. Multi-phase service calls

The term multi-phase service refers to a service whose calls consist of one or more phases.

A multi-phase service call may span several servers, and terminates when the user agent receives a response containing a result message.

In order to continue the current call, a phase may return a response that does not contain a result message. In this case, the user agent will try to use the message for initiating the next phase of the current call. When the HTTP protocol is used, HTTP redirections and interaction messages such as HTML pages allow such call continuations. Another way of performing call continuations is through the use of composition messages.

A multi-phase service call consisting of three phases, using the HTTP protocol

2.2. Special case: the World Wide Web

The multi-phase service call concept is more general than the World Wide Web paradigm.

Indeed, a web browsing session inside a browser tab (or window) is equivalent to a multi-phase service call which never returns a result, and which never calls other services by using the proposed composition mechanism.

2.3. Special case: RPC

The multi-phase service call concept is also more general than the concept of remote procedure call: a multi-phase service call consisting of a single phase is equivalent to a conventional remote procedure call.

2.4. The user agent as mediator for service calls

According to the proposed composition mechanism, a service calls another service as follows:

The calling service sends a composition message to the user agent.
Based on the instructions contained in this message, the user agent then performs the service call, between two consecutive phases of the calling service.
The service call terminates when one of its phases sends a result message to the user agent.
The user agent then sends the received result to the calling service, at a URL specified in the composition message previously received.

Service composition: a service on a first server calls a service on a second server

Qworum does not impose any restrictions on the number of nested calls: a service may call another service, which calls another service, which calls yet another service, etc. A service may also make recursive calls to itself.

3. Messages

3.1. Message format

Qworum defines an XML [XML] message format that supports the basic service composition pattern described in the previous section.

Here is a result message that might be returned by an e-mail lookup service:

<email>john.smith@email.com</email>

And here is a composition message used for calling the e-mail lookup service (goto describes the next phase of the current call, and call describes the service call to be performed by the user agent on behalf of the current call):

<qrm:goto href='receive_email_address' xmlns:qrm='http://qworum.net/'>
  <qrm:call href='email_lookup'>
    <name>John Smith</name> <-- call parameter -->
  </qrm:call>
</qrm:goto>

Qworum messages also enable more advanced usage patterns. Here is a message which is neither a pure result message, nor a composition message (this particular message might be described as a result message with parts provided by service calls):

<emails>
  <qrm:call href='email_lookup' xmlns:qrm='http://qworum.net/'>
    <name>John Smith</name>
  </qrm:call>
  <qrm:call href='email_lookup' xmlns:qrm='http://qworum.net/'>
    <name>Jack Smith</name>
  </qrm:call>
</emails>

3.2. Message evaluation by the user agent

Qworum messages are scripts, rather than human-centric documents. Each message consists of one statement, corresponding to the root XML element.

Upon receiving a message, the user agent MUST start evaluating it using the latest Qworum specification that it supports. Specifications are backward-compatible, meaning that if a message conforms to one version of the Qworum specification, then it conforms to all subsequent versions as well.

Most statements yield a result when evaluated. For example, the call statement:

<qrm:call href='email_lookup' xmlns:qrm='http://qworum.net/'>
  <name>John Smith</name>
</qrm:call>

yields a call result, which might be:

<email>john.smith@email.com</email>

And the data statement:

<emails>
  <qrm:call href='email_lookup' xmlns:qrm='http://qworum.net/'>
    <name>John Smith</name>
  </qrm:call>
  <qrm:call href='email_lookup' xmlns:qrm='http://qworum.net/'>
    <name>Jack Smith</name>
  </qrm:call>
</emails>

might yield:

<emails>
  <email>john.smith@email.com</email>
  <email>jack.smith@email.com</email>
</emails>

The following statements disrupt the flow of evaluation, and consequently do not yield a result:

goto
return
fault

Message evaluations are interrupted during a service call; they resume when the call terminates. A message evaluation ends when:

the next phase of the current call is initiated, or
the current call terminates.

The next phase of the current call is initiated when a goto statement is evaluated.

The current call terminates when:

the main statement (represented by the root XML element) yields a result, or
a return statement is evaluated, or
an uncaught fault is evaluated.

The user agent maintains an internal call stack for handling service calls. In the case of a web browser, each tab or window has a call stack associated with it.

Call stacks initially contain one frame, which represents the main service call. Call frames are used for storing variable values and messages whose evaluations were interrupted by service calls. The topmost call frame, corresponding to the current service call, does not contain any message.

3.3. The `http://qworum.net/` XML namespace

Qworum defines an XML vocabulary that is used in messages. All elements of this vocabulary belong to the http://qworum.net/ namespace [XMLnamespaces]. Elements belonging to this namespace are also referred to as Qworum elements. Elements that do not belong to this namespace are also referred to as non-Qworum elements.

All statements are described by a Qworum element, except the data statement. Some Qworum elements, namely title and catch, do not describe a statement but are part of an enclosing statement.

3.4. The `application/x-qworum+xml` media type

The media type of Qworum messages is application/x-qworum+xml (media types are explained in the section 3.7 of the HTTP/1.1 specification [HTTP/1.1]). It has an OPTIONAL parameter named version.

User agents which implement the present version of the Qworum specification SHOULD include one of the two following values in the Accept headers of the HTTP(S) requests they generate:

application/x-qworum+xml
application/x-qworum+xml;version=1.0

For example, a Qworum-enabled web browser might generate the following request header:

Accept: application/x-qworum+xml,text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5

Similarly, an RPC client for Qworum services might generate the following request header:

Accept: application/x-qworum+xml;version=1.0

If an HTTP(S) response contains a Qworum message, then servers MUST send this media type as the value of the Content-Type header. The version parameter SHOULD NOT be included in this header; the user agent MUST ignore it if present. For example, an HTTP(S) response containing a Qworum message might include the following header:

Content-Type: application/x-qworum+xml

3.5. The `.qrm` file extension

The RECOMMENDED extension for files containing a Qworum message is .qrm. For example, a file containing a message that calls a payment processing service might be named payment_processing_call.qrm.

4. Statements

4.1. The `call` statement

The call statement initiates a multi-phase service call. The evaluation of this statement is interrupted until the call returns a result. The evaluation then ends by yielding the call result.

call elements MAY have an href attribute which indicates the URL of the first phase of the service to be called. The value of the href attribute MUST be an absolute HTTP or HTTPS URL [URL], or a relative URL [RelativeURL]. An absent href attribute is equivalent to an href attribute whose value is the URL of the message containing the call statement, and a relative URL is resolved using the message URL. For example, a request to http://www.ahost.com/path may return any one of the following messages; they will all initiate a call by sending a GET request to http://www.ahost.com/path:

<call xmlns='http://qworum.net/' />

<call href='path' xmlns='http://qworum.net/' />

<call href='http://www.ahost.com/path' xmlns='http://qworum.net/' />

call elements MAY contain a statement called the parameter statement. If the parameter statement is present, then the following sequence of events occur:

the parameter statement is evaluated,
the evaluation result of the parameter statement is put into a call variable named call parameter, so that all phases of the call to be performed have easy access to it,
the call is initiated with a POST request whose body (which has the content type application/xml) contains the evaluation result of the parameter statement.

call elements contain zero, one or more title elements which briefly describe the call. An OPTIONAL lang attribute indicates the human language that is being used. Accepted values for this attribute are described in the section 3.10 of the HTTP/1.1 [HTTP/1.1] specification. title elements MUST NOT contain any elements.

For example, the following statement:

<qrm:call href='https://www.apaymentprocessingsite.com/process_payment' xmlns:qrm='http://qworum.net/'>
  <qrm:title>Calling the payment processing service ..</qrm:title>
  <payment>
    <description>1 x 1-year subscription for "A Business Magazine"</description>
    <total>98.95</total>
    <currency>USD</currency>
    <merchant>payments@anecommercesite.com</merchant>
  </payment>
</qrm:call>

sends a POST request to https://www.apaymentprocessingsite.com/process_payment, and the request body (as well as the call variable named call parameter) contains:

<payment>
  <description>1 x 1-year subscription for "A Business Magazine"</description>
  <total>98.95</total>
  <currency>USD</currency>
  <merchant>payments@anecommercesite.com</merchant>
</payment>

User agents take the following security measures when evaluating call statements:

If a call statement is redirecting the user agent from a private or local site to an internet site (a URL is considered to point to an internet site if its host part is a fully qualified domain name that ends with a top-level domain [TLD], or if it is an IP address [IPaddress] that is neither private nor local [Loopback]), then the user agent MAY choose not to send the actual referrer URL in the Referer HTTP header. Instead, this header MAY be absent or it MAY contain a URL that is derived from the Intranet Assigned Domain Name [DRM/1.0], such as http://mycompany.com/.
call statements MUST NOT redirect user agents from an internet site to a private or local site. In this case, user agents MUST raise an authorization fault instead of evaluating the call statement.

Internet-to-intranet redirections are prevented by user agents

4.2. The data statement

Data statements are non-Qworum elements that MAY have other non-Qworum elements or statements as descendents. Their evaluation ends when all descendent statements have been evaluated in a depth-first manner. For example, the statement:

<emails>
  <qrm:call href='email_lookup' xmlns:qrm='http://qworum.net/'>
    <!-- this call is evaluated first -->
    <name>John Smith</name>
  </qrm:call>
  <qrm:call href='email_lookup' xmlns:qrm='http://qworum.net/'>
    <!-- this call is evaluated second -->
    <name>Jack Smith</name>
  </qrm:call>
</emails>

may yield:

<emails>
  <email>john.smith@email.com</email>
  <email>jack.smith@email.com</email>
</emails>

And the following statement remains unchanged after evaluation.

<name>John Smith</name>

4.3. The `fault` statement

The fault statement indicates an error condition that prevents a service call from proceeding normally. Faults can be caught and handled by try statements. Fault example:

<fault xmlns='http://qworum.net/' />

Faults are classified into types which narrow down the underlying cause of an error condition, so that user agents are able to handle each type of fault separately.

Fault types

Faults of type service or one of its subtypes indicate that the error condition is due to the service which is currently being called. Such faults can be explicitly raised by services. They MAY also be raised by the user agent. In the latter case, some possible causes are:

The user agent received a Qworum message that does not conform to the present specification.
The user agent received an invalid HTTP(S) response.
The user agent received an HTTP(S) response that indicates a server-side issue (examples: 500 Internal Server Error, 501 Not Implemented).

Faults of type network indicate that the user agent is unable to execute a call phase, either because it cannot find and connect to the server, or because it was disconnected before it could receive a complete HTTP(S) response. In this situation, the user agent MAY act as if it has received a Qworum message that contains a single network fault.

Faults of type user agent indicate that a user agent issue prevents the current call to proceed normally. The user agent MUST raise a user agent fault if it is unable to evaluate a valid Qworum statement, for example because of an internal error. The user agent MAY also raise a user agent fault if it receives an HTTP(S) response that indicates a client-side issue (such as a 400 Bad Request or 408 Request Timeout response).

user agent has a subtype called authorization which applies to situations where a statement could not be evaluated because of authorization issues (see call, goto).

User agents MAY raise a user fault if they receive an HTTP(S) response that requires interacting with the end-user in order to continue the current call, and if said user is not available. For example, an RPC client (which calls a Qworum service directly and returns the result of that main call) may internally raise a user fault when it receives a 200 OK HTTP(S) response whose content is not a Qworum message. user is a subtype of user agent.

Services MAY use fault types that are not specified by the present specification. Such types MUST start with the * character and MUST NOT contain the comma (,) character. They are subtypes of the extension type, which is in turn a subtype of service. Example:

<fault type='* parameter is not a name' xmlns='http://qworum.net/' />

fault elements contain zero, one or more title elements which briefly describe the fault. An OPTIONAL lang attribute indicates the human language that is being used. Accepted values for this attribute are described in the section 3.10 of the HTTP/1.1 [HTTP/1.1] specification. title elements MUST NOT contain any elements. Example:

<fault xmlns='http://qworum.net/'>
  <title lang='de'>Unbekannte Aktie<title>
  <title lang='fr'>Code inconnu<title>
  <title>Unknown ticker symbol<title>
</fault>

The default fault type is service, so that the following statements are equivalent:

<fault type='service' xmlns='http://qworum.net/' />
<fault xmlns='http://qworum.net/' />

4.4. The `goto` statement

The goto statement initiates the next phase of a multi-phase service call.

goto elements MAY have an href attribute which indicates the URL of the next phase. The value of the href attribute MUST be an absolute HTTP or HTTPS URL [URL], or a relative URL [RelativeURL]. An absent href attribute is equivalent to an href attribute whose value is the URL of the message containing the goto statement, and a relative URL is resolved using the message URL. For example, a request to http://www.ahost.com/path might return any one of the following messages; they will all initiate the next phase of the current call by sending a GET request to http://www.ahost.com/path:

<goto xmlns='http://qworum.net/' />

<goto href='path' xmlns='http://qworum.net/' />

<goto href='http://www.ahost.com/path' xmlns='http://qworum.net/' />

goto elements contain zero or one statement (the parameter statement). If the parameter statement is present then the next phase is initiated with a POST request whose body (which has the content type application/xml) contains the evaluation result of the parameter statement.

goto elements contain zero, one or more title elements which briefly describe the next phase. An OPTIONAL lang attribute indicates the human language that is being used. Accepted values for this attribute are described in the section 3.10 of the HTTP/1.1 [HTTP/1.1] specification. title elements do not contain any elements.

For example, the following statement:

<qrm:goto href='http://www.anecommercesite.com/process_payment' xmlns:qrm='http://qworum.net/'>
  <qrm:title>Start processing the payment ..</qrm:title>
  <payment>
    <description>1 x 1-year subscription for "A Business Magazine"</description>
    <total>98.95</total>
    <currency>USD</currency>
    <merchant>payments@anecommercesite.com</merchant>
  </payment>
</qrm:goto>

sends a POST request to http://www.anecommercesite.com/process_payment, and the request body contains:

<payment>
  <description>1 x 1-year subscription for "A Business Magazine"</description>
  <total>98.95</total>
  <currency>USD</currency>
  <merchant>payments@anecommercesite.com</merchant>
</payment>

User agents take the following security measures when evaluating goto statements:

If a goto statement is redirecting the user agent from a private or local site to an internet site (a URL is considered to point to an internet site if its host part is a fully qualified domain name that ends with a top-level domain [TLD], or if it is an IP address [IPaddress] that is neither private nor local [Loopback]), then the user agent MAY choose not to send the actual referrer URL in the Referer HTTP header. Instead, this header MAY be absent or it MAY contain a URL that is derived from the Intranet Assigned Domain Name [DRM/1.0], such as http://mycompany.com/.
goto statements MUST NOT redirect user agents from an internet site to a private or local site. In this case, user agents MUST raise an authorization fault instead of evaluating the goto statement.

4.5. The `if` statement

if is a conditional statement. It MUST contain a condition statement, followed by a "then" statement, followed by an OPTIONAL "else" statement. The default value of the "else" statement is nil.

The condition statement is evaluated first. If it yields nil, then the "else" statement is evaluated, and the if statement yields that value. Otherwise, the "then" statement is evaluated, and the if statement yields that value.

For example, the following statement:

<qrm:if xmlns:qrm='http://qworum.net/'>
  <qrm:nil />
  <text>Positive</text>
  <text>Negative</text>
</qrm:if>

yields:

<text>Negative</text>

4.6. The `nil` statement

The nil statement represents data that does not carry any information. It remains unchanged after evaluation. Example:

<nil xmlns='http://qworum.net/' />

The nil element MUST NOT have any attributes, and it MUST NOT contain any elements.

4.7. The `return` statement

The return statement terminates the current call by returning a result. It MUST NOT contain more than one statement. For example, the statement:

<parent>
  <qrm:return xmlns:qrm='http://qworum.net/'>
    <email>john.smith@email.com</email>
  </qrm:return>
</parent>

returns the result:

<email>john.smith@email.com</email>

And the following statement returns nil:

<return xmlns='http://qworum.net/' />

The return element MUST NOT have any attributes.

4.8. The `select` statement

The select statement is used for selecting an element from the value yielded by the statement it MUST contain. The select element MUST have an xpath attribute whose value is an expression that conforms to the XPath 1.0 specification [XPath/1.0], and it has an OPTIONAL namespaces attribute which defines the namespace prefixes used in the XPath expression.

This statement MUST raise a message fault if the XPath expression is not valid. Otherwise, this statement MUST yield the element that is matched by the XPath expression. If several elements match the XPath expression, then this statement MUST yield the first matched element. It MUST yield nil if the XPath expression:

points to a node that is not an element (such as an attribute or a text node),
returns a character string, a number or a boolean value,
returns an empty node set.

For example, the following statement:

<qrm:select xpath='/bookshelf/book' xmlns:qrm='http://qworum.net/'>
  <bookshelf>
    <book>
      <title>The XPath Book</title>
    </book>
    <book>
      <title>The XML Book</title>
    </book>
  </bookshelf>
</qrm:select>

yields:

<book>
  <title>The XPath Book</title>
</book>

And the following statement:

<qrm:select xpath='book/d:title' 
  namespaces='d http://purl.org/dc/elements/1.1/ m http://mycompany.com/ns' 
  xmlns:qrm='http://qworum.net/'>
  <bookshelf xmlns:dc='http://purl.org/dc/elements/1.1/' xmlns:my='http://mycompany.com/ns'>
    <book>
      <dc:title>The XPath Book</dc:title>
      <my:inventory>22</my:inventory>
    </book>
    <book>
      <dc:title>The XML Book</dc:title>
      <my:inventory>44</my:inventory>
    </book>
  </bookshelf>
</qrm:select>

yields:

<dc:title xmlns:dc="http://purl.org/dc/elements/1.1/">The XPath Book</dc:title>

4.9. The `sequence` statement

The sequence statement contains zero, one or more statements, each of which is evaluated in turn. The evaluation of this statement yields the result that is yielded by the last statement it contains. For example, the statement:

<qrm:sequence xmlns:qrm='http://qworum.net/'>
  <qrm:call href='email_lookup'>
    <name>John Smith</name>
  </qrm:call>
  <email>jack.smith@email.com</email>
</qrm:sequence>

yields (if the service call did not terminate with a fault):

<email>jack.smith@email.com</email>

And the following empty statement returns nil:

<sequence xmlns='http://qworum.net/' />

The sequence element MUST NOT have any attributes.

4.10. The `transform` statement

The transform statement transforms the value yielded by a statement. It MUST contain an XSL stylesheet that conforms to the XSLT syntax [XSLT], followed by the statement whose value is to be transformed. User agents MUST ignore xsl:output elements in the XSL stylesheet.

If the transformation does not yield any value, then the transform statement MUST yield nil. If the transformation fails, then a message fault MUST be raised.

For example, the following statement:

<qrm:transform xmlns:qrm='http://qworum.net/'>
  <xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
    <xsl:template match="/">
      <books type='nearly out of stock'>
        <xsl:for-each select='*/book[inventory&lt;5]'>
          <book><xsl:value-of select='title' /></book>
        </xsl:for-each>
      </books>
    </xsl:template>
    <xsl:output method='text' /> <!-- ignored by the user agent -->
  </xsl:stylesheet>
  <bookstore>
    <book>
      <title>The XSLT Book</title>
      <inventory>1</inventory>
    </book>
    <book>
      <title>The XML Book</title>
      <inventory>44</inventory>
    </book>
  </bookstore>
</qrm:transform>

will yield:

<books type='nearly out of stock'>
  <book>
    <title>The XSLT Book</title>
    <inventory>1</inventory>
  </book>
</books>

4.11. The `transient` statement

The transient statement is used for handling message variables, which exist only during the evaluation of a given message. The transient element MUST have a name attribute which identifies the message variable being handled.

When setting the value of a message variable, the transient element contains one statement which yields the value. The transient statement in turn yields that same value. For example, the statement:

<qrm:transient name='John&apos;s e-mail' xmlns:qrm='http://qworum.net/'>
  <qrm:call href='email_lookup'>
    <name>John Smith</name>
  </qrm:call>
</qrm:transient>

might yield:

<email>john.smith@email.com</email>

When getting the value of a message variable, the transient element does not contain any element, and the statement yields the value of the message variable. For example, the statement:

<transient name='John&apos;s e-mail' xmlns='http://qworum.net/' />

might yield:

<email>john.smith@email.com</email>

The following statement uses transient in order to avoid code duplication:

<qrm:try xmlns:qrm='http://qworum.net/'>
  <!-- Look for user in first database -->
  <qrm:call href='http://first.user-database/email_lookup'>
    <qrm:transient name='User'>
      <name>John Smith</name>
    </qrm:transient>
  </qrm:call>
  <qrm:catch>
    <!-- User not found in first database -->
    <qrm:try>
      <!-- Look for user in second database -->
      <qrm:call href='http://second.user-database/email_lookup'>
        <qrm:transient name='User' />
      </qrm:call>
      <qrm:catch>
        <!-- User not found in second database -->
      </qrm:catch>
    </qrm:try>
  </qrm:catch>
</qrm:try>

The default value of a message variable is nil.

4.12. The `try` statement

The try statement allows user agents to handle a fault in order to prevent it from terminating the current call.

try statements MUST contain one statement (the tried statement) followed by one or more catch elements. Each catch element contains zero, one or more statements.

The evaluation of try starts with the evaluation of the tried statement. If the tried statement is successful, then try yields the result of that statement. For example:

<qrm:try xmlns:qrm='http://qworum.net/'>
  <text>succeeds</text>
  <qrm:catch>
    <text>will never be evaluated</text>
  </qrm:catch>
</qrm:try>

yields:

<text>succeeds</text>

If the tried statement fails because of a fault, then statements in the first catch that matches the fault type are evaluated, and try yields the result of the last statement. For example, the statement:

<qrm:try xmlns:qrm='http://qworum.net/'>
  <qrm:fault />
  <qrm:catch types='message, user agent'>
    <text>fault is of type message or user agent</text>
    <text>0</text>
  </qrm:catch>
  <qrm:catch types='service'>
    <text>fault is of type service</text>
    <text>1</text>
  </qrm:catch>
  <qrm:catch types='service'>
    <text>fault is of type service</text>
    <text>2</text>
  </qrm:catch>
  <qrm:catch>
    <text>fault is of an undetermined type</text>
    <text>3</text>
  </qrm:catch>
</qrm:try>

yields:

<text>1</text>

The following try is unable to handle a failed tried statement, and the current call will terminate unless an enclosing try statement in the same message handles the fault:

<try xmlns='http://qworum.net/'>
  <fault />
  <catch types='message, user agent' />
</try>

A catch element that does not contain any statement is equivalent to one that contains a nil statement.

4.13. The `variable` statement

An issue that quickly arises when developing Qworum services is that of representing call state. Conventional RPC services do not need a mechanism for storing call state, as calls to RPC services always consist of a single phase. In this regard Qworum services are similar to web applications (or websites) whose execution may span several phases, which creates a need for representing a state that is shared between phases.

Qworum addresses the call state representation issue through the concept of call variables. Call variables are stored on the user agent, and they exist throughout the duration of the service call in which they are defined. Call variables are manipulated through the variable statement which has an attribute named name that identifies the variable.

When setting the value of a call variable, the variable element contains one statement which yields the value. The variable statement in turn yields that same value. For example, the statement:

<qrm:variable name='John&apos;s e-mail' xmlns:qrm='http://qworum.net/'>
  <qrm:call href='email_lookup'>
    <name>John Smith</name>
  </qrm:call>
</qrm:variable>

might yield:

<email>john.smith@email.com</email>

When getting the value of a call variable, the variable element does not contain any element, and the statement yields the value of the call variable. For example, the statement:

<variable name='John&apos;s e-mail' xmlns='http://qworum.net/' />

might yield:

<email>john.smith@email.com</email>

The following statement sets the value of a call variable and initiates the next phase:

<qrm:sequence xmlns:qrm='http://qworum.net/'>
  <qrm:variable name='Username'>
    <username>john.smith</username>
  </qrm:variable>
  <qrm:goto href='call_variable_is_set' />
</qrm:sequence>

The default value of a call variable is nil.

5. Implementations

5.1. Additional specifications

User agents which implement the present version of the Qworum core specification MUST also implement the following specifications:

Version 1.0 of the Qworum Domain Rights Management specification [DRM/1.0],
Version 1.0 of the Qworum Enterprise specification [Enterprise/1.0].

5.2. The `configure` statement

The configure statement is used for configuring user agents in private networks. This statement allows IT administrators to avoid configuring each person's web browser manually. They only need to publish the configuration data in a Qworum message on an intranet website. Each person can then configure their browsers themselves by opening the message URL in their browsers.

Example:

<configure xmlns='http://qworum.net/'>
  <enterprise>
    <contract>14-c3b61-2627d-8b559-8095a-6dc6d-e6543</contract>
  </enterprise>
  <saas>
    <domain>mycompany.com</domain>
    <schemes>
      <scheme>https</scheme>
    </schemes>
  </saas>
</configure>

configure elements MUST contain an enterprise element if Qworum is to be used in private networks (see [Enterprise/1.0]). If present, this element MUST contain a contract element which specifies a Qworum Enterprise contract identifier. User agents do not need to verify contract validity during statement evaluation.

configure elements MUST contain a saas (Software-as-a-Service) element if calls and goto redirections to internet services are to be allowed from private networks (see [DRM/1.0]). If present, this element MUST contain a domain element which specifies the private network's Intranet Assigned Domain Name.

saas elements MAY contain a schemes element, which MUST in turn contain at least one scheme element. The schemes element is used for defining the set of allowed protocols when calling or redirecting to an internet service from a private network (a protocol that is not allowed would raise an authorization fault). If the saas element does not contain a schemes element, then all protocols are allowed.

If the Qworum message containing the configure statement is received from an internet website, or if the statement evaluation fails, then the user agent MUST ignore the configuration data and it MUST raise an authorization fault. Otherwise, the configuration data MUST be stored by the user agent and the evaluation MUST yield nil.

6. Appendices

6.1. References

[HTTP/1.1]	Berners-Lee, T., Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., and Leach, P., Hypertext Transfer Protocol -- HTTP/1.1, RFC 2616
[HTTP/1.0]	Berners-Lee, T., Fielding, R. and Frystyk, H., Hypertext Transfer Protocol -- HTTP/1.0, RFC 1945
[HTTPS]	Rescorla, E., HTTP Over TLS, RFC 2818
[URL]	Berners-Lee, T., Masinter, L., and McCahill, M., Uniform Resource Locators (URL), RFC 1738
[RelativeURL]	Fielding, R., Relative Uniform Resource Locators, RFC 1808
[XML]	Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, François Yergeau, Extensible Markup Language (XML), W3C Recommendation
[XMLnamespaces]	Tim Bray, Dave Hollander, Andrew Layman, Richard Tobin, Namespaces in XML 1.0, W3C Recommendation
[XPath/1.0]	James Clark, Steve DeRose, XML Path Language (XPath), Version 1.0, W3C Recommendation
[XSLT]	James Clark, XSL Transformations (XSLT), Version 1.0, W3C Recommendation
[TLD]	Top-level domain
[IPaddress]	IP address
[Loopback]	Loopback IP address
[Keywords]	Bradner, B., Key words for use in RFCs to Indicate Requirement Levels, RFC 2119
[DRM/1.0]	Doğa Armangil, Qworum Domain Rights Management (DRM) specification, version 1.0
[Enterpise/1.0]	Doğa Armangil, Qworum Enterprise specification, version 1.0

6.2. Revision history

2010.06.10: Added the transform statement.

2010.06.04: Added the if and select statements.

2010.05.13: Added the configure statement.

2010.04.05: Initial release of 1.0 draft.

2007.09.06: Release of first draft.

6.3. Copyright and disclaimer

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and these paragraphs are included on all such copies and derivative works. This document may not be modified in any way, such as by removing the copyright notice or references to Doğa Armangil or other organizations.

Any party may, for commercial or non-commercial purposes, send Qworum messages from web servers to user agents, without royalty or license fee to Doğa Armangil.

In addition, any party may, without royalty or license fee to Doğa Armangil, implement client-side software which conform to the present specification, allowing web browsers and other user agents to handle Qworum messages.

THIS DOCUMENT AND THE INFORMATION CONTAINED HEREIN IS PROVIDED "AS IS", AND DOĞA ARMANGIL DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. FURTHER, DOĞA ARMANGIL WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THIS DOCUMENT.

Qworum core specification, version 1.0 Draft

Abstract

1. Introduction

1.1. Purpose

1.2. Requirements

2. Service composition

2.1. Multi-phase service calls

2.2. Special case: the World Wide Web

2.3. Special case: RPC

2.4. The user agent as mediator for service calls

3. Messages

3.1. Message format

3.2. Message evaluation by the user agent

3.3. The http://qworum.net/ XML namespace

3.4. The application/x-qworum+xml media type

3.5. The .qrm file extension

4. Statements

4.1. The call statement

4.2. The data statement

4.3. The fault statement

4.4. The goto statement

4.5. The if statement

4.6. The nil statement

4.7. The return statement

4.8. The select statement

4.9. The sequence statement

4.10. The transform statement

4.11. The transient statement

4.12. The try statement

4.13. The variable statement

5. Implementations

5.1. Additional specifications

5.2. The configure statement

6. Appendices

6.1. References

6.2. Revision history

6.3. Copyright and disclaimer

3.3. The `http://qworum.net/` XML namespace

3.4. The `application/x-qworum+xml` media type

3.5. The `.qrm` file extension

4.1. The `call` statement

4.3. The `fault` statement

4.4. The `goto` statement

4.5. The `if` statement

4.6. The `nil` statement

4.7. The `return` statement

4.8. The `select` statement

4.9. The `sequence` statement

4.10. The `transform` statement

4.11. The `transient` statement

4.12. The `try` statement

4.13. The `variable` statement

5.2. The `configure` statement