XPath expression analysis
This is an Orbeon Forms PE feature.
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: At the XForms level, this feature is disabled by default, but it is enabled for forms created by Form Builder by default.
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
xxf:xpath-analysis="true", on the first model:
How XPath analysis works
Consider this instance in a
<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
- returns an element
- only depends on the people instance in the
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?
A structural change to the instance, such as a new
<person>element replacing the current
Currently, 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.)
A change to the value of any element matching
If the value of such an
element changes between two refreshes, then the binding needs to be reevaluated.
Otherwise, no evaluation is needed!
For example, if the value of
instance('people')/person/namechanges, 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
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
- values of label, help, hint, and help elements
- 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.
These expression are not analyzed:
Expression containing the following functions:
- all functions depending on external data, like the request, session,
- Java functions
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.