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