Saxon.Api

 

 

Saxon.Api

Class XsltTransformer

public class XsltTransformer
implements IDestination

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.

The Xslt30Transformer class provides invocation options that are more closely aligned with the XSLT 3.0 specification, for example streamed evaluation. However, both XsltTransformer and Xslt30Transformer can be used irrespective of the XSLT language version used in the stylesheet.

Property Summary
 Uri BaseOutputUri

The base output URI, which acts as the base URI for resolving the href attribute of xsl:result-document.

 IDestination Destination

The destination for the result of the transformation. The class XmlDestination is an abstraction that allows a number of different kinds of destination to be specified.

 net.sf.saxon.trans.XsltController Implementation

Escape hatch to the underlying implementation

 XdmNode InitialContextNode

The global context item for the stylesheet, as a node.

 QName InitialMode

The initial mode for the stylesheet. This is either a QName, for a specific mode, or null, for the default mode.

 QName InitialTemplate

The initial template for the stylesheet. This is either a QName, for a named template, or null, if no initial template has been set.

 Action<Message> MessageListener

Handler for messages output using <xsl:message>.

 ResultDocumentHandler ResultDocumentHandler

The IResultDocumentHandler to be used at run-time to process the output produced by any xsl:result-document instruction with an href attribute.

 SchemaValidationMode SchemaValidationMode

The SchemaValidationMode to be used in this transformation, especially for documents loaded using the doc(), document(), or collection() functions.

 TextWriter TraceFunctionDestination

Destination for output of messages using the trace() function.

 net.sf.saxon.s9api.Destination UnderlyingDestination

The underlying implementation object. Although this method is public, it is intended for advanced applications only, and should not be considered stable from release to release.

 

Method Summary
 void Close ()

Close this Destination, releasing any resources that need to be released.

 void OnClose (Action action)

Define an action to be performed when writing to the Destination is complete.

 void Run (IDestination destination)

Run the transformation, sending the result to a specified destination.

 void SetInputStream (Stream input, Uri baseUri)

Supply the principal input document for the transformation in the form of a stream.

 void SetParameter (QName name, XdmValue value)

Set the value of a stylesheet parameter.

 

Property Detail

BaseOutputUri

public Uri BaseOutputUri {get; set; }

The base output URI, which acts as the base URI for resolving the href attribute of xsl:result-document.

Destination

public IDestination Destination {get; set; }

The destination for the result of the transformation. The class XmlDestination is an abstraction that allows a number of different kinds of destination to be specified.

The Destination can be used to chain transformations into a pipeline, by using one XsltTransformer as the destination of another.

Implementation

public net.sf.saxon.trans.XsltController Implementation {get; }

Escape hatch to the underlying implementation

InitialContextNode

public XdmNode InitialContextNode {get; set; }

The global context item for the stylesheet, as a node.

Although XSLT 3.0 allows the global context item to be any item, this interface only allows it to be a node. Most commonly it will be a document node, which might be constructed using the Build method of the DocumentBuilder object.

Note that this can be inefficient if the stylesheet uses xsl:strip-space to strip whitespace, or input-type-annotations="strip" to remove type annotations, since this will result in the transformation operating on a virtual document implemented as a view or wrapper of the supplied document.

The name of this property is potentially misleading. If the supplied node is not a document node (for example, if it is the outermost element in the document), then the global context item for the transformation (that is, the value of "." when referenced withing a global variable in the stylesheet) will actually be the root node of the containing document tree. The supplied element node, however, is used as the "initial match selection": that is, the transformation will start by finding a template rule that matches the element, and evaluating that template with the element as its context item.

InitialMode

public QName InitialMode {get; set; }

The initial mode for the stylesheet. This is either a QName, for a specific mode, or null, for the default mode.

The default mode will usually be the unnamed mode, but if the stylesheet declares a named mode as the default mode, then supplying null as the InitialMode invokes this default.

InitialTemplate

public QName InitialTemplate {get; set; }

The initial template for the stylesheet. This is either a QName, for a named template, or null, if no initial template has been set.

If the stylesheet is to be invoked by calling the template named xsl:initial-template, then the InitialTemplate property should be set to this QName explicitly.

Throws:

