Error Pipeline

1. Rationale

When PresentationServer encounters an error, it throws two kinds of exceptions: OXFException and its subclass, ValidationException. They both contain a nested root cause, and ValidationException contains document location information.

When an exception is thrown, PresentationServer displays a default error page containing the root cause and location information if available. However, the application developer can display a different page by specifying a processor to be executed upon error. This processor could be, for example, a pipeline logging the error and displaying a nice error page to the user.

2. Configuration

The error pipeline can be configured in web.xml or properties.xml. For more information, please refer to the Packaging and Deployment documentation.

3. Example

In most cases, the custom error pipeline logs or displays the exception that occurred. A simple error pipeline is shown below, using the Exception processor to display the root cause message, but not the exception stack trace.

3.1 Setup

  <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>

3.2 error.xpl

  <p:config xmlns:p="http://www.orbeon.com/oxf/pipeline">
  <p:processor name="oxf:exception">
  <p:output name="data" id="exception"/>
  </p:processor>
  <p:processor name="oxf:xslt">
  <p:input name="data" href="#exception"/>
  <p:input name="config">
  <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:template match="/">
  <html>
  <head>
  <title>PresentationServer - Custom Error Page</title>
  </head>
  <body>
  <h1>An error occured:</h1>
  <p>
The screen demonstrates a custom error pipeline. For this example, only the message of the first exception is displayed.
  </p>
  <p>
  <code>
  <xsl:value-of select="/exceptions/exception/message"/>
  </code>
  </p>
  </body>
  </html>
  </xsl:template>
  </xsl:stylesheet>
  </p:input>
  <p:output name="data" id="document"/>
  </p:processor>
  <p:processor name="oxf:xslt">
  <p:input name="data" href="#document"/>
  <p:input name="config" href="oxf:/oxf-theme/theme.xsl"/>
  <p:output name="data" id="themed"/>
  </p:processor>
  <p:processor name="oxf:xslt">
  <p:input name="data" href="#themed"/>
  <p:input name="config" href="oxf:/oxf/pfc/oxf-rewrite.xsl"/>
  <p:output name="data" id="html"/>
  </p:processor>
  <p:processor name="oxf:html-serializer">
  <p:input name="config">
  <config>
  <status-code>500</status-code>
  </config>
  </p:input>
  <p:input name="data" href="#html"/>
  </p:processor>
  </p:config>