Saxon.Api

Class DocumentBuilder

Class DomDestination

Class DynamicContext

Class DynamicError

Class EmptyEnumerator

Class ExtensionFunctionCall

Class ExtensionFunctionDefinition

Class InvalidityHandlerWrapper

Class NamespaceConstant

Class NullDestination

Class Processor

Class QName

Class SchemaManager

Class SchemaValidator

Class Serializer

Class StandardLogger

Class StaticContext

Class StaticError

Class TextWriterDestination

Class WhitespacePolicy

Class XPathCompiler

Class XPathExecutable

Class XPathSelector

Class XQueryCompiler

Class XQueryEvaluator

Class XQueryExecutable

Class XdmAnyFunctionType

Class XdmAnyItemType

Class XdmAnyNodeType

Class XdmArray

Class XdmAtomicType

Class XdmAtomicValue

Class XdmDestination

  - Class TreeProtector

Class XdmEmptySequence

Class XdmExternalObjectValue

Class XdmFunctionItem

Class XdmItem

Class XdmItemType

Class XdmMap

Class XdmNode

Class XdmNodeKind

Class XdmSequenceType

Class XdmValue

Class XmlDestination

Class Xslt30Transformer

Class XsltCompiler

Class XsltExecutable

  - Class ParameterDetails

Class XsltPackage

Class XsltTransformer

Enum RecoveryPolicy

Enum SchemaValidationMode

Enum TreeModel

Enum XdmAxis

Interface IInvalidityHandler

Interface IMessageListener

Interface IQueryResolver

Interface IResultDocumentHandler

Interface IXdmEnumerator

Interface IXmlLocation

Interface SchemaResolver

 

Saxon.Api
Class XsltCompiler 

public class XsltCompiler
implements object

An XsltCompiler object allows XSLT 2.0 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 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
 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.

 Processor Processor

The Processor from which this XsltCompiler was constructed

 XmlResolver XmlResolver

An XmlResolver, which will be used to resolve URI references while compiling a stylesheet

 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.

 bool AssertionsEnabled

Indicates whether or not assertions (xsl:assert instructions) have been enabled at run time.

 string XsltLanguageVersion

The XsltLanguageVersion property determines whether the version of the XSLT language specification implemented by the compiler. The values 2.0 and 3.0 refer to the XSLT 2.0 and XSLT 3.0 (formerly XSLT 2.1) specifications. The value 0.0 (which is the initial default) indicates that the value is to be taken from the version attribute of the xsl:stylesheet element.

 bool ByteCodeEnabled

This property determines whether bytecode is to be generated in the compiled code

 IList ErrorList

List of errors. The caller should supply an empty list before calling Compile; the processor will then populate the list with error information obtained during the compilation. Each error will be included as an object of type StaticError. If no error list is supplied by the caller, error information will be written to an error list allocated by the system, which can be obtained as the value of this property.

 
Method Summary
 void DeclareCollation(System.Uri uri, System.Globalization.CompareInfo compareInfo, System.Globalization.CompareOptions options, bool isDefault)

Create a collation based on a given CompareInfo and CompareOptions

 XsltExecutable Compile(System.IO.Stream input)

Compile a stylesheet supplied as a Stream.

 XsltPackage CompilePackage(System.IO.Stream input)

Compile a library package.

The source argument identifies an XML file 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.

 IList<XsltPackage> CompilePackages(System.Collections.Generic.IList{System.String} sources)

