net.sf.saxon.s9api

Class XsltTransformer

java.lang.Object

net.sf.saxon.s9api.AbstractXsltTransformer

net.sf.saxon.s9api.XsltTransformer

All Implemented Interfaces:

Destination

public class XsltTransformer
extends AbstractXsltTransformer
implements Destination

An XsltTransformer represents a compiled and loaded stylesheet ready for execution. The XsltTransformer holds details of the dynamic evaluation context for the stylesheet.

An XsltTransformer must not be used concurrently in multiple threads. It is safe, however, to reuse the object within a single thread to run the same stylesheet several times. Running the stylesheet does not change the context that has been established. Some of the public methods are synchronized: this is not because multi-threaded execution is supported, rather it is to reduce the damage if multi-threaded execution is attempted.

An XsltTransformer is always constructed by running the Load method of an XsltExecutable.

An XsltTransformer is itself a Destination. This means it is possible to use one XsltTransformer as the destination to receive the results of another transformation, this providing a simple way for transformations to be chained into a pipeline. Note however that a when the input to a transformation is supplied in this way, it will always be built as a tree in memory, rather than the transformation being streamed. As a Destination, the transformer performs Sequence Normalization on its input; that is, it converts the input to a single document node. (The main reason for this is that when chaining XSLT transformations, the raw output of the first stylesheet is often an element node, but the second stylesheet traditionally expects a document node.)

Since:

9.0

Field Summary

Fields inherited from class net.sf.saxon.s9api.AbstractXsltTransformer

baseOutputUriWasSet, controller, processor

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	XsltTransformer(Processor processor, XsltController controller, GlobalParameterSet staticParameters) Protected constructor

Method Summary

Modifier and Type	Method and Description
void	clearParameters() Clear the values of all parameters that have been set
void	close() Close this destination, allowing resources to be released.
void	closeAndNotify() Close the destination and notify all registered listeners that it has been closed.
Destination	getDestination() Get the destination that was specified in a previous call of setDestination(net.sf.saxon.s9api.Destination)
java.net.URI	getDestinationBaseURI() Get the base URI of the resource being written to this destination
XdmNode	getInitialContextNode() Get the initial context node for the transformation, if one has been set
QName	getInitialTemplate() Get the initial named template for the transformation, if one has been set
XdmValue	getParameter(QName name) Get the value that has been set for a stylesheet parameter
Receiver	getReceiver(PipelineConfiguration pipe, SerializationProperties params) Return a Receiver which can be used to supply the principal source document for the transformation.
void	onClose(Action listener) Register a listener to be notified when a Outputter linked to this destination is closed.
void	setDestination(Destination destination) Set the destination to be used for the result of the transformation.
void	setDestinationBaseURI(java.net.URI baseURI) Set the base URI of the resource being written to this destination
void	setInitialContextNode(XdmNode node) Set the initial context node for the transformation.
void	setInitialTemplate(QName templateName) Set the initial named template for the transformation
void	setParameter(QName name, XdmValue value) Set the value of a stylesheet parameter.
void	setSource(javax.xml.transform.Source source) Set the source document for the transformation.
void	transform() Perform the transformation.

Methods inherited from class net.sf.saxon.s9api.AbstractXsltTransformer

applyTemplatesToSource, getBaseOutputURI, getDestinationReceiver, getErrorListener, getErrorReporter, getInitialMode, getMessageListener2, getReceivingTransformer, getSchemaValidationMode, getTraceFunctionDestination, getTraceListener, getUnderlyingController, getUnparsedTextURIResolver, getURIResolver, isAssertionsEnabled, isStreamableSource, setAssertionsEnabled, setBaseOutputURI, setErrorListener, setErrorReporter, setInitialMode, setMessageHandler, setMessageListener, setResultDocumentHandler, setSchemaValidationMode, setTraceFunctionDestination, setTraceListener, setUnparsedTextResolver, setURIResolver

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XsltTransformer

protected XsltTransformer(Processor processor,
                          XsltController controller,
                          GlobalParameterSet staticParameters)

Protected constructor

Parameters:

processor - the S9API processor

