XForms Reference: XForms Engine Configuration
- 1. Introduction
- 2. State Handling
- 2.1. Rationale
- 2.2. Configuring State Handling
- 2.3. Session Heartbeat
- 3. Local Submissions
- 3.1. Rationale
- 3.2. Enabling Local Submissions
- 3.3. Context Resolution
- 3.4. Limitations of Includes
- 4. JavaScript and CSS Resources
- 5. Browser Navigation (Back and Forward) Handling
- 6. Encryption
- 7. Debugging XForms Pages
1. Introduction
This part of the XForms reference documentation focuses on XForms engine configuration.
2. State Handling
2.1. Rationale
The Orbeon Forms XForms engine requires keeping processing state while operating on an XForms page. Such state includes the current values of XForms instances, selected repeated elements, and more. With Orbeon Forms, XForms state information can be handled in one of two ways:
-
Server-side: in this case, state information is stored on the server. Only very little state information circulates between client and server. The most frequently used state information is stored in memory. Less frequently used state information is stored on disk in a local database.
Benefits of the approach:
-
Resulting HTML page are smaller. HTML pages increase in size as more XForms controls are used, but they don't increase in size proportionally to the size of XForms instances.
-
Small amounts of data circulate between the client browser and the Orbeon Forms XForms server.
-
This means that very large XForms instances can be processed without any impact on the amount of data that is transmitted between the client and the server.
Drawbacks of the approach:
-
The Orbeon Forms XForms server needs to be stateful. It uses server memory to store state information even when no request is being processed. This creates additional demand for resources on the server and slightly complicates the task of tuning the server.
-
State information can become unavailable when sessions expire or when the server is restarted. When state information becomes unavailable for a page, that page will no longer function unless it is reloaded.
NoteOrbeon Forms ensures that it is possible to open multiple client browser windows showing the same page within the same session. -
-
Client-side: in this case, static initial state information is sent along with the initial HTML page, and dynamic state is exchanged over the wire between the client browser and the Orbeon Forms XForms server when necessary.
Benefits of the approach:
-
The Orbeon Forms server is entirely stateless. It only requires memory while processing a client request. It can be restarted without consequence for the XForms engine.
-
State information does not expire as long as the user keeps the application page open in the web browser.
Drawbacks of the approach:
-
Resulting HTML pages are larger. In particular, the size of state data grows when XForms instances grow, regardless of whether many XForms controls are bound to instance data.
-
More data circulates between the client browser and the Orbeon Forms XForms server.
NoteOrbeon Forms compresses and encrypts XForms state information sent to the client. -
By default, Orbeon forms store XForms state information on the server. Please change this default to client-side only if you have well understood the tradeoffs explained above.
2.2. Configuring State Handling
State handling can be configured globally for all pages, or locally for each individual page
served. Global configuration is performed in properties.xml
with the
oxf.xforms.state-handling
property. When missing or set to client
,
state is stored client-side. When set to server
, state is stored server-side. For
example:
The global configuration can be overridden for each page by setting the
xxforms:state-handling
attribute in the page. This attribute can be set on the
root element of the XHTML page, or on the first xforms:model
element. Only the
first such attribute encountered by the XForms engine is used:
When storing state on the server, the maximum size of the data to be stored globally in memory
can be selected using the oxf.xforms.store.application.size
property. The size is
specified in bytes:
When the allowed memory space for state information is full, Orbeon passivates state information to a local eXist database. Configuration parameters for the connection to the eXist database can be changed. The defaults are as follows:
Whether state information is kept client-side or server-side, a property controls whether the XForms
engine should try to optimize state reconstruction by using a cache. This property should usually
be set to true
:
If the above property is set to true
, the number of XForms documents that can be
held in that document cache at a given time is configured with the following property:
Note that this represents XForms documents in a particular state of interaction with a user, which means that if to users load the same XForms page two entries will be needed in the cache.
2.3. Session Heartbeat
If you happen to leave a browser window open on your computer, chances are that you will get back to that window and keep using the application. The last thing you want to happen when you come back is lose your session and therefore your data.
This is not always a correct guess of course: you may just happen to leave a window or tab open without planning to use it again. Conversely you may have a page which is not actually visible, for example in your browser history, yet you will come back to it. This approach wouldn???t be good for banking applications either. Still, in many situations, such as filling-out large forms, it sounds like a good idea to keep your session alive for open pages.
To achieve this goal you could make all server sessions longer. However this is harder to configure for the application developer, and this won???t discriminate between pages that are actually open on a client and the ones that are not. And while it may be ideal to have infinitely long sessions, unfortunately many applications are not ready for this kind of approach.
So Orbeon Forms supports a "session heartbeat" feature. Here is how this works:
-
When this feature is enabled (the default), an open XForms page in a client browser regularly pings the server through Ajax to keep the current server session alive.
-
The ping delay is automatically computed based on the server???s session timeout. The client pings the server at 80% of the session expiration time after the last interaction with the server.
-
We are careful not to hit the XForms engine too much, in fact we do a very limited amount of work on the server for each ping, so they should run fast.
-
XForms state information for pages hit with the heartbeat just migrates to the disk store over time if RAM is used by other pages, so keeping even large numbers of pages open should not have any negative impact on server RAM.
-
When a user gets back to using the page, state information migrates back from disk to RAM, and the page will be live again.
-
Sessions do eventually expire as nobody keeps a browser open forever.
Note that whenever an application keeps sessions alive for a long time, it is a good idea to keep as little data as possible in the session. The Orbeon Forms XForms engine itself uses a global state store and does not use session objects for storage, but do remember to keep your sessions small!
The session heartbeat should help prevent many occurrences of "session expired" error messages.
As an Orbeon Forms application developer you don???t have to worry about anything: the session
heartbeat is enabled by default. You can configure it globally in properties.xml
:
You can also override the global default by specifying a property on the first XForms model of a page:
3. Local Submissions
3.1. Rationale
XForms pages can make heavy use of services through the use of <xforms:submission>
.
A service is primarily identified by a URL.
-
Sometimes a service is remote (on a machine other than the machine on which Orbeon Forms is installed), in which case the URL is necessarily an absolute URL starting with
http://
orhttps://
. -
But often services are implemented within Orbeon Forms itself, not only on the same server but within the same web application. In the case of such local submission, Orbeon Forms provides a special optimized mode which has the following benefits:
-
No actual HTTP connection is initiated, so performance is likely to be better.
-
There is no need to deal with absolute URLs such as
http://localhost:8080
, especially when proxies or firewalls are in place.
-
For more information, see also the Configuration Properties related to submissions.
3.2. Enabling Local Submissions
Orbeon Forms performs a local submission if:
-
The URL specified is not a absolute, i.e. does not start with
http://
orhttps://
. -
The submission is not asynchronous. (This restriction may be lifted in the future.)
-
In a servlet environment:
-
The submission has
replace="all"
(which is the default if noreplace
attribute is specified) and theoxf.xforms.local-submission-forward
property is set totrue
(which is the default). -
The submission has
replace="instance"
,replace="text"
orreplace="none"
and theoxf.xforms.local-submission-include
property is set totrue
(the default isfalse
).
-
-
In a portlet environment:
-
The
f:url-norewrite
attribute is not set totrue
. -
The
f:url-type
attribute is not set toresource
.
NoteThe portlet logic above is likely to be revised in the future. Also note that in the case of optimized submissions within portlets, requests are made directly to the Orbeon Forms portlet and do not use servlet forward/include. -
3.3. Context Resolution
In a servlet environment, paths are resolved as follows:
-
If
f:url-norewrite
is not set totrue
, the resource is resolved against the current servlet context. -
If
f:url-norewrite
is set totrue
, the resource is resolved against the servlet container root. This allows accessing other web applications within the same servlet container.
Say your application is under context /orbeon
, and you have a second web application
under context /foo
:
3.4. Limitations of Includes
With replace="instance"
, replace="text"
or replace="none"
,
optimized submission are implemented using the servlet container's include mechanism, which does not
automatically build path information for the included resource.
In this case, Orbeon Forms is therefore unable to provide proper "servlet path" and "path info" information. Orbeon Forms handles this situation in the following way:
-
A blank (
""
) "servlet path" is provided. -
The "path info" contains the entire path provided, instead of the path following the servlet path.
This may cause some application which rely on the "servlet path" information to behave incorrectly. For example, consider the eXist REST servlet:
-
It is mounted as
/exist/rest
within Orbeon Forms. -
eXist (quite properly) expects any path following
/exist/rest
to be a path into the database, e.g./exist/rest/db/orbeon
produces a path called/db/orbeon
. -
If Orbeon Forms calls the eXist REST servlet with a blank servlet path and a path info containing
/exist/rest/db/orbeon
, eXist obviously obtains an incorrect database path.
Local forwards are not subject to that limitation.
4. JavaScript and CSS Resources
This section has moved to the Orbeon Forms wiki.
5. Browser Navigation (Back and Forward) Handling
When visiting an XForms page by using your browser's Back and Forward buttons, or other browser-history mechanisms, Orbeon Forms by default restores the appearance of that page as it was when you left it. (Browsers don't automatically handle this behavior with Ajax applications!) This behavior best matches the usual user experience obtained when navigating regular web pages.
In certain situations, it can be useful instead to ask the XForms page to reload entirely. You
control this by using the xxforms:revisit-handling
attribute on the first XForms model
of the page you want to reload. This attribute supports two values: restore
(the
default) and reload
. Example:
reload
value carefully, as reloading pages upon browser
navigation often does not match the expectation of the user.
6. Encryption
Orbeon Forms encrypt some information sent to the client (for example when using client-side state
state handling). This is done through the following property in properties.xml
:
It is strongly advised to change the default password in the property above.
In addition, Orbeon Forms by default encrypts the value of selection controls before sending them to the client. This can be controlled with this property:
In general, this should be set to true
, but you can set it to false
if you
need to access the value of selection controls through JavaScript on the client, or through offline
binds.