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 |
IDestination | Destination
The destination for the result of the transformation. The class |
ErrorReporter | ErrorReporter
The |
net.sf.saxon.trans.XsltController | Implementation Escape hatch to the underlying implementation |
XdmNode | InitialContextNode The initial context item for the stylesheet, as a node. |
QName | InitialMode
The initial mode for the stylesheet. This is either a |
QName | InitialTemplate
The initial template for the stylesheet. This is either a |
Action<Message> | MessageListener
Handler for messages output using |
ResultDocumentHandler | ResultDocumentHandler
The |
SchemaValidationMode | SchemaValidationMode
The |
ResourceResolver | TextResolver
The |
TextWriter | TraceFunctionDestination
Destination for output of messages using the |
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. |
ResourceResolver | XmlDocumentResolver
The |
Method Summary |
|
---|---|
void | Close ()
Close the |
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 | Run ()
Run the transformation, sending the result to the destination set in the
|
void | SetInputStream (Stream input, Uri baseUri) Supply the principal input document for the transformation in the form of a stream. |
void | SetInputTextReader (TextReader input, Uri baseUri)
Supply the principal input document for the transformation in the form of a |
void | SetParameter (QName name, XdmValue value) Set the value of a stylesheet parameter. |
Property Detail
BaseOutputUri
The base output URI, which acts as the base URI for resolving the href
attribute of xsl:result-document
.
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.
The Destination can be used to chain transformations into a pipeline, by using one
XsltTransformer
as the destination of another.
ErrorReporter
The ErrorReporter
to be used at run-time to notify any dynamic
errors that occur.
Implementation
Escape hatch to the underlying implementation
InitialContextNode
The initial 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
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
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
with error
code XTDE0040. Setting it to the name of a template that has template
parameters throws a SaxonApiException
with error code XTDE0060.MessageListener
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
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
The SchemaValidationMode
to be used in this transformation, especially for documents
loaded using the doc()
, document()
, or collection()
functions.
TextResolver
The TextResolver
to be used at run-time to resolve and dereference URIs
supplied to the unparsed-text()
, unparsed-text-lines()
,
unparsed-text-available()
, and json-doc()
functions.
If no TextResolver
is supplied, or if the supplied TextResolver
returns null
when called, the CommonResourceResolver
for the Saxon Configuration
is invoked,
with a ResourceRequest
having Nature == ResourceRequest.TEXT_NATURE
. If this
returns null, then the "direct" URI resolution provided by Org.XmlResolver.UriUtils
is
invoked: this is capable of handling regular file:
, http:
, and https:
URIs, as well as the data:
and pack:
schemes.
If the call on unparsed-text()
supplies an encoding parameter, this is made
available in the call to the TextResolver
.
TraceFunctionDestination
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
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:
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.
XmlDocumentResolver
The ResourceResolver
to be used at run-time to resolve and dereference URIs
supplied to functions retrieving XML, such as the fn:doc()
, fn:document()
, and
fn:doc-available()
functions, as well as fn:transform()
The URI supplied as the first argument to the resolver is the absolute URI requested, that is, the result of resolving the requested relative URI against the relevant base URI.
The requested relative URI and the corresponding base URI are supplied as separate
properties within the ResourceProperties
argument, in case they are needed.
The returned IResource
must be one of the following:
- An
IResource
such as aNodeResource
or anXmlReaderResource
whosegetItem()
method delivers anXdmNode
; - A
TextResource
delivering lexical XML in itsContent
property; this will then be parsed to deliver the corresponding XML document.
If no XmlDocumentResolver
is supplied, or if it returns null, then
the CommonResourceResolver
associated with the Saxon Configuration is invoked.
Method Detail
Close
OnClose
Define an action to be performed when writing to the Destination is complete.
Parameters:
action
- The action to be performed.Run
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
if the transformation
fails.Run
throws
SaxonApiException
Run the transformation, sending the result to the destination set in the
Destination
property (which must have been given a value).
Throws:
SaxonApiException
if the transformation
fails, or if no destination has been set.SetInputStream
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.SetInputTextReader
Uri baseUri)
Supply the principal input document for the transformation in the form of a TextReader
.
If this method is used, the InitialContextNode
is ignored.
The supplied reader will be consumed by the Run()
method.
Closing the input reader 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 reader containing the source XML 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
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).
Close the
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.