Package net.sf.saxon.lib

## Class StandardErrorReporter

- java.lang.Object
- - net.sf.saxon.lib.StandardDiagnostics
  - - net.sf.saxon.lib.StandardErrorReporter

- All Implemented Interfaces:
    `ErrorReporter`

      public class StandardErrorReporter
      extends StandardDiagnostics
      implements ErrorReporter

  StandardErrorReporter is the standard error handler for processing XSLT and XQuery static errors, used if no other error handler is nominated.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected Logger` | `logger` |

    - ### Fields 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
    Constructor | Description
    --- | ---
    `StandardErrorReporter()` | Create a Standard Error Reporter

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.String` | `constructFirstLine​(XmlProcessingError error, java.lang.String langText, java.lang.String kind)` | Construct the first line of the error or warning message.
    `java.lang.String` | `constructMessage​(XmlProcessingError exception, java.lang.String langText, java.lang.String kind)` | Construct an error or warning message.
    `java.lang.String` | `constructSecondLine​(XmlProcessingError err)` | Construct the second line of the error message.
    `protected void` | `error​(XmlProcessingError error)` | Receive notification of an error.
    `java.lang.CharSequence` | `expandSpecialCharacters​(java.lang.CharSequence in)` | Expand any special characters appearing in a message.
    `java.lang.String` | `formatErrorCode​(XmlProcessingError err)` | Format the error code contained in the supplied exception object
    `java.lang.String` | `formatExtraContext​(Expression failingExpression, java.lang.String nearBy)` | Create extra context information for locating the error from knowledge of the containing expression or the nearby text retained by the tokenizer
    `java.lang.String` | `formatNestedMessages​(XmlProcessingError err, java.lang.String message)` | Construct a message by combining the message from the top-level exception plus any messages associated with nested exceptions
    `java.lang.String` | `getExpandedMessage​(XmlProcessingError err)` | Get a string containing the message for this exception and all contained exceptions.
    `protected java.lang.String` | `getLocationMessage​(XmlProcessingError err)` | Get a string identifying the location of an error.
    `Logger` | `getLogger()` | Get the error output stream
    `int` | `getMaximumNumberOfErrors()` | Get the maximum number of errors that are reported; further errors after this limit result in the compilation being abandoned
    `int` | `getMaximumNumberOfWarnings()` | Get the maximum number of warnings that are reported; further warnings after this limit are silently ignored
    `int` | `getMaxOrdinaryCharacter​(int max)` | Set the maximum codepoint value for a character to be considered non-special.
    `int` | `getStackTraceDetail()` | Get the level of information to be included in a stack trace when a dynamic error occurs.
    `boolean` | `isReportingWarnings()` | Ask whether the error listener is reporting warnings.
    `protected void` | `outputStackTrace​(Logger out, XPathContext context)` | Generate a stack trace.
    `void` | `report​(XmlProcessingError error)` | Report an error or warning
    `void` | `setLogger​(Logger logger)` | Set output destination for error messages (default is System.err)
    `void` | `setMaximumNumberOfErrors​(int max)` | Set the maximum number of errors that are reported; further errors after this limit result in the compilation being abandoned
    `void` | `setMaximumNumberOfWarnings​(int max)` | Set the maximum number of warnings that are reported; further warnings after this limit are silently ignored
    `void` | `setMaxOrdinaryCharacter​(int max)` | Set the maximum codepoint value for a character to be considered non-special.
    `void` | `setOutputErrorCodes​(boolean include)` | Say whether error codes should be included in the message.
    `void` | `setStackTraceDetail​(int level)` | Set the level of information to be included in a stack trace when a dynamic error occurs.
    `protected void` | `warning​(XmlProcessingError error)` | Receive notification of a warning.

    - ### Methods inherited from class net.sf.saxon.lib.StandardDiagnostics

      `abbreviateLocationURI, abbreviateLocationURIDefault, expandSpecialCharacters, formatListOfOffendingNodes, getInstructionName, getInstructionNameDefault, getLocationMessageText, printStackTrace, showOriginator, wordWrap`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### logger

          protected transient Logger logger

  - ### Constructor Detail

    - #### StandardErrorReporter

          public StandardErrorReporter()

      Create a Standard Error Reporter

  - ### Method Detail

    - #### setLogger

          public void setLogger​(Logger logger)

      Set output destination for error messages (default is System.err)
      Parameters:
        `logger` - The Logger to use for error messages

    - #### getLogger

          public Logger 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

    - #### setMaximumNumberOfErrors

          public void setMaximumNumberOfErrors​(int max)

      Set the maximum number of errors that are reported; further errors after this limit result in the compilation being abandoned
      Parameters:
        `max` - the maximum number of errors output before the compilation is abandoned

    - #### getMaximumNumberOfErrors

          public int getMaximumNumberOfErrors()

      Get the maximum number of errors that are reported; further errors after this limit result in the compilation being abandoned
      Returns:
        the maximum number of errors output before the compilation is abandoned

    - #### 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)

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

    - #### setOutputErrorCodes

          public void setOutputErrorCodes​(boolean include)

      Say whether error codes should be included in the message. This is normally suppressed during schema processing because the error codes (such as FORG0001) are generally useless.
      Parameters:
        `include` - if true (the default), then error codes are included in the message

    - #### report

          public void report​(XmlProcessingError error)

      Report an error or warning
      Specified by:
        `report` in interface `ErrorReporter`
      Parameters:
        `error` - the error or warning being reported

    - #### warning

          protected void warning​(XmlProcessingError error)

      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.

      Parameters:
        `error` - The warning information encapsulated in a transformer exception.
      See Also:
        `TransformerException`

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

          protected void error​(XmlProcessingError error)

      Receive notification of an error.

      After calling this method to report a static error, the compiler will normally continue to detect and report further errors, but the method can abort the compilation by calling `StaticError.setFatal(String)`

      Parameters:
        `error` - The error information.

    - #### constructMessage

          public java.lang.String constructMessage​(XmlProcessingError exception,
                                                   java.lang.String langText,
                                                   java.lang.String kind)

      Construct an error or warning message.

      The default implementation outputs a two-line message: the first line is obtained by calling `constructFirstLine(XmlProcessingError, String, String)`, the second by calling `constructSecondLine(XmlProcessingError)`; these are concatenated with a newline and two spaces separating them.

      Parameters:
        `exception` - the exception originally reported to the ErrorListener
        `langText` - a string such as "in expression" or "in query" identifying the kind of construct that is in error
        `kind` - the kind of error, for example "Syntax error", "Static error", "Type error"
      Returns:
        the constructed message

    - #### constructFirstLine

          public java.lang.String constructFirstLine​(XmlProcessingError error,
                                                     java.lang.String langText,
                                                     java.lang.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:
        `error` - the error originally reported to the ErrorReporter
        `langText` - a string such as "in expression" or "in query" identifying the kind of construct that is in error
        `kind` - the kind of error, for example "Syntax error", "Static error", "Type error"
      Returns:
        the constructed message

    - #### formatExtraContext

          public java.lang.String formatExtraContext​(Expression failingExpression,
                                                     java.lang.String nearBy)

      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

          public java.lang.String constructSecondLine​(XmlProcessingError err)

      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(XmlProcessingError)` and then formatting the result using `StandardDiagnostics.wordWrap(String)` and `expandSpecialCharacters(CharSequence)`.
      Parameters:
        `err` - the original reported exception
      Returns:
        the string to be used as the second line of the error message

    - #### getLocationMessage

          protected java.lang.String getLocationMessage​(XmlProcessingError err)

      Get a string identifying the location of an error. The default implementation first tries to get a `SourceLocator` object from this exception or from any nested exception, and then, if a `SourceLocator` is found, calls `StandardDiagnostics.getLocationMessageText(SourceLocator)` to format the location information.
      Parameters:
        `err` - the exception containing the location information
      Returns:
        a message string describing the location

    - #### getExpandedMessage

          public java.lang.String getExpandedMessage​(XmlProcessingError err)

      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(XmlProcessingError)`
      - The message associated with this exception, and with all nested exceptions, formatted using `formatNestedMessages(XmlProcessingError, 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.

    - #### formatNestedMessages

          public java.lang.String formatNestedMessages​(XmlProcessingError err,
                                                       java.lang.String message)

      Construct a message by combining the message from the top-level exception plus any messages associated with nested exceptions

      The 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 exception
        `message` - 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

          public java.lang.String formatErrorCode​(XmlProcessingError err)

      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 an `XPathException`) or in any wrapped `XPathException`. The default implementation ignores the namespace part of the error code (which is in general a QName) if it is the standard namespace `NamespaceConstant.ERR`; otherwise it displays the code in the format `prefix:localName`.
      Returns:
        a string representation of the error code, followed by a trailing space if non-empty; returns a zero-length string if outputErrorCodes is false.

    - #### expandSpecialCharacters

          public java.lang.CharSequence expandSpecialCharacters​(java.lang.CharSequence in)

      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 using `setMaxOrdinaryCharacter(int)`. The default implementation returns the message unchanged if the registered `Logger` 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(CharSequence, 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

    - #### outputStackTrace

          protected void outputStackTrace​(Logger out,
                                          XPathContext context)

      Generate a stack trace. This method is protected so it can be overridden in a subclass.
      Parameters:
        `out` - the destination for the stack trace
        `context` - the context (which holds the information to be output)