Class StandardErrorListener
- All Implemented Interfaces:
ErrorListener
-
Field Summary
FieldsFields inherited from class net.sf.saxon.lib.StandardDiagnostics
MAX_MESSAGE_LENGTH, MAX_MESSAGE_LINE_LENGTH, MIN_MESSAGE_LINE_LENGTH, TARGET_MESSAGE_LINE_LENGTH
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionconstructFirstLine
(TransformerException exception, XPathException xe, String langText, String kind) Construct the first line of the error or warning message.constructMessage
(TransformerException exception, XPathException xe, String langText, String kind) Construct an error or warning message.Construct the second line of the error message.void
error
(TransformerException exception) Receive notification of a recoverable error.Expand any special characters appearing in a message.void
fatalError
(TransformerException exception) Receive notification of a non-recoverable error.Format the error code contained in the supplied exception objectformatErrorObject
(Sequence errorObject) Get a string representation of the error object associated with the exception (this represents the final argument to fn:error, in the case of error triggered by calls on the fn:error function).formatExtraContext
(Expression failingExpression, String nearBy) Create extra context information for locating the error from knowledge of the containing expression or the nearby text retained by the tokenizerformatNestedMessages
(TransformerException err, String message) Construct a message by combining the message from the top-level exception plus any messages associated with nested exceptionsGet a string containing the message for this exception and all contained exceptions.Get a string identifying the location of an error.Get the error output streamint
Get the maximum number of warnings that are reported; further warnings after this limit are silently ignoredint
getMaxOrdinaryCharacter
(int max) Set the maximum codepoint value for a character to be considered non-special.int
Get the level of information to be included in a stack trace when a dynamic error occurs.boolean
Ask whether the error listener is reporting warnings.makeAnother
(HostLanguage hostLanguage) Make a clean copy of this ErrorListener.protected void
outputStackTrace
(Logger out, XPathContext context) Generate a stack trace for a dynamic error.void
Set output destination for error messages (default is System.err)void
setMaximumNumberOfWarnings
(int max) Set the maximum number of warnings that are reported; further warnings after this limit are silently ignoredvoid
setMaxOrdinaryCharacter
(int max) Set the maximum codepoint value for a character to be considered non-special.void
setStackTraceDetail
(int level) Set the level of information to be included in a stack trace when a dynamic error occurs.void
warning
(TransformerException exception) Receive notification of a warning.Methods inherited from class net.sf.saxon.lib.StandardDiagnostics
abbreviateLocationURI, abbreviateLocationURIDefault, expandSpecialCharacters, formatListOfOffendingNodes, getInstructionName, getInstructionNameDefault, getLocationMessageText, logStackTrace, showOriginator, wordWrap
-
Field Details
-
logger
-
-
Constructor Details
-
StandardErrorListener
public StandardErrorListener()Create a Standard Error Listener
-
-
Method Details
-
makeAnother
Make a clean copy of this ErrorListener. This is necessary because the standard error listener is stateful (it remembers how many errors there have been)- Parameters:
hostLanguage
- the host language (not used by this implementation)- Returns:
- a copy of this error listener
-
setLogger
Set output destination for error messages (default is System.err)- Parameters:
logger
- The Logger to use for error messages
-
getLogger
Get the error output stream- Returns:
- the error output stream
-
setMaximumNumberOfWarnings
public void setMaximumNumberOfWarnings(int max) Set the maximum number of warnings that are reported; further warnings after this limit are silently ignored- Parameters:
max
- the maximum number of warnings output
-
getMaximumNumberOfWarnings
public int getMaximumNumberOfWarnings()Get the maximum number of warnings that are reported; further warnings after this limit are silently ignored- Returns:
- the maximum number of warnings output
-
setStackTraceDetail
public void setStackTraceDetail(int level) Set the level of information to be included in a stack trace when a dynamic error occurs.- Parameters:
level
- set to 0 (zero) for no stack trace; 1 (one) for a stack trace showing the templates and functions being executed; 2 (two) to add values of local variables and parameters (available in Saxon-EE only) Default is the maximum level available.
-
getStackTraceDetail
public int getStackTraceDetail()Get the level of information to be included in a stack trace when a dynamic error occurs.- Returns:
- 0 (zero) for no stack trace; 1 (one) for a stack trace showing the templates and functions being executed; 2 (two) to add values of local variables and parameters (available in Saxon-EE only) Default is the maximum level available.
-
setMaxOrdinaryCharacter
public void setMaxOrdinaryCharacter(int max) Set the maximum codepoint value for a character to be considered non-special. Special characters (codepoints above this value) will be expanded in hex for extra clarity in the error message.- Parameters:
max
- the highest codepoint considered non-special (defaults to 255)
-
getMaxOrdinaryCharacter
public int getMaxOrdinaryCharacter(int max) Set the maximum codepoint value for a character to be considered non-special. Special characters (codepoints above this value) will be expanded in hex for extra clarity in the error message.- Parameters:
max
- the highest codepoint considered non-special (defaults to 255)
-
warning
Receive notification of a warning.Transformers can use this method to report conditions that are not errors or fatal errors. The default behaviour is to take no action.
After invoking this method, the Transformer must continue with the transformation. It should still be possible for the application to process the document through to the end.
- Specified by:
warning
in interfaceErrorListener
- Parameters:
exception
- The warning information encapsulated in a transformer exception.- See Also:
-
isReportingWarnings
public boolean isReportingWarnings()Ask whether the error listener is reporting warnings. (If it isn't, the caller can save the effort of constructing one; which is significant because it's represented by an exception, and constructing exceptions is expensive).- Returns:
- true if the error listener is ignoring warnings, perhaps because the threshold on the number of warnings has been exceeded.
-
error
Receive notification of a recoverable error.The transformer must continue to provide normal parsing events after invoking this method. It should still be possible for the application to process the document through to the end.
The action of the standard error listener depends on the recovery policy that has been set, which may be one of RECOVER_SILENTLY, RECOVER_WITH_WARNING, or DO_NOT_RECOVER
- Specified by:
error
in interfaceErrorListener
- Parameters:
exception
- The error information encapsulated in a transformer exception.- See Also:
-
fatalError
Receive notification of a non-recoverable error.The application must assume that the transformation cannot continue after the Transformer has invoked this method, and should continue (if at all) only to collect addition error messages. In fact, Transformers are free to stop reporting events once this method has been invoked.
- Specified by:
fatalError
in interfaceErrorListener
- Parameters:
exception
- The error information encapsulated in a transformer exception.
-
constructMessage
public String constructMessage(TransformerException exception, XPathException xe, String langText, String kind) Construct an error or warning message.The default implementation outputs a two-line message: the first line is obtained by calling
constructFirstLine(TransformerException, XPathException, String, String)
, the second by callingconstructSecondLine(TransformerException, XPathException)
; these are concatenated with a newline and two spaces separating them.- Parameters:
exception
- the exception originally reported to the ErrorListenerxe
- the result of converting the exception to an XPathException (possibly null). This may be the original exception, or an XPathException nested within it.langText
- a string such as "in expression" or "in query" identifying the kind of construct that is in errorkind
- the kind of error, for example "Syntax error", "Static error", "Type error"- Returns:
- the constructed message
-
constructFirstLine
public String constructFirstLine(TransformerException exception, XPathException xe, String langText, String kind) Construct the first line of the error or warning message. This typically contains information about the kind of error that occurred, and the location where it occurred- Parameters:
exception
- the exception originally reported to the ErrorListenerxe
- the result of converting the exception to an XPathException (possibly null). This may be the original exception, or an XPathException nested within it.langText
- a string such as "in expression" or "in query" identifying the kind of construct that is in errorkind
- the kind of error, for example "Syntax error", "Static error", "Type error"- Returns:
- the constructed message
-
formatExtraContext
Create extra context information for locating the error from knowledge of the containing expression or the nearby text retained by the tokenizer- Parameters:
failingExpression
- the subexpression in which the failure occurs (possibly null)nearBy
- text from the input buffer near the error, retained by the tokenizer (possible null)- Returns:
- a message with extra context information, or an empty string if nothing is available.
-
constructSecondLine
Construct the second line of the error message. This contains the error code, error object (if applicable) and the textual message.The default implementation depends on the kind of exception:
- For a
ValidationException
, it constructs a message containing the error message together with explanations of which XSD Schema constraint was violated; - For other exceptions, it returns a string comprising two characters
of indentation, followed by the result of calling
getExpandedMessage(TransformerException)
and then formatting the result usingStandardDiagnostics.wordWrap(String)
andexpandSpecialCharacters(String)
.
- Parameters:
err
- the original reported exception- Returns:
- the string to be used as the second line of the error message
- For a
-
outputStackTrace
Generate a stack trace for a dynamic error. The default implementation callsStandardDiagnostics.logStackTrace(XPathContext, Logger, int)
supplying as the third argument the current setting ofsetStackTraceDetail(int)
, which defaults to 2.- Parameters:
out
- the destination for the stack tracecontext
- the context (which holds the information to be output)
-
getLocationMessage
Get a string identifying the location of an error. The default implementation first tries to get aSourceLocator
object from this exception or from any nested exception, and then, if aSourceLocator
is found, callsStandardDiagnostics.getLocationMessageText(SourceLocator)
to format the location information.- Parameters:
err
- the exception containing the location information- Returns:
- a message string describing the location
-
getExpandedMessage
Get a string containing the message for this exception and all contained exceptions.The default implementation outputs the concatenation (with space-separation) of:
- The error code, formatted using
formatErrorCode(TransformerException)
- The error object, formatted using
formatErrorObject(Sequence)
(whose default implementation outputs nothing) - The message associated with this exception, and with all nested exceptions,
formatted using
formatNestedMessages(TransformerException, String)
- Parameters:
err
- the exception containing the required information- Returns:
- a message that concatenates the message of this exception with its contained exceptions, also including information about the error code and location.
- The error code, formatted using
-
formatNestedMessages
Construct a message by combining the message from the top-level exception plus any messages associated with nested exceptionsThe default implementation outputs the supplied message, followed by the messages from any nested (contained) exceptions, colon-separated, with some attempt to remove duplicated messages and certain redundant message prefixes (such as "net.sf.saxon.trans.XPathException: " and "TRaX Transform Exception")
- Parameters:
err
- the original reported exceptionmessage
- the message as constructed so far, containing the error code, error object, and the message from the original reported exception- Returns:
- an expanded message containing the supplied message followed by messages from any contained exceptions.
-
formatErrorCode
Format the error code contained in the supplied exception object- Parameters:
err
- the exception object. The default implementation looks for an error code both in this object (if it is anXPathException
) or in any wrappedXPathException
. The default implementation ignores the namespace part of the error code (which is in general a QName) if it is the standard namespaceNamespaceConstant.ERR
; otherwise it displays the code in the formatprefix:localName
.- Returns:
- a string representation of the error code
-
formatErrorObject
Get a string representation of the error object associated with the exception (this represents the final argument to fn:error, in the case of error triggered by calls on the fn:error function). The standard implementation returns null, meaning that the error object is not displayed; but the method can be overridden in a subclass to create a custom display of the error object, which is then appended to the message text.- Parameters:
errorObject
- the error object passed as the last argument to fn:error. Note: this method is not called if the error object is absent/null- Returns:
- a string representation of the error object to be appended to the message, or null if no output of the error object is required
-
expandSpecialCharacters
Expand any special characters appearing in a message. Special characters will be output as themselves, followed by a hex codepoint in the form [xHHHHH]. Characters are considered special if they have a codepoint above the value set usingsetMaxOrdinaryCharacter(int)
. The default implementation returns the message unchanged if the registeredLogger
is unicode-aware.This method is provided because a number of operating systems cannot display arbitrary Unicode characters on the system console, or cannot do so unless the console has been specially configured. The simplest way to prevent messages being expanded in this way is to mark the logger as being unicode-aware.
If messages are expanded, then they will be expanded using the method
StandardDiagnostics.expandSpecialCharacters(String, int)
, which can be overridden to define the actual format in which special characters are displayed.- Parameters:
in
- the message to be expanded- Returns:
- the expanded message
-