net.sf.saxon.lib

## Class StandardErrorListener

- java.lang.Object
- - net.sf.saxon.lib.StandardErrorListener

- All Implemented Interfaces:
    Serializable, ErrorListener

      public class StandardErrorListener
      extends Object
      implements ErrorListener, Serializable

  StandardErrorListener is the standard error handler for XSLT and XQuery processing errors, used if no other ErrorListener is nominated.
  Author:
    Michael H. Kay
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected PrintStream` | `errorOutput`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `StandardErrorListener()` Create a Standard Error Listener

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static String` | `abbreviatePath(String uri)` Abbreviate a URI (if requested)
    `void` | `error(TransformerException exception)` Receive notification of a recoverable error.
    `void` | `fatalError(TransformerException exception)` Receive notification of a non-recoverable error.
    `String` | `getErrorObjectString(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).
    `PrintStream` | `getErrorOutput()` Get the error output stream
    `String` | `getExpandedMessage(TransformerException err)` Get a string containing the message for this exception and all contained exceptions
    `static String` | `getInstructionName(Instruction inst)` Extract a name identifying the instruction at which an error occurred
    `String` | `getLocationMessage(TransformerException err)` Get a string identifying the location of an error.
    `int` | `getMaximumNumberOfWarnings()` Get the maximum number of warnings that are reported; further warnings after this limit are silently ignored
    `int` | `getRecoveryPolicy()` Get the recovery policy
    `StandardErrorListener` | `makeAnother(int hostLanguage)` Make a clean copy of this ErrorListener.
    `protected void` | `outputStackTrace(PrintStream out, XPathContext context)` Generate a stack trace.
    `static void` | `printStackTrace(PrintStream out, XPathContext context)` Print a stack trace to a specified output destination
    `void` | `setErrorOutput(PrintStream writer)` 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 ignored
    `void` | `setRecoveryPolicy(int policy)` Set the recovery policy
    `void` | `warning(TransformerException exception)` Receive notification of a warning.

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

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

- - ### Field Detail

    - #### errorOutput

          protected transient PrintStream errorOutput

  - ### Constructor Detail

    - #### StandardErrorListener

          public StandardErrorListener()

      Create a Standard Error Listener

  - ### Method Detail

    - #### makeAnother

          public StandardErrorListener makeAnother(int hostLanguage)

      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

    - #### setErrorOutput

          public void setErrorOutput(PrintStream writer)

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

    - #### getErrorOutput

          public PrintStream getErrorOutput()

      Get the error output stream
      Returns:
        the error output stream

    - #### setRecoveryPolicy

          public void setRecoveryPolicy(int policy)

      Set the recovery policy
      Parameters:
        `policy` - the recovery policy for XSLT recoverable errors. One of `Configuration.RECOVER_SILENTLY`, `Configuration.RECOVER_WITH_WARNINGS`, `Configuration.DO_NOT_RECOVER`.

    - #### getRecoveryPolicy

          public int getRecoveryPolicy()

      Get the recovery policy
      Returns:
        the recovery policy for XSLT recoverable errors. One of `Configuration.RECOVER_SILENTLY`, `Configuration.RECOVER_WITH_WARNINGS`, `Configuration.DO_NOT_RECOVER`.

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

    - #### warning

          public void warning(TransformerException exception)
                       throws TransformerException

      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 interface `ErrorListener`
      Parameters:
        `exception` - The warning information encapsulated in a transformer exception.
      Throws:
        `TransformerException` - if the application chooses to discontinue the transformation.
      See Also:
        `TransformerException`

    - #### error

          public void error(TransformerException exception)
                     throws TransformerException

      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 interface `ErrorListener`
      Parameters:
        `exception` - The error information encapsulated in a transformer exception.
      Throws:
        `TransformerException` - if the application chooses to discontinue the transformation.
      See Also:
        `TransformerException`

    - #### fatalError

          public void fatalError(TransformerException exception)
                          throws TransformerException

      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 interface `ErrorListener`
      Parameters:
        `exception` - The error information encapsulated in a transformer exception.
      Throws:
        `TransformerException` - if the application chooses to discontinue the transformation.
      See Also:
        `TransformerException`

    - #### outputStackTrace

          protected void outputStackTrace(PrintStream 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)

    - #### getLocationMessage

          public String getLocationMessage(TransformerException err)

      Get a string identifying the location of an error.
      Parameters:
        `err` - the exception containing the location information
      Returns:
        a message string describing the location

    - #### abbreviatePath

          public static String abbreviatePath(String uri)

      Abbreviate a URI (if requested)
      Parameters:
        `uri` - the URI to be abbreviated
      Returns:
        the abbreviated URI, unless full path names were requested, in which case the URI as supplied

    - #### getExpandedMessage

          public String getExpandedMessage(TransformerException err)

      Get a string containing the message for this exception and all contained exceptions
      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.

    - #### getErrorObjectString

          public String getErrorObjectString(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). 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

    - #### getInstructionName

          public static String getInstructionName(Instruction inst)

      Extract a name identifying the instruction at which an error occurred
      Parameters:
        `inst` - the provider of information
      Returns:
        the name of the containing instruction or expression, in user-meaningful terms

    - #### printStackTrace

          public static void printStackTrace(PrintStream out,
                             XPathContext context)

      Print a stack trace to a specified output destination
      Parameters:
        `out` - the print stream to which the stack trace will be output
        `context` - the XPath dynamic execution context (which holds the head of a linked list of context objects, representing the execution stack)

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.