Compile a list of packages.
 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 , string )

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.

 XsltPackage LoadLibraryPackage(System.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(System.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.

 XsltExecutable LoadExecutablePackage(System.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(System.Stream).

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

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

 void SetParameter(QName name, XdmValue value)

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

 XsltExecutable Compile(System.IO.TextReader input)

Compile a stylesheet supplied as a TextReader.

 XsltExecutable Compile(System.Uri uri)

Compile a stylesheet, retrieving the source using a URI.

 XsltExecutable Compile(System.Xml.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(XdmNode source)

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

 
Property Detail

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.

Processor

public Processor Processor {get; set; }

The Processor from which this XsltCompiler was constructed

XmlResolver

public XmlResolver XmlResolver {get; set; }

An XmlResolver, which will be used to resolve URI references while compiling a stylesheet

If no XmlResolver is set for the XsltCompiler, the XmlResolver is used that was set on the Processor at the time NewXsltCompiler was called.

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.

AssertionsEnabled

public bool AssertionsEnabled {get; set; }

Indicates whether or not assertions (xsl:assert instructions) have been enabled at run 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.

Since 9.7

Returns:
true if assertions are enabled at compile time

XsltLanguageVersion

public string XsltLanguageVersion {get; set; }

The XsltLanguageVersion property determines whether the version of the XSLT language specification implemented by the compiler. The values 2.0 and 3.0 refer to the XSLT 2.0 and XSLT 3.0 (formerly XSLT 2.1) specifications. The value 0.0 (which is the initial default) indicates that the value is to be taken from the version attribute of the xsl:stylesheet element.

Values that are not numerically equal to one of the above values are rejected.

A warning is output (unless suppressed) when the XSLT language version supported by the processor is different from the value of the version attribute of the xsl:stylesheet element.

XSLT 3.0 features are supported only in Saxon-PE and Saxon-EE. Setting the value to 3.0 under Saxon-HE will cause an error if (and only if) the stylesheet actually uses XSLT 3.0 constructs.

ByteCodeEnabled

public bool ByteCodeEnabled {set; }

This property determines whether bytecode is to be generated in the compiled code

true if bytecode is to be generated, false if not

ErrorList

public IList ErrorList {get; set; }

List of errors. The caller should supply an empty list before calling Compile; the processor will then populate the list with error information obtained during the compilation. Each error will be included as an object of type StaticError. If no error list is supplied by the caller, error information will be written to an error list allocated by the system, which can be obtained as the value of this property.

By supplying a custom List with a user-written add() method, it is possible to intercept error conditions as they occur.

Method Detail

DeclareCollation

public void DeclareCollation(System.Uri uri,
System.Globalization.CompareInfo compareInfo,
System.Globalization.CompareOptions options,
bool isDefault)

Create a collation based on a given CompareInfo and CompareOptions

Parameters:
uri -
The collation URI to be used within the XPath expression to refer to this collation
compareInfo -
The CompareInfo, which determines the language-specific collation rules to be used
options -
Options to be used in performing comparisons, for example whether they are to be case-blind and/or accent-blind
isDefault -
If true, this collation will be used as the default collation

Compile

public XsltExecutable Compile(System.IO.Stream input)

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.

CompilePackage

public XsltPackage CompilePackage(System.IO.Stream input)

Compile a library package.

The source argument identifies an XML file 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.

@since 9.6

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.

CompilePackages

public IList<XsltPackage> CompilePackages(System.Collections.Generic.IList{System.String} sources)

Compile a list of packages.

Since 9.6

Parameters:
sources -
the collection of packages to be compiled, in the form of an Iterable
Returns:
the collection of compiled packages, in the form of an Iterable.

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 -
thePackage the package to be imported

ImportPackage

public void ImportPackage(XsltPackage thePackage,
string ,
string )

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 -
thePackage the package to be imported

LoadLibraryPackage

public XsltPackage LoadLibraryPackage(System.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(System.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

LoadExecutablePackage

public XsltExecutable LoadExecutablePackage(System.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(System.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

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.

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

Compile

public XsltExecutable Compile(System.IO.TextReader input)

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

Compile

public XsltExecutable Compile(System.Uri uri)

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

Compile

public XsltExecutable Compile(System.Xml.XmlReader reader)

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

Compile

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

Parameters:
node -
The document node or the outermost element node of the document containing the principal stylesheet module.
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.

CompileAssociatedStylesheet

public XsltExecutable CompileAssociatedStylesheet(XdmNode source)

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.