Creating a Transformer

Creating a Transformer

Once the XSLT processor is configured, you then need to create an executable version of your XSLT stylesheet or transform, and an XM_XSLT_TRANSFORMER to use it.

The first step is to create an an XM_XSLT_TRANSFORMER_FACTORY. You simply call make, passing it the configuration you created in the previous step. By default, this caches compiled stylesheets for you. You can change this behaviour at any time by calling set_caching (on_or_off: BOOLEAN).

Then you call create_new_transformer. This takes a XM_XSLT_SOURCE as a parameter, so you first have to create one to represent your stylesheet. If you are starting with XML text, then you do this by creating an XM_XSLT_URI_SOURCE, passing it the URI of your text file. You must also pass an absolute URI as the base URI for the application. This will be used to resolve the first argument if it is relative, amongst other things.

If instead, you wish to transform a source document according to any xml-stylesheet processing instructions contained within it, then you should first call associated_stylesheet to create the XM_XSLT_SOURCE. This takes the URI of the source document as the first argument, the medium for the transformed document as the second argument, and an XM_XSLT_PI_CHOOSER as the third argument. This last argument is to allow choosing between alternate stylesheets. See Associating Style Sheets with XML documents for an understanding of what is involved.

The transformer factory either sets was_error, or else the new transformer is made available in created_transformer.

The compiled stylesheets are re-usable (which is why they are cached). To re-use one, simply call create_new_transformer again with an XM_XSLT_SOURCE that has the same URI.

However, you should not attempt to run two transformations at once (not even if they involve different stylesheets).

If you reuse a transformer, then before calling transform a second time, you may wish to call clear_document_pool. This clears all document nodes from memory, and destroys the mapping of URIs to document nodes. The reasons you might want to do this are:

To save memory (and hence garbage collection cycles) by throwing away documents which will not be used again.
If you reuse the same URIs to refer to different documents from one transformation to another. This is a doubtful practice, but if you insist on doing it then you must call clear_document_pool otherwise you will get incorrect results.

In general, it is better to not call clear_document_pool, as you will then get better performance if you reuse a document (for example, by using the document() function), as the transformer will not have to parse the document afresh.