OPS User Guide

Error Processor

1. Rationale

When OPS 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, OPS displays a default error page containing the root cause and location information if available, as well as a detailed OPS stack trace. 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 processor is configured in web.xml. For more information, please refer to the Packaging and Deployment documentation.

3. Example

3.1. Setup

The following code in web.xml specifies that upon error, the Pipeline processor must run using the oxf:/config/error.xpl pipeline:

  <servlet>  <servlet-name>oxf</servlet-name>  <servlet-class>org.orbeon.oxf.servlet.OPSServlet</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

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

  <p:config xmlns:p="http://www.orbeon.com/oxf/pipeline">  <!-- Generate exception document -->  <p:processor name="oxf:exception">  <p:output name="data" id="exception"/>  </p:processor>  <!-- Apply stylesheet -->  <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>OPS - 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[1]/message"/>  </code>  </p>  </body>  </html>  </xsl:template>  </xsl:stylesheet>  </p:input>  <p:output name="data" id="document"/>  </p:processor>  <!-- Get some request information -->  <p:processor name="oxf:request">  <p:input name="config">  <config>  <include>/request/container-type</include>  <include>/request/request-path</include>  </config>  </p:input>  <p:output name="data" id="request"/>  </p:processor>  <!-- Apply theme -->  <p:processor name="oxf:xslt">  <p:input name="data" href="#document"/>  <p:input name="request" href="#request"/>  <p:input name="config" href="oxf:/config/theme/theme.xsl"/>  <p:output name="data" id="themed"/>  </p:processor>  <!-- Rewrite all URLs in XHTML documents -->  <p:processor name="oxf:xhtml-rewrite">  <p:input name="rewrite-in" href="#themed"/>  <p:output name="rewrite-out" id="rewritten-data"/>  </p:processor>  <!-- Convert to HTML -->  <p:processor name="oxf:qname-converter">  <p:input name="config">  <config>  <match>  <uri>http://www.w3.org/1999/xhtml</uri>  </match>  <replace>  <uri/>  <prefix/>  </replace>  </config>  </p:input>  <p:input name="data" href="#rewritten-data"/>  <p:output name="data" id="html-data"/>  </p:processor>  <p:processor name="oxf:html-converter">  <p:input name="config">  <config>  <public-doctype>-//W3C//DTD HTML 4.01 Transitional//EN</public-doctype>  <version>4.01</version>  <encoding>utf-8</encoding>  </config>  </p:input>  <p:input name="data" href="#html-data"/>  <p:output name="data" id="converted"/>  </p:processor>  <!-- Serialize -->  <p:processor name="oxf:http-serializer">  <p:input name="config">  <config>  <status-code>500</status-code>  <header>  <name>Cache-Control</name>  <value>post-check=0, pre-check=0</value>  </header>  </config>  </p:input>  <p:input name="data" href="#converted"/>  </p:processor>  </p:config>