Using s9api for Transformations
You can perform a transformation using the s9api interface as follows:
Processorand set any global configuration options on the
newXsltCompiler()to create an
XsltCompiler, and set any options that are local to a specific compilation (for example, the destination of error messages).
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
load30()method on the
XsltExecutable. This creates an
Xslt30Transformerrespectively. Either of these can be used to run the transformation (regardless of which XSLT version you are using), but they have different capabilities:
XsltTransformeris 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
text. As well as processing the source document using template rules, it is also used as the context item for evaluating global variables.
XsltTransformeralso 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
XsltTransformerto set values for global stylesheet parameters, but not for parameters declared at the level of a particular
The output of the transformation is specified as a
Destinationobject, 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
SchemaValidatoras the destination, or you can pipe it through another transformation, because
XsltTransformeritself implements the
Xslt30Transformerclass 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.
Xslt30Transformerdoes not implement the
Destinationinterface; if you want to pipe transformation results into a transformation, that transformation must be represented as an
Xslt30Transformercan 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.