Orbeon Search

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

XForms - XPath Analysis

Contents

  1. 1 Availability
  2. 2 Rationale
  3. 3 Enabling XPath analysis
  4. 4 How XPath analysis works
  5. 5 XPath expressions supported

Availability

This is an Orbeon Forms PE feature.

Rationale

Whenever a user makes a change to a form, for example by entering a new value in a form field, the XForms engine must process that change, including:
  • storing the user data into an XML document (XForms instance)
  • re-evaluate validity constraints and other properties on the data
  • run recalculations
  • update the controls that bind to the data so that they reflect the latest data
Often, this results in a very large number of XPath evaluations, which can be costly.

The XPath analysis feature of Orbeon Forms PE allows the XForms engine, when loading a page, to go through XPath expressions to analyze them and understand dependencies between XML data, constraints, and controls.

This enables the XForms engine to process user interactions faster.

Enabling XPath analysis

NOTE: As of Orbeon Forms 3.0 PE, this feature is disabled by default, except for the demo forms and Form Builder where it is specifically enabled.

You enable XPath analysis with the following property:

<property as="xs:boolean" name="oxf.xforms.xpath-analysis" value="true"/>

You can also turn on this property specifically for a given form by adding xxforms:xpath-analysis="true", on the first model:

<xforms:model xxforms:xpath-analysis="true">
  ...

How XPath analysis works

Consider this instance in a people-model model:

<xf:instance id="people">
  <people>
    <person>
      <name>Mary</name>
      <age>20</age>
    </person
    <person>
      <name>Bob</name>
      <age>27</age>
    </person
  </people>
</xf:instance>

And consider a group at the top-level:

<xf:group id="my-group" ref="person[age ge 21]">

The binding with ref is relative to the root element of the instance('people') instance. The expression person[age ge 21] is relative to that root element. It is analyzed as if the form author had written directly:

instance('people')/person[age ge 21]

Now by analyzing this expression, the XForms engine can know that the expression:
  • depends on the value of an element called <age> child of an element <person> child of instance('people')
  • returns an element <person> child of instance('people')
  • only depends on the people instance in the people-model model
The XForms engine then uses this information to determine when the ref binding on the group needs to be re-evaluated.

So what can cause the binding for my-group to require an update?
  1. A structural change to the instance, such as a new <person> element replacing the current <person> element.

    As of Orbeon Forms 3.9, any structural change in a model invalidates all bindings and values touching that model, and it is as if XPath analysis had been turned off. (This can be improved in the future.)

  2. A change to the value of any element matching instance('people')/person/age.

    If the value of such an <age> element changes between two refreshes, then the binding needs to be reevaluated.

  3. Otherwise, no evaluation is needed!

    For example, if the value of instance('people')/person/name changes, the binding need not change.

So the XForms engine can simply follow this algorithm:
  • Was there a structural change since the last refresh? If so, re-evaluate the binding.
  • Was there a change to the value of any <age> element matching instance('people')/person/age? If so, re-evaluate the binding.
  • Otherwise, don't re-evaluate the binding.
The same idea applies to:
  • control bindings
  • control values
  • itemsets
  • values of label, help, hint, and help elements
  • <xforms:bind> bindings
  • values of model item properties

XPath expressions supported

Not all XPath expressions are currently analyzed fully. If an XPath expression is not analyzable, it will simply be re-evaluated whenever needed.

As of Orbeon Forms 3.9, these expression are not analyzed:

Expression containing the following functions:
  • context()
  • index() / xxf:index() 
  • xxf:case()
  • all functions depending on external data, like the request, session, or xxf:call-xpl()
  • Java functions
Expressions containing:
  • "*", for example instance('people')/person/*
  • "//", for example instance('people')//age
For debugging purposes, you can log the result of the XPath analysis to the servlet container's standard output by enabling this property:

<property as="xs:boolean" name="oxf.xforms.debug.log-xpath-analysis" value="true"/>

This lists all the expressions considered, mark whether they were analyzed or not, and list all aspects of the analysis.