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). -
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()
orload30()
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:-
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 methodsxml
,html
, ortext
. 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 particularxsl: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 classXdmNode
) 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, becauseXsltTransformer
itself implements theDestination
interface. -
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 aSerializer
), but this is no longer mandatory.The
Xslt30Transformer
does not implement theDestination
interface; if you want to pipe transformation results into a transformation, that transformation must be represented as anXsltTransformer
.
Both
XsltTransformer
andXslt30Transformer
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.