Error Processor
1. Rationale
When Orbeon Forms 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, Orbeon Forms displays a default error page containing the root
cause and location information if available, as well as a detailed Orbeon Forms 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><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></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:xsl="http://www.w3.org/1999/XSL/Transform"><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"><xsl:template match="/"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>Orbeon Forms - 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><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><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-plain.xsl"/><p:output name="data" id="themed"/></p:processor><p:processor name="oxf:xhtml-rewrite"><p:input name="rewrite-in" href="#themed"/><p:output name="rewrite-out" id="rewritten-data"/></p:processor><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><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>