Message output

XSLT defines the xsl:message instruction to produce output, but leaves nearly all details of its behaviour implementation-defined. Although the content of a message is often a simple text string, the specification defines it as an XML document fragment. By default Saxon serializes this document and writes it to the standard error stream. The serialization is done with method="xml" indent="yes" omit-xml-declaration="yes".

A Java application can customize the handling of xsl:message output by calling the setMessageHandler() method on the XsltTransformer or Xslt30Transformer. The argument to the method is of type Consumer<Message> and it will typically be supplied as a lambda expression, for example:

transformer.setMessageHandler(msg -> System.err.println(">>" + msg.getContent().getStringValue()));

A C# application can customize the handling of xsl:message output by setting the MessageListener property on the XsltTransformer or Xslt30Transformer. The value of the property should be of type Action<Message> and it will typically be supplied as a lambda expression, for example:

transformer.MessageListener = msg => Console.Error.WriteLine(">>" + msg.Content.StringValue);

A SaxonC application in C++, Python or PHP can customize the handling of xsl:message output by calling the setSaveXslMessage(bool show, const char* filename = nullptr) method (set_save_xsl_message() in Python) on the XsltExecutable. The first argument to the method is a boolean which indicates whether xsl:message output is sent to the standard error listener (the default is true). The second argument can be used to send the xsl:message ouput to a specified file: each message is appended at the end of the file. After executing the transformation, the xsl:message output can be retrieved using the getXslMessages() method (get_xsl_messages() in Python), which returns the sequence of messages as an XdmValue, for example in C++:

executable->setSaveXslMessage(true); result = executable->transformToString(); XdmValue * messages = executable->getXslMessages();

In Java and C#, the Message object passed to the supplied message handler contains the content of the message as an XdmNode, the location of the xsl:message instruction, the error code to be used, and a boolean value indicating whether terminate="yes" was specified.

A message handler might reformat the message (for example, by adding a timestamp) or it might redirect it to a destination such as a system logging framework, or to a status line in a graphical user interface.