Use a message handler
The default behavior for prepare-time and execution-time processing errors and other messages is to print the messages to System.err and for nonrecoverable errors to raise an XProcessException as well. If an error occurs at prepare time, the processor attempts to continue preparation and signal all errors before generating an XProcessException; but no executable is produced. At run time, execution stops at the first occurrence of an error situation.
Tasks
Change the handling of errors by registering an implementation of XMessageHandler to the XStaticContext (for prepare-time errors and other messages) or the XDynamicContext (for execution-time errors and other messages).
The XMessageHandler interface consists of a single report method that has the following parameters:
- level
- One of the following enumerators defined in the XMessageHandler interface:
- INFO
- Indicates that the error is simply informational and will not affect the result
This is also used for the XSLT message instruction when the terminate attribute evaluates to "no."
- WARNING
- Indicates a warning
The processor recovers from a warning situation, but the result might not be what was expected.
- ERROR
- Indicates a recoverable error
The processor might recover from this error for the purpose of signaling additional errors, but no result is produced.
- FATAL_ERROR
- Indicates a nonrecoverable error
The processor cannot recover from this error. It is also used for the XSLT message instruction when the terminate attribute evaluates to "yes."
- TRACE
- Indicates that the message was generated by a call to the XPath fn:trace function
- message
- Error message
- location
- Source location as an XSourceLocation if available
In general, the source location is not available for execution-time errors.
- cause
- Original exception that caused the error if available
If the input document is invalid, for example, the XML parser generates an exception that is passed to the report method through this parameter.
- errorItems
- Items that were specified for the error-object parameter to the XPath fn:error function
The implementation of XMessageHandler can present the errors and other messages as desired, such as writing to a log file rather than sending the messages to System.err. It may also be more strict and stop compilation or execution after any error including recoverable errors by generating an exception. Because the report method has no throws clause, the exception must be unchecked. The implementation might also choose to ignore informational and warning messages. In short, registering an XMessageHandler allows the application to configure message handling to suit its purposes.
Note that in the case of a nonrecoverable error, if the registered message handler does not generate an exception, an XProcessException is raised by the processor.
Manage exceptions Use a message handler and managing exceptions