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>