Package net.sf.saxon.lib

Class StandardDiagnostics

java.lang.Object

net.sf.saxon.lib.StandardDiagnostics

Direct Known Subclasses:

AbstractTraceListener, StandardErrorListener, StandardErrorReporter, StandardInvalidityHandler

public class StandardDiagnostics
extends Object

This class is an abstract superclass of classes such as the StandardErrorListener and StandardInvalidityHandler, and exists to provide common utility methods for these classes, and for similar user-written classes if required

Field Summary

Fields

Modifier and Type	Field	Description
int	MAX_MESSAGE_LENGTH	Variable defining an absolute limit on the length of an error message; any message longer than this will be truncated by the wordWrap(String) method.
int	MAX_MESSAGE_LINE_LENGTH	Variable defining a threshold for word-wrapping a message.
int	MIN_MESSAGE_LINE_LENGTH	Variable defining a minimum length for parts of a word-wrapped a message.
int	TARGET_MESSAGE_LINE_LENGTH	Variable defining a target line length for messages.

Constructor Summary

Constructors

Constructor	Description
StandardDiagnostics()

Method Summary

Modifier and Type	Method	Description
String	abbreviateLocationURI(String uri)	Abbreviate a URI for use in diagnostics.
static String	abbreviateLocationURIDefault(String uri)	Abbreviate a URI for use in diagnostics.
String	expandSpecialCharacters(String in, int threshold)	Expand any special characters appearing in a message.
protected String	formatListOfOffendingNodes(ValidationFailure failure)	A ValidationFailure relating to a failing assertion contains a (possibly empty) list of nodes responsible for the failure.
String	getInstructionName(Instruction inst)	Extract a name or phrase identifying the instruction at which an error occurred.
static String	getInstructionNameDefault(Instruction inst)	Extract a name or phrase identifying the instruction at which an error occurred.
String	getLocationMessageText(SourceLocator loc)	Construct a message identifying the location of an error
void	logStackTrace(XPathContext context, Logger out, int level)	Print a stack trace to a specified output destination
protected String	showOriginator(ContextOriginator originator)	Produce text identifying a construct that originates the context for an error
String	wordWrap(String message)	Wordwrap an error message into lines of TARGET_MESSAGE_LINE_LENGTH characters or less (if possible).

Methods inherited from class java.lang.Object

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

Field Details

MAX_MESSAGE_LENGTH

public int MAX_MESSAGE_LENGTH

Variable defining an absolute limit on the length of an error message; any message longer than this will be truncated by the wordWrap(String) method. The value can be assigned. Default value is 2000.

MAX_MESSAGE_LINE_LENGTH

public int MAX_MESSAGE_LINE_LENGTH

Variable defining a threshold for word-wrapping a message. If a message is longer than this, then the wordWrap(String) method will attempt to break it into shorter lines. The value can be assigned. Default value is 100.

MIN_MESSAGE_LINE_LENGTH

public int MIN_MESSAGE_LINE_LENGTH

Variable defining a minimum length for parts of a word-wrapped a message. The wordWrap(String) method will not split a message line if it would result in a line shorter than this. The value can be assigned. Default value is 10.

TARGET_MESSAGE_LINE_LENGTH

public int TARGET_MESSAGE_LINE_LENGTH

Variable defining a target line length for messages. If word-wrapping takes place, then it will take place at the last space character found before this column position. The value can be assigned. Default value is 90.

Constructor Details

StandardDiagnostics

public StandardDiagnostics()

Method Details

getLocationMessageText

public String getLocationMessageText(SourceLocator loc)

Construct a message identifying the location of an error

Parameters:

loc - the location of the error

Returns:

a message describing the location

getInstructionName

public String getInstructionName(Instruction inst)

Extract a name or phrase identifying the instruction at which an error occurred. This default implementation invokes the static method getInstructionNameDefault(Instruction).

Parameters:

inst - the instruction in question

Returns:

the name or description of the instruction, in user-meaningful terms

getInstructionNameDefault

public static String getInstructionNameDefault(Instruction inst)

Extract a name or phrase identifying the instruction at which an error occurred. This default implementation uses terminology that is neutral between XQuery and XSLT, for example "text node constructor" in preference to "xsl:text".

Parameters:

inst - the instruction in question

Returns:

the name or description of the instruction, in user-meaningful terms

logStackTrace

public void logStackTrace(XPathContext context,
 Logger out,
 int level)

Print a stack trace to a specified output destination

Parameters:

context - the XPath dynamic execution context (which holds the head of a linked list of context objects, representing the execution stack)

out - the print stream to which the stack trace will be output

level - the level of detail: 0=none, 1=name and location of function/template, 2=values of variables

showOriginator

protected String showOriginator(ContextOriginator originator)

Produce text identifying a construct that originates the context for an error

Parameters:

originator - the ContextOriginator responsible for creating a new context

Returns:

message text (suitable for use in a phrase such as "called by XXX") for inclusion in an error message.

formatListOfOffendingNodes

protected String formatListOfOffendingNodes(ValidationFailure failure)

A ValidationFailure relating to a failing assertion contains a (possibly empty) list of nodes responsible for the failure. This may be the node to which the assertion applies, or in the case of an assertion in the form every $x in XX satisfies P it may be the node in XX for which P was not satisfied. This method converts this list of nodes into a string suitable for inclusion in error messages, typically as a complete sentence. If the list of nodes is empty, the returned string should normally be empty.

The default implementation displays a message over several lines, starting with "Nodes for which the assertion fails:", and continuing with one line per node. In the typical case where the nodes are elements, subsequent lines will take the form "element(N) on line L column C of file.xml" if the location is not, or "at x/y/z" (where x/y/z is a path to the node) otherwise.

The method is provided so that it can be overridden in a subclass.

Parameters:

failure - the validation failure being reported.

Returns:

a string describing the list of nodes contributing to the failure of an assertion.

abbreviateLocationURI

public String abbreviateLocationURI(String uri)

Abbreviate a URI for use in diagnostics.

This default implementation invokes the static method abbreviateLocationURIDefault(String).

This method is intended for use only for location URIs, not for namespace URIs.

Parameters:

uri - the URI to be abbreviated

Returns:

the abbreviated URI

abbreviateLocationURIDefault

public static String abbreviateLocationURIDefault(String uri)

Abbreviate a URI for use in diagnostics.

This default implementation displays the part of the URI after the last slash.

This method is intended for use only for location URIs, not for namespace URIs.

Parameters:

uri - the URI to be abbreviated

Returns:

the abbreviated URI

wordWrap

public String wordWrap(String message)

Wordwrap an error message into lines of TARGET_MESSAGE_LINE_LENGTH characters or less (if possible). Note that existing newlines within the message will be retained.

Parameters:

message - the message to be word-wrapped

Returns:

the message after applying word-wrapping

expandSpecialCharacters

public String expandSpecialCharacters(String in,
 int threshold)

Expand any special characters appearing in a message. In the default implementation, special characters will be output as themselves, followed by a hex codepoint in the form [xHHHHH]: for example §[xA7]

Parameters:

in - the message to be expanded

threshold - the codepoint above which characters are considered special.

Returns:

the expanded message