net.sf.saxon.s9api

Class XsltTransformer

java.lang.Object

net.sf.saxon.s9api.XsltTransformer

All Implemented Interfaces:

Destination

public class XsltTransformer
extends java.lang.Object
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.

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.

Since:

9.0

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	XsltTransformer(Processor processor, Controller 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.
java.lang.String	getBaseOutputURI() Get the base output URI.
Destination	getDestination() Get the destination that was specified in a previous call of setDestination(net.sf.saxon.s9api.Destination)
javax.xml.transform.ErrorListener	getErrorListener() Get the ErrorListener being used during this compilation episode
XdmNode	getInitialContextNode() Get the initial context node for the transformation, if one has been set
QName	getInitialMode() Get the name of the initial mode for the transformation, if one has been set.
QName	getInitialTemplate() Get the initial named template for the transformation, if one has been set
MessageListener	getMessageListener() Get the MessageListener to be notified whenever the stylesheet evaluates an xsl:message instruction.
XdmValue	getParameter(QName name) Get the value that has been set for a stylesheet parameter
Receiver	getReceiver(Configuration config) Return a Receiver which can be used to supply the principal source document for the transformation.
ValidationMode	getSchemaValidationMode() Get the schema validation mode for the transformation.
Logger	getTraceFunctionDestination() Get the destination for output from the fn:trace() function.
TraceListener	getTraceListener() Get the TraceListener to be notified of all events occurring during the transformation.
Controller	getUnderlyingController() Get the underlying Controller used to implement this XsltTransformer.
javax.xml.transform.URIResolver	getURIResolver() Get the URI resolver.
void	setBaseOutputURI(java.lang.String uri) Set the base output URI.
void	setDestination(Destination destination) Set the destination to be used for the result of the transformation.
void	setErrorListener(javax.xml.transform.ErrorListener listener) Set the ErrorListener to be used during this transformation
void	setInitialContextNode(XdmNode node) Set the initial context node for the transformation.
void	setInitialMode(QName modeName) Set the initial mode for the transformation
void	setInitialTemplate(QName templateName) Set the initial named template for the transformation
void	setMessageListener(MessageListener listener) Set the MessageListener to be notified whenever the stylesheet evaluates an xsl:message instruction.
void	setParameter(QName name, XdmValue value) Set the value of a stylesheet parameter
void	setSchemaValidationMode(ValidationMode mode) Set the schema validation mode for the transformation.
void	setSource(javax.xml.transform.Source source) Set the source document for the transformation.
void	setTraceFunctionDestination(Logger stream) Set the destination for output from the fn:trace() function.
void	setTraceListener(TraceListener listener) Set a TraceListener to be notified of all events occurring during the transformation.
void	setURIResolver(javax.xml.transform.URIResolver resolver) Set an object that will be used to resolve URIs used in fn:doc() and related functions.
void	transform() Perform the transformation.

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,
                          Controller 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

setInitialTemplate

public void setInitialTemplate(QName templateName)
                        throws SaxonApiException

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

Throws:

SaxonApiException - if there is no named template with this name

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

setInitialMode

public void setInitialMode(QName modeName)
                    throws java.lang.IllegalArgumentException

Set the initial mode for the transformation

Parameters:

modeName - the name of the initial mode. Two special values are recognized, in the reserved XSLT namespace: xsl:unnamed to indicate the mode with no name, and xsl:default to indicate the mode defined in the stylesheet header as the default mode. The value null also indicates the default mode (which defaults to the unnamed mode, but can be set differently in an XSLT 3.0 stylesheet).

Throws:

java.lang.IllegalArgumentException - if the requested mode is not defined in the stylesheet

Since:

changed in 9.6 to throw an exception if the mode is not defined in the stylesheet. Chaned in 9.7 so that null means the default mode, not necessarily the unnamed mode.

getInitialMode

public QName getInitialMode()

Get the name of the initial mode for the transformation, if one has been set.

Returns:

the initial mode for the transformation. Returns null if no mode has been set, or if the mode was set to null to represent the default (unnamed) mode

setSchemaValidationMode

public void setSchemaValidationMode(ValidationMode mode)

Set the schema validation mode for the transformation. This indicates how source documents loaded specifically for this transformation will be handled. This applies to the principal source document if supplied as a SAXSource or StreamSource, and to all documents loaded during the transformation using the doc(), document(), or collection() functions.

Parameters:

mode - the validation mode. Passing null causes no change to the existing value. Passing ValidationMode.DEFAULT resets to the initial value, which determines the validation requirements from the Saxon Configuration.

getSchemaValidationMode

public ValidationMode getSchemaValidationMode()

Get the schema validation mode for the transformation. This indicates how source documents loaded specifically for this transformation will be handled. This applies to the principal source document if supplied as a SAXSource or StreamSource, and to all documents loaded during the transformation using the doc(), document(), or collection() functions.

Returns:

the validation mode.

setSource

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

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.

Parameters:

source - the principal source document for the transformation

Throws:

SaxonApiException - if for example the Source is an unrecognized type of source

setInitialContextNode

public void setInitialContextNode(XdmNode node)

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

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

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

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

If the destination is a Serializer, then this call has two side-effects:

• It sets the base output URI for the transformation. This acts as the base URI for resolving the href attribute of any xsl:result-document instruction.
• It modifies the supplied Serializer to make it aware of the serialization properties defined in the default xsl:output declaration of the stylesheet. The serialization parameters defined in the Serializer override any serialization parameters defined using xsl:output for the principal output of the transformation. However, they have no effect on any output produced using xsl:result-document.

Parameters:

destination - the destination to be used

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

setBaseOutputURI

public void setBaseOutputURI(java.lang.String uri)

Set the base output URI.

This defaults to the system ID of the Destination for the principal output of the transformation if this is known; if it is not known, it defaults to the current directory.

If no base output URI is supplied, but the Destination of the transformation is a Serializer that writes to a file, then the URI of this file is used as the base output URI.

The base output URI is used for resolving relative URIs in the href attribute of the xsl:result-document instruction.

Parameters:

uri - the base output URI

Since:

9.2

getBaseOutputURI

public java.lang.String getBaseOutputURI()

Get the base output URI.

This returns the value set using the setBaseOutputURI(java.lang.String) method. If no value has been set explicitly, then the method returns null if called before the transformation, or the computed default base output URI if called after the transformation.

The base output URI is used for resolving relative URIs in the href attribute of the xsl:result-document instruction.

Returns:

the base output URI

Since:

9.2

setURIResolver

public void setURIResolver(javax.xml.transform.URIResolver resolver)

Set an object that will be used to resolve URIs used in fn:doc() and related functions.

Parameters:

resolver - An object that implements the URIResolver interface, or null.

Since:

9.3

getURIResolver

public javax.xml.transform.URIResolver getURIResolver()

Get the URI resolver.

Returns:

the user-supplied URI resolver if there is one, or null otherwise

Since:

9.3

setErrorListener

public void setErrorListener(javax.xml.transform.ErrorListener listener)

Set the ErrorListener to be used during this transformation

Parameters:

listener - The error listener to be used. This is notified of all dynamic errors detected during the transformation.

Since:

9.2

getErrorListener

public javax.xml.transform.ErrorListener getErrorListener()

Get the ErrorListener being used during this compilation episode

Returns:

listener The error listener in use. This is notified of all dynamic errors detected during the transformation. If no user-supplied ErrorListener has been set the method will return a system-supplied ErrorListener. If an explicit ErrorListener has been set using setErrorListener(ErrorListener), then that ErrorListener will generally be returned, unless the internal ErrorListener has been changed by some other mechanism.

Since:

9.2

setMessageListener

public void setMessageListener(MessageListener listener)

Set the MessageListener to be notified whenever the stylesheet evaluates an xsl:message instruction. If no MessageListener is nominated, the output of xsl:message instructions will be serialized and sent to the standard error stream.

Parameters:

listener - the MessageListener to be used

Since:

9.1

getMessageListener

public MessageListener getMessageListener()

Get the MessageListener to be notified whenever the stylesheet evaluates an xsl:message instruction. If no MessageListener has been nominated, return null

Returns:

the user-supplied MessageListener, or null if none has been supplied

Since:

9.1

setTraceListener

public void setTraceListener(TraceListener listener)

Set a TraceListener to be notified of all events occurring during the transformation. This will only be effective if the stylesheet was compiled with trace code enabled (see XsltCompiler.setCompileWithTracing(boolean))

Parameters:

listener - the TraceListener to be used. Note that the TraceListener has access to interal Saxon interfaces which may vary from one release to the next. It is also possible that the TraceListener interface itself may be changed in future releases.

Since:

9.2

getTraceListener

public TraceListener getTraceListener()

Get the TraceListener to be notified of all events occurring during the transformation. If no TraceListener has been nominated, return null

Returns:

the user-supplied TraceListener, or null if none has been supplied

Since:

9.2

setTraceFunctionDestination

public void setTraceFunctionDestination(Logger stream)

Set the destination for output from the fn:trace() function. By default, the destination is System.err. If a TraceListener is in use, this is ignored, and the trace() output is sent to the TraceListener.

Parameters:

stream - the PrintStream to which trace output will be sent. If set to null, trace output is suppressed entirely. It is the caller's responsibility to close the stream after use.

Since:

9.6

getTraceFunctionDestination

public Logger getTraceFunctionDestination()

Get the destination for output from the fn:trace() function.

Returns:

the Logger to which trace output will be sent. If no explicitly destination has been set, returns System.err. If the destination has been set to null to suppress trace output, returns null.

Since:

9.6

transform

public void transform()
               throws SaxonApiException

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

Throws:

SaxonApiException - if any dynamic error occurs during the transformation

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

getReceiver

public Receiver getReceiver(Configuration config)
                     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:

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

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()
           throws SaxonApiException

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

Throws:

SaxonApiException - if any failure occurs

getUnderlyingController

public Controller getUnderlyingController()

Get the underlying Controller used to implement this XsltTransformer. This provides access to lower-level methods not otherwise available in the s9api interface. Note that classes and methods obtained by this route cannot be guaranteed stable from release to release.

Returns:

the underlying Controller

Since:

9.0.0.4