controller - the Saxon controller object

staticParameters - the static parameters supplied at stylesheet compile time

Method Detail

setDestinationBaseURI

public void setDestinationBaseURI(java.net.URI baseURI)

Set the base URI of the resource being written to this destination

Specified by:

setDestinationBaseURI in interface Destination

Parameters:

baseURI - the base URI to be used

getDestinationBaseURI

public java.net.URI getDestinationBaseURI()

Get the base URI of the resource being written to this destination

Specified by:

getDestinationBaseURI in interface Destination

Returns:

the baseURI, or null if none is known

onClose

public void onClose(Action listener)

Description copied from interface: Destination

Register a listener to be notified when a Outputter linked to this destination is closed.

Example: destination.onClose(() -> System.out.println("Finished writing to " + uri)

The method must be called before the call on Destination.getReceiver(PipelineConfiguration, SerializationProperties); the effect of calling it after getting a Receiver, but before closing the Outputter, is undefined.

Specified by:

onClose in interface Destination

Parameters:

listener - an object to be notified when writing to the destination is successfully completed

closeAndNotify

public void closeAndNotify()
                    throws SaxonApiException

Description copied from interface: Destination

Close the destination and notify all registered listeners that it has been closed. This method is intended for internal use by Saxon. The method first calls Destination.close() to close the destination, then it calls Consumer.accept(T) on each of the listeners in turn to notify the fact that it has been closed.

Specified by:

closeAndNotify in interface Destination

Throws:

SaxonApiException - if the close() method throws SaxonApiException.

setInitialTemplate

public void setInitialTemplate(QName templateName)

Set the initial named template for the transformation

Parameters:

templateName - the name of the initial template, or null to indicate that there should be no initial named template. Changed in 9.9: the method no longer checks that the named template exists.

getInitialTemplate

public QName getInitialTemplate()

Get the initial named template for the transformation, if one has been set

Returns:

the name of the initial template, or null if none has been set

setSource

public void setSource(javax.xml.transform.Source source)

Set the source document for the transformation.

If the source is an instance of NodeInfo, the supplied node is used directly as the initial context item of the transformation.

If the source is an instance of DOMSource, the DOM node identified by the DOMSource is wrapped as a Saxon node, and this is then used as the context item.

In other cases a new Saxon tree will be built by the transformation engine when the transformation starts, unless it is a Saxon-EE streaming transformation, in which case the document is processed in streaming fashion as it is being parsed.

To run a transformation in streaming mode, the source should be supplied as an instance of StreamSource or SAXSource.

Some kinds of Source (for example StreamSource and SAXSourceare consumed by use; others (such as DOMSource) are immutable. In the general case, therefore, the Source object that is supplied by this method does not survive a call on transform().

Parameters:

source - the principal source document for the transformation

setInitialContextNode

public void setInitialContextNode(XdmNode node)
                           throws SaxonApiUncheckedException

Set the initial context node for the transformation.

In XSLT 3.0 terms, this sets the initial match selection (the sequence to which the initial implicit call of xsl:applyTemplates is applied). It also determines how the global context item for evaluating global variables is set: following the XSLT 1.0 and 2.0 rules (XSLT 2.0 section 9.5): "For a global variable or the default value of a stylesheet parameter, the expression or sequence constructor specifying the variable value is evaluated with a singleton focus based on the root node of the tree containing the initial context node."

This value is ignored in the case where the XsltTransformer is used as the Destination of another process. In that case the initial context node will always be the document node of the document that is being streamed to this destination.

Calling this method has the side-effect of setting the initial source to null.

Parameters:

node - the initial context node, or null if there is to be no initial context node

Throws:

SaxonApiUncheckedException - if the node is unsuitable, for example if it was built using the wrong Configuration

getInitialContextNode

public XdmNode getInitialContextNode()

Get the initial context node for the transformation, if one has been set

Returns:

the initial context node, or null if none has been set. This will not necessarily be the same XdmNode instance as was supplied, but it will be an XdmNode object that represents the same underlying node.

setParameter

public void setParameter(QName name,
                         XdmValue value)

Set the value of a stylesheet parameter.

If the stylesheet does not have a parameter with this name, then the supplied value will simply be ignored (no error occurs)

If the stylesheet has a parameter with this name, and the supplied value does not match the required type, then no error will be reported at this stage, but a dynamic error will occur when the parameter value is first used. Supplied values are converted to the required type using the function conversion rules.

If the stylesheet has a parameter with this name, and the parameter is declared with static="yes", or if a parameter with the same name was supplied to the XsltCompiler, then no error will be reported at this stage, but an error will be reported when the transformation is initiated. Static parameters must be initialized using XsltCompiler.setParameter(QName, XdmValue).

Parameters:

name - the name of the stylesheet parameter, as a QName

value - the value of the stylesheet parameter, or null to clear a previously set value

Throws:

SaxonApiUncheckedException - if the value is lazily evaluated, and evaluation fails

clearParameters

public void clearParameters()

Clear the values of all parameters that have been set

getParameter

public XdmValue getParameter(QName name)

Get the value that has been set for a stylesheet parameter

Parameters:

name - the parameter whose name is required

Returns:

the value that has been set for the parameter, or null if no value has been set

setDestination

public void setDestination(Destination destination)

Set the destination to be used for the result of the transformation.

This method can be used to chain transformations into a pipeline, by using one XsltTransformer as the destination of another

The Destination object will generally be modified by a transformation (that is, by a call on transform()), and in general a Destination cannot be used more than once. Therefore, if this XsltTransformer is used for multiple transformations then a new Destination should be set for each one.

Parameters:

destination - the destination to be used for the result of this transformation

getDestination

public Destination getDestination()

Get the destination that was specified in a previous call of setDestination(net.sf.saxon.s9api.Destination)

Returns:

the destination, or null if none has been supplied

transform

public void transform()
               throws SaxonApiException

Perform the transformation. If this method is used, a destination must have been supplied previously.

Calling this method will in general consume any Source and Destination that have been supplied, so a new Source and Destination are needed for each transformation. Other properties of this XsltTransformer (for example, the values of parameters, the initial template, and initial mode) are left unchanged after the transformation completes.

If no source has been supplied (using setSource(Source)), then the method looks to see whether an initial named template has been supplied (using setInitialTemplate(QName), and if so, the transformation starts with that named template. In the absence of an initial named template, it looks to see if the stylesheet includes a template named xsl:initial-template, and if so, uses that as the entry point. If there is no source and no initial template, the method fails.

Throws:

SaxonApiException - if any dynamic error occurs during the transformation

java.lang.IllegalStateException - if no destination has been supplied

getReceiver

public Receiver getReceiver(PipelineConfiguration pipe,
                            SerializationProperties params)
                     throws SaxonApiException

Return a Receiver which can be used to supply the principal source document for the transformation. This method is intended primarily for internal use, though it can also be called by a user application that wishes to feed events into the transformation engine.

Saxon calls this method to obtain a Receiver, to which it then sends a sequence of events representing the content of an XML document. This method is provided so that XsltTransformer implements Destination, allowing one transformation to receive the results of another in a pipeline.

Before calling this method, the setDestination(net.sf.saxon.s9api.Destination) method must be called to supply a destination for the transformation.

Note that when an XsltTransformer is used as a Destination, the initial context node set on that XsltTransformer using setInitialContextNode(XdmNode) is ignored, as is the source set using setSource(javax.xml.transform.Source).

Specified by:

getReceiver in interface Destination

Parameters:

pipe - The Saxon configuration. This is supplied so that the destination can use information from the configuration (for example, a reference to the name pool) to construct or configure the returned Receiver.

params - serialization parameters (not relevant here since we aren't serializing; except possibly for the item-separator property)

Returns:

the Receiver to which events are to be sent.

Throws:

SaxonApiException - if the Receiver cannot be created

java.lang.IllegalStateException - if no Destination has been supplied

close

public void close()

Close this destination, allowing resources to be released. Used when this XsltTransformer is acting as the destination of another transformation. Saxon calls this method when it has finished writing to the destination.

Specified by:

close in interface Destination