SaxonApiException - Setting this property to the name of a template that does not exist in the stylesheet throws a SaxonApiException with error code XTDE0040. Setting it to the name of a template that has template parameters throws a SaxonApiException with error code XTDE0060.

MessageListener

public Action<Message> MessageListener {get; set; }

Handler for messages output using <xsl:message>.

The caller may supply a message handler before calling Run; the processor will then invoke the handler once for each message generated during the transformation. Each message will be output as an object of type XdmNode representing a document node.

If no message handler is supplied by the caller, message information will be written to the standard error stream.

Each message is presented as an XML document node. Calling ToString() on the message object will usually generate an acceptable representation of the message.

When the xsl:message instruction specifies terminate="yes", the message is first notified using this interface, and then an exception is thrown which terminates the transformation.

ResultDocumentHandler

public ResultDocumentHandler ResultDocumentHandler {get; set; }

The IResultDocumentHandler to be used at run-time to process the output produced by any xsl:result-document instruction with an href attribute.

In the absence of a user-supplied result document handler, the href attribute of the xsl:result-document instruction must be a valid relative URI, which is resolved against the value of the BaseOutputUri property, and the resulting absolute URI must identify a writable resource (typically a file in filestore, using the file: URI scheme).

SchemaValidationMode

public SchemaValidationMode SchemaValidationMode {get; set; }

The SchemaValidationMode to be used in this transformation, especially for documents loaded using the doc(), document(), or collection() functions.

TraceFunctionDestination

public TextWriter TraceFunctionDestination {get; set; }

Destination for output of messages using the trace() function.

If no value is supplied by the caller, trace information will be written to the standard error stream.

The supplied destination is ignored if a TraceListener is in use.

The TextWriter should be closed by the caller after use.

UnderlyingDestination

public net.sf.saxon.s9api.Destination UnderlyingDestination {get; }

The underlying implementation object. Although this method is public, it is intended for advanced applications only, and should not be considered stable from release to release.

Value:

The underlying implementation object, which will be an instance of the class Saxon.Hej.s9api.XsltTransformer. Information about this class is available in the Saxon-EE Javadoc documentation for the very similar Java class net.sf.saxon.s9api.XsltTransformer.

Method Detail

Close

public void Close()

Close this Destination, releasing any resources that need to be released.

This method is called by the system on completion of a query or transformation. Some kinds of Destination may need to close an output stream, others might not need to do anything. The default implementation does nothing.

OnClose

public void OnClose(Action action)

Define an action to be performed when writing to the Destination is complete.

Parameters:

action - The action to be performed.

Run

public void Run(IDestination destination)
throws
SaxonApiException

Run the transformation, sending the result to a specified destination.

Parameters:

destination -  The destination for the results of the stylesheet. The class XmlDestination is an abstraction that allows a number of different kinds of destination to be specified.

Throws:

SaxonApiException - Throws a SaxonApiException if the transformation fails.

SetInputStream

public void SetInputStream(Stream input,
Uri baseUri)

Supply the principal input document for the transformation in the form of a stream.

If this method is used, the InitialContextNode is ignored.

The supplied stream will be consumed by the Run() method. Closing the input stream after use is the client's responsibility.

A base URI must be supplied in all cases. It is used to resolve relative URI references appearing within the input document.

Schema validation is applied to the input document according to the value of the SchemaValidationMode property.

Whitespace stripping is applied according to the value of the xsl:strip-space and xsl:preserve-space declarations in the stylesheet.

Parameters:

input -  The stream containing the source code of the principal input document to the transformation. The document node at the root of this document will be the global context item for the transformation.
baseUri -  The base URI of the principal input document. This is used for example by the document() function if the document contains links to other documents in the form of relative URIs.

SetParameter

public void SetParameter(QName name,
XdmValue value)

Set the value of a stylesheet parameter.

Parameters:

name - The name of the parameter, expressed as a QName. If a parameter of this name has been declared in the stylesheet, the given value will be assigned to the variable. If the variable has not been declared, calling this method has no effect (it is not an error).
value - The value to be given to the parameter. If the parameter declaration defines a required type for the variable, then this value will be converted in the same way as arguments to function calls (for example, numeric promotion is applied).