Saxon.Api

Class XsltCompiler

public class XsltCompiler

An XsltCompiler object allows XSLT stylesheets to be compiled. The compiler holds information that represents the static context for the compilation.

To construct an XsltCompiler, use the factory method NewXsltCompiler on the XsltCompiler.Processor object.

An XsltCompiler may be used repeatedly to compile multiple queries. Any changes made to the XsltCompiler (that is, to the static context) do not affect queries that have already been compiled. An XsltCompiler may be used concurrently in multiple threads, but it should not then be modified once initialized.

Property Summary
bool	AssertionsEnabled Indicates whether or not assertions (`xsl:assert` instructions) are enabled at compile time.
Uri	BaseUri The base URI of the stylesheet, which forms part of the static context of the stylesheet. This is used for resolving any relative URIs appearing within the stylesheet, for example in `xsl:include` and `xsl:import` declarations, in schema locations defined to `xsl:import-schema`, or as an argument to the `document()` or `doc()` function.
string	DefaultCollationName The name of the default collation used by stylesheets compiled using this `XsltCompiler`. This must be the name of a collation that is known to the `Processor`.
ErrorReporter	ErrorReporter The `ErrorReporter` to be used when reporting static errors in a stylesheet.
bool	FastCompilation Property to check and set fast compilation. Fast compilation will generally be achieved at the expense of run-time performance and quality of diagnostics. Fast compilation is a good trade-off if (a) the stylesheet is known to be correct, and (b) once compiled, it is only executed once against a document of modest size.
bool	JustInTimeCompilation Property to say whether just-in-time compilation of template rules should be used. Set to true if just-in-time compilation is to be enabled. With this option enabled, static analysis of a template rule is deferred until the first time that the template is matched.This can improve performance when many template rules are rarely used during the course of a particular transformation; however, it means that static errors in the stylesheet will not necessarily cause the `Compile(Source)` method to throw an exception (errors in code that is actually executed will still be notified to the registered `ErrorReporter` or `ErrorList`, but this may happen after the { `Compile(Source)` method returns). This option is enabled by default in Saxon-EE, and is not available in Saxon-HE or Saxon-PE. Recommendation: disable this option unless you are confident that the stylesheet you are compiling is error-free.
Processor	Processor The `Processor` from which this `XsltCompiler` was constructed
bool	Relocatable Indicates whether or not any compiled package produced by this compiler is relocatable. If a package is relocatable, then any run-time operation that depends on the static base URI (for example, the `fn:doc` function) uses the deployed location of the package, not the location of the original source code.
bool	SchemaAware The `SchemaAware` property determines whether the stylesheet is schema-aware. By default, a stylesheet is schema-aware if it contains one or more `xsl:import-schema` declarations. This option allows a stylesheet to be marked as schema-aware even if it does not contain such a declaration.
ResourceResolver	StylesheetModuleResolver A `ResourceResolver`, which will be used to resolve URI references appearing in `xsl:include` and `xsl:import` declarations within a stylesheet.
string	TargetEdition Indicates the Saxon edition under which any compiled package is intended to execute. The value should be set to "JS" when compiling packages intended for execution under Saxon-JS 2.0 or later.
string	XsltLanguageVersion The `XsltLanguageVersion` property determines the version of the XSLT language specification implemented by the compiler. In this Saxon release the values "3.0" and "4.0" are recognized. The default is "3.0". Set the value to "4.0" to enable support for experimental features defined in the XSLT 4.0 proposal (which is likely to change before it stabilizes).

Method Summary
void	ClearParameters () Clear the values of all stylesheet parameters previously set using `SetParameter(QName, XdmValue)`. This resets the parameters to their initial ("undeclared") state
XsltExecutable	Compile (Stream input) Compile a stylesheet supplied as a Stream.
XsltExecutable	Compile (Stream input, Uri baseUri) Compile a stylesheet supplied as a Stream, along with a base URI.
XsltExecutable	Compile (TextReader input) Compile a stylesheet supplied as a `TextReader`.
XsltExecutable	Compile (Uri uri) Compile a stylesheet, retrieving the source using a URI.
XsltExecutable	Compile (XmlReader reader) Compile a stylesheet, delivered using an `XmlReader`.
XsltExecutable	Compile (XdmNode node) Compile a stylesheet, located at an `XdmNode`. This may be a document node whose child is an `xsl:stylesheet` or `xsl:transform` element, or it may be the `xsl:stylesheet` or `xsl:transform` element itself.
XsltExecutable	CompileAssociatedStylesheet (Uri uri, string media) Locate and compile a stylesheet identified by an `<?xml-stylesheet?>` processing instruction within a source document, and that match the given criteria.
XsltExecutable	CompileAssociatedStylesheet (XdmNode source) Locate and compile a stylesheet identified by an `<?xml-stylesheet?>` processing instruction within a source document.
XsltPackage	CompilePackage (Stream input) Compile a library package.
XsltPackage	CompilePackage (Stream input, Uri baseUri) Compile a library package, supplying a stream and a base URI
net.sf.saxon.trans.CompilerInfo	GetUnderlyingCompilerInfo () Get the underlying `CompilerInfo` object, which provides more detailed (but less stable) control over some compilation options
void	ImportPackage (XsltPackage thePackage) Import a library package. Calling this method makes the supplied package available for reference in the `xsl:use-package` declaration of subsequent compilations performed using this `XsltCompiler`.
void	ImportPackage (XsltPackage thePackage, string packageName, string version) Import a library package. Calling this method makes the supplied package available for reference in the `xsl:use-package` declaration of subsequent compilations performed using this `XsltCompiler`.
XsltExecutable	LoadExecutablePackage (Uri location) Load a compiled package from a file or from a remote location, with the intent to use this as a complete executable stylesheet, not as a library package.
XsltPackage	LoadLibraryPackage (Uri location) Load a compiled package from a file or from a remote location.
void	SetParameter (QName name, XdmValue value) Externally set the value of a static parameter (new facility in XSLT 3.0)

Property Detail

AssertionsEnabled

public bool AssertionsEnabled {get; set; }

Indicates whether or not assertions (xsl:assert instructions) are enabled at compile time.

By default assertions are disabled at compile time. If assertions are enabled at compile time, then by default they will also be enabled at run time; but they can be disabled at run time by specific request. At compile time, assertions can be enabled for some packages and disabled for others; at run time, they can only be enabled or disabled globally.

Returns:

true if assertions are enabled at compile time

BaseUri

public Uri BaseUri {get; set; }

The base URI of the stylesheet, which forms part of the static context of the stylesheet. This is used for resolving any relative URIs appearing within the stylesheet, for example in xsl:include and xsl:import declarations, in schema locations defined to xsl:import-schema, or as an argument to the document() or doc() function.

This base URI is used only if the input supplied to the Compile method does not provide its own base URI. It is therefore used on the version of the method that supplies input from a Stream. On the version that supplies input from an XmlReader, this base URI is used only if the XmlReader does not have its own base URI.

DefaultCollationName

public string DefaultCollationName {get; set; }

The name of the default collation used by stylesheets compiled using this XsltCompiler. This must be the name of a collation that is known to the Processor.

ErrorReporter

public ErrorReporter ErrorReporter {get; set; }

The ErrorReporter to be used when reporting static errors in a stylesheet.

FastCompilation

public bool FastCompilation {get; set; }

Property to check and set fast compilation. Fast compilation will generally be achieved at the expense of run-time performance and quality of diagnostics. Fast compilation is a good trade-off if (a) the stylesheet is known to be correct, and (b) once compiled, it is only executed once against a document of modest size.

Fast compilation may result in static errors going unreported, especially if they occur in code that is never executed.

The current implementation is equivalent to switching off all optimizations other than just-in-time compilation of template rules. Setting this option, however, indicates an intent rather than a mechanism, and the implementation details may change in future to reflect the intent.

Set to true to request fast compilation; set to false to revert to the optimization options defined in the Configuration.

JustInTimeCompilation

public bool JustInTimeCompilation {get; set; }

Property to say whether just-in-time compilation of template rules should be used. Set to true if just-in-time compilation is to be enabled. With this option enabled, static analysis of a template rule is deferred until the first time that the template is matched.This can improve performance when many template rules are rarely used during the course of a particular transformation; however, it means that static errors in the stylesheet will not necessarily cause the Compile(Source) method to throw an exception (errors in code that is actually executed will still be notified to the registered ErrorReporter or ErrorList, but this may happen after the { Compile(Source) method returns). This option is enabled by default in Saxon-EE, and is not available in Saxon-HE or Saxon-PE.

Recommendation: disable this option unless you are confident that the stylesheet you are compiling is error-free.

Processor

public Processor Processor {get; }

The Processor from which this XsltCompiler was constructed

Relocatable

public bool Relocatable {get; set; }

Indicates whether or not any compiled package produced by this compiler is relocatable. If a package is relocatable, then any run-time operation that depends on the static base URI (for example, the fn:doc function) uses the deployed location of the package, not the location of the original source code.

SchemaAware

public bool SchemaAware {get; set; }

The SchemaAware property determines whether the stylesheet is schema-aware. By default, a stylesheet is schema-aware if it contains one or more xsl:import-schema declarations. This option allows a stylesheet to be marked as schema-aware even if it does not contain such a declaration.

If the stylesheet is not schema-aware, then schema-validated input documents will be rejected.

The reason for this option is that it is expensive to generate code that can handle typed input documents when they will never arise in practice.

The initial setting of this property is false, regardless of whether or not the Processor is schema-aware. Setting this property to true if the processor is not schema-aware will cause an Exception.

StylesheetModuleResolver

public ResourceResolver StylesheetModuleResolver {get; set; }

A ResourceResolver, which will be used to resolve URI references appearing in xsl:include and xsl:import declarations within a stylesheet.

If no StylesheetModuleResolver is set for the XsltCompiler, or if the supplied ResourceResolver returns null, then the relevant URIs will be resolved using the common resolver defined at the Saxon Configuration level; failing this, the system falls back to default mechanisms for URI resolution.

TargetEdition

public string TargetEdition {get; set; }

Indicates the Saxon edition under which any compiled package is intended to execute. The value should be set to "JS" when compiling packages intended for execution under Saxon-JS 2.0 or later.

XsltLanguageVersion

public string XsltLanguageVersion {get; set; }

The XsltLanguageVersion property determines the version of the XSLT language specification implemented by the compiler. In this Saxon release the values "3.0" and "4.0" are recognized. The default is "3.0". Set the value to "4.0" to enable support for experimental features defined in the XSLT 4.0 proposal (which is likely to change before it stabilizes).

Method Detail

ClearParameters

public void ClearParameters()

Clear the values of all stylesheet parameters previously set using SetParameter(QName, XdmValue). This resets the parameters to their initial ("undeclared") state

Compile

public XsltExecutable Compile(Stream input)
throws
SaxonApiException

Compile a stylesheet supplied as a Stream.

If the stylesheet contains any xsl:include or xsl:import declarations, then the BaseUri property must be set to allow these to be resolved.

The stylesheet is contained in the part of the input stream between its current position and the end of the stream. It is the caller's responsibility to close the input stream after use. If the compilation succeeded, then on exit the stream will be exhausted; if compilation failed, the current position of the stream on exit is undefined.

Parameters:

input - A stream containing the source text of the stylesheet

Returns:

An XsltExecutable which represents the compiled stylesheet object. The XsltExecutable may be loaded as many times as required, in the same or a different thread. The XsltExecutable is not affected by any changes made to the XsltCompiler once it has been compiled.

Throws:

SaxonApiException - Throws a SaxonApiException if errors were detected during static analysis of the stylesheet. Details of the errors will be reported to the ErrorReporter if supplied; otherwise they will be written to the standard error stream. The exception that is returned from this method is merely a summary indicating the status, and is not useful for diagnosing the actual error.

Example:

Stream source = new FileStream("input.xsl", FileMode.Open, FileAccess.Read); XsltExecutable q = compiler.Compile(source); source.Close();

Compile

public XsltExecutable Compile(Stream input,
Uri baseUri)
throws
SaxonApiException

Compile a stylesheet supplied as a Stream, along with a base URI.

The BaseUri property of the XsltCompiler is ignored.

Parameters:

input - A stream containing the source text of the stylesheet

baseUri - The base URI of the stylesheet, used for resolving any relative URIs in xsl:include and xsl:import declarations, and anywhere else that the static base URI of the stylesheet is relevant.

Returns:

Throws:

Example:

Stream source = new FileStream("input.xsl", FileMode.Open, FileAccess.Read); XsltExecutable q = compiler.Compile(source, new Uri(); source.Close();

Compile

public XsltExecutable Compile(TextReader input)
throws
SaxonApiException,
SaxonApiException

Compile a stylesheet supplied as a TextReader.

If the stylesheet contains any xsl:include or xsl:import declarations, then the BaseUri property must be set to allow these to be resolved.

The stylesheet is contained in the part of the input stream between its current position and the end of the stream. It is the caller's responsibility to close the TextReader after use. If the compilation succeeded, then on exit the stream will be exhausted; if compilation failed, the current position of the stream on exit is undefined.

Parameters:

input - A TextReader containing the source text of the stylesheet

Returns:

Throws:

SaxonApiException - If compilation fails, a SaxonApiException is thrown. Note that this will not contain useful error information; to capture details of specific errors, nominate an ErrorReporter to receive notifications.

Example:

String ss = "<xsl:stylesheet version='2.0'>....</xsl:stylesheet>"; TextReader source = new StringReader(ss); XsltExecutable q = compiler.Compile(source); source.Close();

Compile

public XsltExecutable Compile(Uri uri)
throws
SaxonApiException

Compile a stylesheet, retrieving the source using a URI.

The document located via the URI is parsed using the System.Xml parser. This URI is used as the base URI of the stylesheet: the BaseUri property of the Compiler is ignored.

Parameters:

uri - The URI identifying the location where the stylesheet document can be found. If a StylesheetModuleResolver has been defined, it will be used to resolve the supplied URI.

Returns:

An XsltExecutable which represents the compiled stylesheet object. The XsltExecutable may be run as many times as required, in the same or a different thread. The XsltExecutable is not affected by any changes made to the XsltCompiler once it has been compiled.

Throws:

Compile

public XsltExecutable Compile(XmlReader reader)
throws
SaxonApiException,
SaxonApiException

Compile a stylesheet, delivered using an XmlReader.

The XmlReader is responsible for parsing the document; this method builds a tree representation of the document (in an internal Saxon format) and compiles it. The XmlReader will be used as supplied; it is the caller's responsibility to ensure that the settings of the XmlReader are consistent with the requirements of the XSLT specification (for example, that entity references are expanded and whitespace is preserved).

If the XmlReader has a BaseUri property, then that property determines the base URI of the stylesheet module, which is used when resolving any xsl:include or xsl:import declarations. If the XmlReader has no BaseUri property, then the BaseUri property of the Compiler is used instead. An ArgumentNullException is thrown if this property has not been supplied.

Parameters:

reader - The XmlReader (that is, the XML parser) used to supply the document containing the principal stylesheet module.

Returns:

Throws:

Compile

public XsltExecutable Compile(XdmNode node)
throws
SaxonApiException,
SaxonApiException

Compile a stylesheet, located at an XdmNode. This may be a document node whose child is an xsl:stylesheet or xsl:transform element, or it may be the xsl:stylesheet or xsl:transform element itself.

Parameters:

node - The document node or the outermost element node of the document containing the principal stylesheet module.

Returns:

Throws:

CompileAssociatedStylesheet

public XsltExecutable CompileAssociatedStylesheet(Uri uri,
string media)
throws
SaxonApiException

Locate and compile a stylesheet identified by an <?xml-stylesheet?> processing instruction within a source document, and that match the given criteria.

There are some limitations in the current implementation. Parameters of the xml-stylesheet instruction other than the media type, are ignored. The href attribute must either reference an embedded stylesheet within the same document or a non-embedded external stylesheet.

Parameters:

uri - The URI of the source document containing the xml-stylesheet processing instruction.

media - The media attribute to be matched. May be null, in which case the "application/xml" mime type will be used when fetching the source document from the Uri.

Returns:

An XsltExecutable which represents the compiled stylesheet object.

Throws:

CompileAssociatedStylesheet

public XsltExecutable CompileAssociatedStylesheet(XdmNode source)
throws
SaxonApiException

Locate and compile a stylesheet identified by an <?xml-stylesheet?> processing instruction within a source document.

There are some limitations in the current implementation. The media type is ignored, as are the other parameters of the xml-stylesheet instruction. The href attribute must either reference an embedded stylesheet within the same document or a non-embedded external stylesheet.

Parameters:

source - The document node of the source document containing the xml-stylesheet processing instruction.

Returns:

An XsltExecutable which represents the compiled stylesheet object.

Throws:

CompilePackage

public XsltPackage CompilePackage(Stream input)

Compile a library package.

The source argument identifies an input stream containing an xsl:package element. Any packages on which this package depends must have been made available to the XsltCompiler by importing them using ImportPackage.

The base URI of the package (used for resolving xsl:import and xsl:include declarations, and for any other constructs that depend on the static base URI) is taken from the BaseUri property of the compiler.

The caller is responsible for closing the input stream after use.

Parameters:

input - source identifies an XML document holding the the XSLT package to be compiled

Returns:

The XsltPackage that results from the compilation. Note that this package is not automatically imported to this XsltCompiler; if the package is required for use in subsequent compilations then it must be explicitly imported.

CompilePackage

public XsltPackage CompilePackage(Stream input,
Uri baseUri)

Compile a library package, supplying a stream and a base URI

The BaseUri property of the compiler is ignored

The caller is responsible for closing the input stream after use.

Parameters:

input - a stream containing an XML document holding the the XSLT package to be compiled

baseUri - the base URI of the stream, used for resolving any relative references

Returns:

GetUnderlyingCompilerInfo

public net.sf.saxon.trans.CompilerInfo GetUnderlyingCompilerInfo()

Get the underlying CompilerInfo object, which provides more detailed (but less stable) control over some compilation options

Returns:

the underlying CompilerInfo object, which holds compilation-time options. The methods on this object are not guaranteed stable from release to release.

ImportPackage

public void ImportPackage(XsltPackage thePackage)

Import a library package. Calling this method makes the supplied package available for reference in the xsl:use-package declaration of subsequent compilations performed using this XsltCompiler.

since 9.6

Parameters:

thePackage - the package to be imported

ImportPackage

public void ImportPackage(XsltPackage thePackage,
string packageName,
string version)

Import a library package. Calling this method makes the supplied package available for reference in the xsl:use-package declaration of subsequent compilations performed using this XsltCompiler.

since 9.8

Parameters:

thePackage - the package to be imported

packageName - name of the package to be imported

version - version identifier for the package to be imported

LoadExecutablePackage

public XsltExecutable LoadExecutablePackage(Uri location)

Load a compiled package from a file or from a remote location, with the intent to use this as a complete executable stylesheet, not as a library package.

The supplied URI represents the location of a resource which must have been originally created using XsltPackage.Save(Stream).

Parameters:

location - the location from which the package is to be loaded, as a URI

Returns:

the compiled package loaded from the supplied file or remote location

LoadLibraryPackage

public XsltPackage LoadLibraryPackage(Uri location)

Load a compiled package from a file or from a remote location.

The supplied URI represents the location of a resource which must have been originally created using XsltPackage.Save(Stream). The result of loading the package is returned as an XsltPackage object. Note that this package is not automatically imported to this XsltCompiler; if the package is required for use in subsequent compilations then it must be explicitly imported.

Parameters:

location - the location from which the package is to be loaded, as a URI

Returns:

the compiled package loaded from the supplied file or remote location

SetParameter

public void SetParameter(QName name,
XdmValue value)

Externally set the value of a static parameter (new facility in XSLT 3.0)

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

Saxon.Api

Saxon.Api

Class XsltCompiler

Property Summary

Method Summary

Property Detail

AssertionsEnabled

BaseUri

DefaultCollationName

ErrorReporter

FastCompilation

JustInTimeCompilation

Processor

Relocatable

SchemaAware

StylesheetModuleResolver

TargetEdition

XsltLanguageVersion

Method Detail

ClearParameters

Compile

Compile

Compile

Compile

Compile

Compile

CompileAssociatedStylesheet

CompileAssociatedStylesheet

CompilePackage

CompilePackage

GetUnderlyingCompilerInfo

ImportPackage

ImportPackage

LoadExecutablePackage

LoadLibraryPackage

SetParameter