Scope

This section explains the structure of the standard WAR distributed with Orbeon Forms and how this WAR integrates with the application server (or Servlet container). This information is useful if you need to repackage Orbeon Forms. For instance, if you want to build an EAR file, or if you need to deploy more complex Orbeon Forms applications containing Servlets, Servlet Filters, Portlets, and Servlet context listeners.

War structure

The following table lists the most important files contained in orbeon.war:

Files	Description
WEB-INF/lib/orbeon.jar	JAR file with all the Orbeon Forms classes.
WEB-INF/lib/orbeon-resources-public.jar	JAR file with all the Orbeon Forms files that can be served to a web client, such as CSS and JavaScript files.
WEB-INF/lib/orbeon-resources-private.jar	JAR file with all the Orbeon Forms files that can not be served to a web client.
WEB-INF/lib/*.jar	All the other JAR files in the WEB-INF/lib directory are used either by the Orbeon Forms core engine, or one of the Orbeon Forms processors.
WEB-INF/web.xml	The standard descriptor for this WAR file. It configures the Orbeon Forms properties and resource manager, the Orbeon Forms main servlet and Ajax servlet, as well as other resources such as the embedded eXist XML database.
WEB-INF/portlet.xml	The standard portlet descriptor for this WAR file is required if you use portlets. It typically declares instances of OrbeonPortlet2Delegate. For more information, see Deployment as a Portlet (JSR-168/JSR-286).
WEB-INF/resources/*	Contains Orbeon Forms resources.
WEB-INF/resources/config/*	Contains Orbeon Forms resources which you can configure. In particular, this directory contains properties.xml, the main Orbeon Forms configuration file.
WEB-INF/resources/apps/*	Contains Orbeon Forms example applications resources. Each sub-directory contains a separate Orbeon Forms example application. When building your own application xxx
xforms-jsp/*	Contains examples using JavaServer Pages (JSP) to produce XForms. This directory can be removed if you do not want to run these examples.

Orbeon forms initialization

The following figure illustrates the initialization of a simple Orbeon Forms deployment in a J2EE application server:

The initialization follows this lifecycle:

1. The application server reads the WEB-INF/web.xml file, which:

   • Declares a Servlet named orbeon-main-servlet implemented by the class org.orbeon.oxf.servlet.OrbeonServletDelegate (loaded from lib/orbeon.jar)
   • Defines orbeon-main-servlet as the default Servlet (i.e. the Servlet handling all the requests).

   <web-app xmlns:p="http://www.orbeon.com/oxf/pipeline" xmlns:xforms="http://www.w3.org/2002/xforms">
       <servlet>
           <servlet-name>orbeon-main-servlet</servlet-name>
           <servlet-class>org.orbeon.oxf.servlet.OrbeonServletDelegate</servlet-class>
           <!-- Initialization parameters here (see below) -->
       </servlet>
       <servlet-mapping>
           <servlet-name>orbeon-main-servlet</servlet-name>
           <url-pattern>/</url-pattern>
       </servlet-mapping>
   </web-app>
   

2. The web.xml file configures the OrbeonServletDelegate with a minimal set of parameters. Those parameters tell OrbeonServletDelegate:

   • What resource manager has to be used, and how this resource manager is configured. In the default WAR bundled in the Orbeon Forms distribution, Orbeon Forms loads resources from the WEB-INF/resources directory inside the WAR. If it can't find a resource in this directory, it will try to look for it inside orbeon.jar or orbeon-resources-private.jar. Only static resources that are part of Orbeon Forms are stored in orbeon.jar and orbeon-resources-private.jar (as opposed to Orbeon Forms applications). The Resource Managers section explains in detail how resource managers work.
   • The location of properties.xml, by default oxf:/config/properties.xml. See Configuration Properties for more details.
   • What main processor or context listener processors must be used. By default, the Page Flow Controller is used as the main processor.:

3. More Orbeon Forms configuration is available in an XML file, properties.xml, stored with the resources. The exact name and path of this file is specified within web.xml. For more information about the properties file, see Configuration Properties.

4. The oxf.main-processor.input.controller property connects the controller input of the Page Flow Controller to the configuration file oxf:/page-flow.xml. The Page Flow Controller reads this input before it starts to operate.
5. The Page Flow Controller now handles client requests and dispatches them to other pipelines. For more information about the role of the controller, see the Page Flow Controller reference.

Main processor

Definition

In the same way that an old-fashioned program has a main function, Orbeon Forms has the concept of main processor. Within a web application, the main processor is the processor that is run each time a Servlet, Servlet filter or Portlet receives a client request. Within a command-line application, the main processor is simply the processor that runs when the application is run.

In the simplest web application deployment scenario, as shown in the example above, only one Orbeon Forms Servlet needs to be configured. In more complex scenarios, it is possible to deploy multiple Orbeon Forms Servlets, Servlet filters, and Portlets, as well as one Orbeon Forms Servlet context listener, within the same Web or Portlet Application. The following figure illustrates this:

Additional non-Orbeon Forms components can obviously be deployed within the same Web or Portlet Application.

Orbeon forms servlet, orbeon forms servlet filter, and orbeon forms portlet

These components can each have their own main processor. The main processor for such components is looked up in in the initialization parameters of the component. For example, in the case of a Servlet:

<servlet xmlns:p="http://www.orbeon.com/oxf/pipeline" xmlns:xforms="http://www.w3.org/2002/xforms">
    <servlet-name>orbeon-main-servlet</servlet-name>
    <servlet-class>org.orbeon.oxf.servlet.OrbeonServletDelegate</servlet-class>
    <!-- Set main processor -->
    <init-param>
        <param-name>oxf.main-processor.name</param-name>
        <param-value>{http://www.orbeon.com/oxf/processors}page-flow</param-value>
    </init-param>
    <init-param>
        <param-name>oxf.main-processor.input.controller</param-name>
        <param-value>oxf:/page-flow.xml</param-value>
    </init-param>
    <!-- ... -->
</servlet>

Error processor

Definition

In case an error is encountered during the execution or the main processor associated with a servlet, Orbeon Forms tries to execute an error processor. The error processor is typically a pipeline that produces a page showing the exception that was encountered. For more information, please refer to the Error Page documentation.

Configuring the error processor

You can configure an error processor in the same way the main processor is configured. The preferred way of configuring the error processor is using the component's initialization parameters in web.xml. For example, in the case of a Servlet:

<servlet xmlns:p="http://www.orbeon.com/oxf/pipeline" xmlns:xforms="http://www.w3.org/2002/xforms">
    <servlet-name>orbeon-main-servlet</servlet-name>
    <servlet-class>org.orbeon.oxf.servlet.OrbeonServletDelegate</servlet-class>
    <!-- ... -->
    <!-- Set error processor -->
    <init-param>
        <param-name>oxf.error-processor.name</param-name>
        <param-value>{http://www.orbeon.com/oxf/processors}pipeline</param-value>
    </init-param>
    <init-param>
        <param-name>oxf.error-processor.input.config</param-name>
        <param-value>oxf:/config/error.xpl</param-value>
    </init-param>
    <!-- Set supported methods -->
    <!-- ... -->
</servlet>