Using s9api for Transformations

You can perform a transformation using the s9api interface as follows:

Create a Processor and set any global configuration options on the Processor.
Call newXsltCompiler() to create an XsltCompiler, and set any options that are local to a specific compilation (for example, the destination of error messages).

By default, error messages are directed to the System.err output stream, which is fine for an application run from a console, but not so good if it's executing on a web server, or behind a graphical interface. In such cases you'll want to think carefully about where to direct the error messages. You can either write your own ErrorListener to format the messages any way you want, or you can use Saxon's StandardErrorListener and change its output destination by supplying your own Logger. For example: xsltCompiler.setErrorListener(new StandardErrorListener(new StandardLogger(new File("log.txt"))))
Call the compile() method to compile a stylesheet. The result is an XsltExecutable, which can be used as often as you like, in the same thread or in different threads.
To run a transformation, call either the load() or load30() method on the XsltExecutable. This creates an XsltTransformer or Xslt30Transformer respectively. Either of these can be used to run the transformation (regardless of which XSLT version you are using), but they have different capabilities:
1. The XsltTransformer is geared towards the traditional way of running an XSLT transformation, by supplying a principal source document as input. When you call the transform() method, the template rule that best matches this source document is located and executed. The result of executing this template is wrapped into a document node to create a result tree, which is optionally serialized using one of the output methods xml, html, or text. As well as processing the source document using template rules, it is also used as the context item for evaluating global variables.
  
  The XsltTransformer also allows you to start executing the stylesheet with a named template as the entry point. In this case there will not necessarily be a source document, though you can still supply one, and it will be used as the context item for global variables.
  
  You can use methods on the XsltTransformer to set values for global stylesheet parameters, but not for parameters declared at the level of a particular xsl:template element.
  
  The output of the transformation is specified as a Destination object, which allows a wide range of possibilities: you can send the output to a serializer, or to a SAX ContentHandler. You can build a tree either in Saxon's native format (represented by the s9api class XdmNode) or as a DOM. You can send the output to be validated against a schema by nominating a SchemaValidator as the destination, or you can pipe it through another transformation, because XsltTransformer itself implements the Destination interface.
2. The Xslt30Transformer class is introduced in Saxon 9.6, and as its name suggests, it provides new ways of executing stylesheet code that are defined in the XSLT 3.0 specification, though Saxon also allows you to use the same entry points with 1.0 or 2.0 stylesheets. Among the new capabilities are:
  - You can invoke a specific stylesheet function, with parameters, rather than invoking a named template or template rule.
  - If you start execution with a named template or template rule, you can supply values for the parameters defined on that template, as well as the global stylesheet parameters.
  - Whether you execute a template or a function, you can return the results in raw form rather than wrapping them in a result tree. For example, a function (or template) might return a sequence of strings, or a single boolean, or a map, or even a function.
  - There is no longer any necessary relationship between the "principal source document" (if it still exists) and the context item for evaluating global variables. The two things are quite independent of each other.
  It is still possible to wrap the output in a result tree and send it to a Destination (which might be a Serializer), but this is no longer mandatory.
  
  The Xslt30Transformer does not implement the Destination interface; if you want to pipe transformation results into a transformation, that transformation must be represented as an XsltTransformer.
Both XsltTransformer and Xslt30Transformer can be serially reused, but they must not be shared across multiple threads. Both allow you to set any options required for the specific transformation (for example, the global context item, the stylesheet parameters, and the error listener).

Examples of s9api transformations are included in the Saxon resources file, see module S9APIExamples.java.