Using s9api for Transformations

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

1. Create a Processor and set any global configuration options on the Processor. If your stylesheet uses any features that require Saxon-PE or Saxon-EE, be sure to use the constructor new Processor(true).

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

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

4. 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 was 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 directly; but you can call its asDocumentDestination() method to get a Destination object allowing the transformation to act as the destination of some other process in the pipeline.

   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 download file, see the sample application S9APIExamples.java, and S9API Examples for more information.

For instance, "TransformA" in S9APIExamples tests the following (to run the Book List Example):