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 ( |
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 |
string | DefaultCollationName
The name of the default collation used by stylesheets compiled using this |
ErrorReporter | ErrorReporter
The |
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
Recommendation: disable this option unless you are confident that the stylesheet you are compiling is error-free. |
Processor | Processor
The |
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
|
bool | SchemaAware
The |
ResourceResolver | StylesheetModuleResolver
A |
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 SaxonJS 2.0 or later. |
string | XsltLanguageVersion
The |
Method Summary |
|
---|---|
void | ClearParameters ()
Clear the values of all stylesheet parameters previously set using |
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 |
XsltExecutable | Compile (Uri uri) Compile a stylesheet, retrieving the source using a URI. |
XsltExecutable | Compile (XmlReader reader)
Compile a stylesheet, delivered using an |
XsltExecutable | Compile (XdmNode node)
Compile a stylesheet, located at an |
XsltExecutable | CompileAssociatedStylesheet (Uri uri, string media) Locate and compile a stylesheet identified by an |
XsltExecutable | CompileAssociatedStylesheet (XdmNode source) Locate and compile a stylesheet identified by an |
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 |
void | ImportPackage (XsltPackage thePackage) Import a library package. Calling this method makes the supplied package available
for reference
in the |
void | ImportPackage (XsltPackage thePackage, string packageName, string version) Import a library package. Calling this method makes the supplied package available
for reference
in the |
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
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:
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.
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
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
The ErrorReporter
to be used when reporting static errors in a stylesheet.
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.
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
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
The Processor
from which this XsltCompiler
was constructed
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.
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.
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
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
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 SaxonJS 2.0 or later.
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 Detail
ClearParameters
Compile
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 stylesheetReturns:
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
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
Uri baseUri)
throws
SaxonApiException
Compile a stylesheet supplied as a Stream, along with a base URI.
The BaseUri
property of the XsltCompiler
is ignored.
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 stylesheetbaseUri
- 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:
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
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, new Uri(); source.Close();Compile
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 stylesheetReturns:
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
is thrown.
Note that this will not contain useful error information; to capture details of
specific errors, nominate an ErrorReporter
to receive notifications.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:
String ss = "<xsl:stylesheet version='2.0'>....</xsl:stylesheet>"; TextReader source = new StringReader(ss); XsltExecutable q = compiler.Compile(source); source.Close();Compile
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:
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:
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.Compile
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:
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:
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.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.Compile
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:
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:
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.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.CompileAssociatedStylesheet
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:
XsltExecutable
which represents the compiled stylesheet object.Throws:
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.CompileAssociatedStylesheet
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:
XsltExecutable
which represents the compiled stylesheet object.Throws:
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.CompilePackage
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 compiledReturns:
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
Uri baseUri)
Compile a library package, supplying a stream and a base URI
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 XsltCompiler.ImportPackage(XsltPackage) or similar.
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 compiledbaseUri
- the base URI of the stream, used for resolving any relative referencesReturns:
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.GetUnderlyingCompilerInfo
Get the underlying CompilerInfo
object, which provides more detailed (but less stable) control
over some compilation options
Returns:
CompilerInfo
object, which holds compilation-time options. The methods on
this object are not guaranteed stable from release to release.
ImportPackage
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 importedImportPackage
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 importedpackageName
- name of the package to be importedversion
- version identifier for the package to be importedLoadExecutablePackage
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 URIReturns:
LoadLibraryPackage
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 URIReturns:
SetParameter
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).
Clear the values of all stylesheet parameters previously set using
SetParameter(QName, XdmValue)
. This resets the parameters to their initial ("undeclared") state