Packaging and Deployment

1. Scope

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

2. WAR Structure

Files Description
WEB-INF/lib/orbeon.jar JAR file with all the PresentationServer classes.
WEB-INF/lib/*.jar All the other JAR files in the WEB-INF/lib directory are used either by the PresentationServer core engine, or one of the Presentation Server processors.
WEB-INF/web.xml The standard descriptor for this WAR file. It declares OXFServlet as the default Servlet and passes some basic configuration parameters to this Servlet.
WEB-INF/portlet.xml The standard portlet descriptor for this WAR file is required if you use portlets. It typically declares instances of OXFPortlet. For more information, see Writing Portlets With PresentationServer.
WEB-INF/weblogic.xml An additional descriptor for WebLogic. This descriptor typically maps resource names to actual resources configured in the application server (e.g. for EJBs, users, JDBC data sources, etc).
WEB-INF/sun-web.xml An additional descriptor for SunOne. This descriptor typically maps resource names to actual resources configured in the application server (e.g. for EJBs, users, JDBC data sources, etc).
WEB-INF/resources/* Contains the resources for the PresentationServer example application. Most of the files in this directory will be replaced when you build your own PresentationServer web applications. In particular, this directory contains properties.xml, the main PresentationServer configuration file.

3. PresentationServer Initialization

The following figure illustrates the initialization of a simple PresentationServer 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 oxf implemented by the class org.orbeon.oxf.servlet.OXFServlet (loaded from lib/orbeon.jar)
    • Defines oxf as the default Servlet (i.e. the Servlet handling all the requests).

      <web-app>
      <servlet>
      <servlet-name>oxf</servlet-name>
      <servlet-class>org.orbeon.oxf.servlet.OXFServlet</servlet-class>
      <!-- Initialization parameters here (see below) -->
      </servlet>
      <servlet-mapping>
      <servlet-name>oxf</servlet-name>
      <url-pattern>/*</url-pattern>
      </servlet-mapping>
      </web-app>

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

    • What resource manager has to be used, and how this resource manager is configured. In the default WAR bundled in the PresentationServer distribution, PresentationServer 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. Only static resources that are part of PresentationServer are stored in orbeon.jar (as opposed to PresentationServer applications). The Resource Managers section explains in detail how resource managers work.
    • The location of properties.xml.
    • Optionally, what main processor or context listener processors must be used.
  3. PresentationServer is configured through an XML file, properties.xml, stored with the resources. The exact name and path of this file is specified within web.xml. properties.xml may declare the main processor to be executed by OXFServlet, as well as optional inputs of this processor. Alternatively, the main processor can be declared directly within web.xml, which is the recommended approach. By default, the Page Flow Controller is used as the main processor. If the configuration is done in web.xml:

      <!-- The main processor that OXFServlet must execute -->
      <context-param>
      <param-name>oxf.main-processor.name</param-name>
      <param-value>{http://www.orbeon.com/oxf/processors}page-flow</param-value>
      </context-param>
      <!-- The Page Flow Controller configuration file -->
      <context-param>
      <param-name>oxf.main-processor.input.controller</param-name>
      <param-value>oxf:/page-flow.xml</param-value>
      </context-param>

    If the configuration is done in properties.xml:

      <properties>
      <!-- The main processor that OXFServlet must execute -->
      <property as="xs:QName" name="oxf.main-processor.main" value="oxf:page-flow"/>
      <!-- The Page Flow Controller configuration file -->
      <property as="xs:anyURI" name="oxf.main-processor.input.controller" value="oxf:/page-flow.xml"/>
      </properties>

    For more information about the properties file, see PresentationServer 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.

4. Main Processor

4.1 Definition

In the same way that an old-fashioned program has a main function, Presentation Server 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 PresentationServer Servlet needs to be configured. In more complex scenarios, it is possible to deploy multiple PresentationServer Servlets, Servlet filters, and Portlets, as well as one PresentationServer Servlet context listener, within the same Web or Portlet Application. The following figure illustrates this:

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

4.2 PresentationServer Servlet, PresentationServer Servlet Filter, and PresentationServer Portlet

These components can each have their own main processor. The main processor for such components is looked up in the following locations, in this order:

  1. The component's initialization parameters in web.xml. For example, in the case of a Servlet:

      <servlet>
      <servlet-name>oxf</servlet-name>
      <servlet-class>org.orbeon.oxf.servlet.OXFServlet</servlet-class>
      <!-- The main processor that OXFServlet must execute -->
      <init-param>
      <param-name>oxf.main-processor.name</param-name>
      <param-value>{http://www.orbeon.com/oxf/processors}page-flow</param-value>
      </init-param>
      <!-- The Page Flow Controller configuration file -->
      <init-param>
      <param-name>oxf.main-processor.input.controller</param-name>
      <param-value>oxf:/page-flow.xml</param-value>
      </init-param>
      </servlet>

  2. properties.xml, for example:

      <properties>
      <!-- The main processor that OXFServlet must execute -->
      <property as="xs:QName" name="oxf.main-processor.name" value="oxf:page-flow"/>
      <!-- The Page Flow Controller configuration file -->
      <property as="xs:anyURI" name="oxf.main-processor.input.controller" value="oxf:/page-flow.xml"/>
      </properties>

  3. The context parameters in web.xml

      <!-- The main processor that OXFServlet must execute -->
      <context-param>
      <param-name>oxf.main-processor.name</param-name>
      <param-value>{http://www.orbeon.com/oxf/processors}page-flow</param-value>
      </context-param>
      <!-- The Page Flow Controller configuration file -->
      <context-param>
      <param-name>oxf.main-processor.input.controller</param-name>
      <param-value>oxf:/page-flow.xml</param-value>
      </context-param>

It is recommended to configure each Web component individually in the component's initialization properties in web.xml, so that adding components with different configurations is facilitated. There are situations where several components need to share a configuration, but it is expected that such situations will be rare.

5. Error Processor

5.1 Definition

In case an error is encoutered during the execution or the main processor, PresentationServer 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 Pipeline documentation.

5.2 Configuring the Error Processor

You can configure an error processor in the same way the main processor is configured. The error processor is looked up in the following locations, in this order:

  1. The component's initialization parameters in web.xml. For example, in the case of a Servlet:

      <servlet>
      <servlet-name>oxf</servlet-name>
      <servlet-class>org.orbeon.oxf.servlet.OXFServlet</servlet-class>
      <!-- The error processor that OXFServlet must execute -->
      <init-param>
      <param-name>oxf.error-processor.name</param-name>
      <param-value>{http://www.orbeon.com/oxf/processors}pipeline</param-value>
      </init-param>
      <!-- The pipeline to execute -->
      <init-param>
      <param-name>oxf.error-processor.input.config</param-name>
      <param-value>oxf:/config/error.xpl</param-value>
      </init-param>
      </servlet>

  2. properties.xml, for example:

      <properties>
      <!-- The error processor that OXFServlet must execute -->
      <property as="xs:QName" name="oxf.error-processor.name" value="oxf:pipeline"/>
      <!-- The Page Flow Controller configuration file -->
      <property as="xs:anyURI" name="oxf.error-processor.input.config" value="oxf:/config/error.xpl"/>
      </properties>

  3. The context parameters in web.xml

      <!-- The error processor that OXFServlet must execute -->
      <context-param>
      <param-name>oxf.error-processor.name</param-name>
      <param-value>{http://www.orbeon.com/oxf/processors}pipeline</param-value>
      </context-param>
      <!-- The pipeline to execute -->
      <context-param>
      <param-name>oxf.error-processor.input.config</param-name>
      <param-value>oxf:/config/error.xpl</param-value>
      </context-param>

It is recommended to configure each Web or Portlet Application component individually in the component's initialization properties in web.xml, so that adding components with different configurations is facilitated. There are situations where several components need to share a configuration, but it is expected that such situations will be rare.