XForms - Using the Orbeon Forms XForms Engine with Java Applications

New documentation

Legacy documentation

Deployment options

  Separate deployment
(recommended)
Integrated deployment
[DEPRECATED as of Orbeon Forms 4.5]
Benefits
  • Easier upgrades of both your application and Orbeon Forms.
  • Preventing situations where different versions of JAR files could conflict.
  • Cleaner application architecture.
  • Only one WAR file is needed (instead of 2, one for Orbeon Forms and one for your app).
We consider that beyond very simple cases (say, just adding JSP files that generate XHTML+XForms without any library), the drawbacks of this method heavily outweigh its benefits. (For more on this, see the benefits of separate deployment listed to the left.) Hence, using separate deployment has always been the recommended method, and since 4.5, integrated deployment is deprecated.
web.xml configuration

See below for the snippet you'll want to include in your web.xml.

The value of the oxf.xforms.renderer.context parameter specifies the context into which you have deployed Orbeon Forms. By default, Orbeon forms deploys to /orbeon so this value is usually safe. If you deploy Orbeon Forms to another context, you need to change this value accordingly.

The <url-pattern> defined under the first <filter-mapping> has the value /xforms-jsp/*. This means that all the data generated by URLs starting with /xforms-jsp/ is post-processed by Orbeon Forms. You can change this value as desired.

The <url-pattern> defined under the second <filter-mapping> has the value /orbeon/*. This is necessary to allow for all Orbeon Forms resources, such as JavaScript, CSS, and Ajax server, to be accessible. This /orbeon/* value is related to the default context into which you deploy Orbeon Forms: if you change you context, you change this value as well.

[SINCE Orbeon Forms 4.6.1]

The filter parameter oxf.xforms.renderer.default-encoding allows you to specify a default character encoding when the content provided by the servlet or JSP page doesn't specify one. Previously, the default character encoding was hardcoded to ISO-8859-1. Since 4.6.1 the hardcoded default remains this, but you can change it with oxf.xforms.renderer.default-encoding. The default Orbeon Forms web.xml overrides this default to UTF-8, which is what most modern HTML uses.

See below for the snippet you'll want to include in your web.xml.

The <url-pattern> defined under the <filter-mapping> has the value /xforms-jsp/*. This means that all the data generated by URLs starting with /xforms-jsp/ is post-processed by Orbeon Forms. You can change this value as desired.

Application server configuration

Your WAR must be deployed in such a way that it is allowed forwarding requests to other web applications.

  • With Tomcat, this is called a cross-context setup, and you enable it as follows with the crossContext attribute in server.xml:

    <Context path="/my-app"
        docBase="/path/to/my-app/war"
        crossContext="true"/>


  • With WebLogic, no special setup is required; WebLogic allows cross-context access by default.

None particular: just deploy Orbeon Forms as usual.

Location of JSPs

With the default configuration shown above, all JSPs located in the directory called xforms-jsp in your WAR are processed by the XForms engine. However, it is likely that you will prefer another location. In that case, you just change the url-mapping configuration.

You must not deploy resources under the /orbeon/ directory, as that directory is reserved for Orbeon Forms resources.

With the default configuration in the Orbeon Forms web.xml, all JSPs located in the directory called xforms-jsp in your WAR are processed by the XForms engine.

Under this directory, by default you find one directory per example, for instance xforms-jsp/guess-the-number or xforms-jsp/flickr-search. You can add your own directories and JSP files as desired.

Other Java resources

You don't have to produce XForms from JSP. You can do so directly from servlets, or other Java web application frameworks (usually based on servlets and template languages). What matters is that the filter defined in web.xml kicks in for those resources and that you produce well-formed XML as output. For this to happen, you modify the <filter-mapping> accordingly to enable the filter for the URLs handled by your framework.


Session handling

All URLs are designed go through your web application's context, so your application and the Orbeon Forms XForms engine automatically share the same session.

All URLs access the same web application context, so your application and Orbeon Forms automatically share the same session.

Access control

You control security for all of your application's pages, including XForms pages, in your own application's web.xml. It is not possible to access your application's XForms pages by accessing Orbeon Forms URLs directly: your application controls the generation of XForms content, not Orbeon Forms.

However by default you can still access Orbeon Forms applications through Orbeon Forms URLs. If you don't want to deploy any Orbeon Forms applications directly, you can block external accesses to the Orbeon Forms WAR by configuring the Orbeon Forms WAR's web.xml.

You control security for all pages in the single application's web.xml.

web.xml configuration for integrated deployment

[DEPRECATED as of Orbeon Forms 4.5]

<filter>
    <filter-name>orbeon-xforms-filter</filter-name>
    <filter-class>org.orbeon.oxf.servlet.OrbeonXFormsFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>orbeon-xforms-filter</filter-name>
    <url-pattern>/xforms-jsp/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
    <dispatcher>FORWARD</dispatcher>
</filter-mapping>
Comments