XForms - Asynchronous Submissions

Site map

Comments? Feedback?

This wiki does not yet support public comments (a limitation of Google Sites), so we encourage you to post your comments either:

On Twitter by responding to @orbeon.

On our community mailing list: subscribe sending an email to ops-users-subscribe@ow2.org (content of subject/body doesn't matter), you'll get a response with the email to use to send your message to the community mailing list.

Recent site activity

Improved retry mechanism
edited by Erik Bruchez
Configuration Properties - Form Runner
edited by Erik Bruchez
Form Runner - Data Envelope
edited by Erik Bruchez
Form Builder - Data Models
edited by Erik Bruchez
Project - XForms UI Dependencies
edited by Erik Bruchez
View All

Documentation‎ > ‎II. Developer and Administrator Guide‎ > ‎

XForms - Asynchronous Submissions

Contents

1 Rationale
2 Declaring an asynchronous submission
3 The xxforms:join-submission action
1. 3.1 Availability
2. 3.2 Configuration
4 How things work
5 Historical documentation
1. 5.1 Earlier implementation
2. 5.2 Fire-and-forget submission
  1. 5.2.1 Processing
  2. 5.2.2 Limitations

Rationale

Asynchronous submissions are specified in XForms 1.1.
There are interesting use cases for them, including:

Background autosave
Background loading of initial data from multiple services in parallel

Starting February 2010 builds, Orbeon Forms supports true asynchronous submissions (with some limitations due to the client-server architecture of Orbeon Forms).

Declaring an asynchronous submission

You enable an asynchronous submission with mode="asynchronous":

<xforms:submission id="call-service" mode="asynchronous"
    method="get" resource="http://www.orbeon.com/ops/xforms-sandbox/service/zip-states"
    serialization="none" xxforms:cache="true"
    replace="instance" targetref="instance('zip-states')"/>

This is useful for example to speed up the initial load of data from slow services when the page initializes because the background submissions can run in parallel, and at the same time the page can pursue its own initialization.

NOTE: While XForms 1.1 specifies that mode="asynchronous" should be the default, in Orbeon Forms mode="synchronous"is the default.

The xxforms:join-submission action

Availability

This is an Orbeon Forms PE feature.

Configuration

This extension action allows waiting until all pending background submissions have completed:

<xforms:action ev:event="xforms-model-construct-done">
   <xforms:send submission="query-people"/>
   <xforms:send submission="query-places"/>
   <xxforms:join-submissions/>
</xforms:action>

In this example, upon xforms-model-construct-done, two background submissions are started. The <xxforms:join-submissions> action waits until they both have completed.

This has two benefits:

For performance reasons, it might be a good idea to wait until they terminate before allowing the controls to initialize.
It might not make sense to show the initial page to the user if data for "people" and "places" is not available.

NOTE: If processing background submissions causes new background submissions to run, their results are processed as well.

NOTE: If the resulting instance is cacheable with xxforms:cache="true" and already in cache, it is immediately retrieved and no background submission takes place.

NOTE: Optimized submissions and submissions with replace="all" are not supported in asynchronous mode.

How things work

The submissions are asynchronous in the following way:

The request itself (http:, https, oxf: and file: are supported) runs in a separate execution thread
Deserialization of the response is also performed in that separate thread if needed:

for instance replacement, it creates an XML document (read-only or read-write)
for text replacement, it reads the text content as a String

The completion of asynchronous submission is checked at these time:

Just before sending the initial HTML page to the client
Upon receiving an Ajax request
Just before completing an Ajax request

When completed submissions are found, the result of each submission is processed:

Instance replacement or text replacement is done.
xforms-submit-done / xforms-submit-error are dispatched.

If an asynchronous submission is still running (pending) at the time an client HTTP connexion returns (whether an initial page load or an Ajax request):

The client is instructed to poll the server at regular intervals, or when an Ajax request is sent for other reasons.
Only once a client request reaches the server are pending asynchronous submission results processed.

The polling delay in milliseconds can be configured with the following property:

<property as="xs:integer" name="oxf.xforms.submission-poll-delay" value="10000"/>

Historical documentation

Earlier implementation

As of July 2009, Orbeon Forms implements a subset of XForms 1.1 asynchronous submissions.

More precisely, Orbeon Forms currently does not allow an asynchronous submission with side-effects (such as replacing an instance, or dispatching events after a response is received) to run after an HTTP response has been sent to the client. This means that either:

The submission must have no side-effect ("fire-and-forget" submission):

It must have replace="none"
It doesn't fire xforms-submit-done or xforms-submit-error

The submission must terminate in the scope of the current HTTP request, that is before the request returns to the browser

In this case it can have replace="instance" or replace="text"
In this case it fires xforms-submit-done or xforms-submit-error

Fire-and-forget submission

This is enabled for a submission with mode="asynchronous" and replace="none", e.g.:

<xforms:submission id="autosave" mode="asynchronous" ref="instance('document')" method="post"
resource="http://my.server.com/autosave" replace="none"/>

Processing

The submission runs after the client HTTP request that triggered the submission has returned a response to the client.
If there are multiple such fire-and-forget submissions, they run sequentially.

Limitations

Fire-and-forget submissions do not truly run in the background. Instead they run sequentially at the end of processing.
Optimized submissions do not yet support the asynchronous mode.

	Orbeon Search